コンテンツにスキップ

REST API

新しいHTTP/JSON APIは、JSON-RPCエンベロープなしでMCPカタログからビジネス操作を公開します。利用可能な操作はインストールされているサーバーバージョンに依存します。これは操作指向のAPIであり、各データベーステーブルごとの別個のCRUDインターフェースではありません。

アクセスと権限

既存のMCP APIキーをAuthorization: Bearer <key>として送信します。MCPはグローバルおよびプロジェクトで有効化されている必要があります。プロジェクトキーにはX-ZTM-Project-UniqueIdも必要です。グローバルキーはプロジェクト操作のために明示的なプロジェクトアクセスが必要です。ブラウザーおよびWindowsのサインインはAPIキーの代わりにはなりません。

ユーザー権限、書き込みゲート、許可された機能およびデモ制限はMCPと同様に適用されます。ローカルテスト以外ではHTTPSを使用してください。キーをURL、ソースコード、ログに絶対に含めないでください。詳細は安全な操作およびMCPをご覧ください。

操作を検出する

リクエスト 結果
GET /api/v1/operations 現在のキーとプロジェクトで利用可能な操作および入力契約
GET /api/v1/operations/{operationId} 1つの操作契約
GET /api/v1/openapi.json 同じ認証コンテキストのOpenAPI 3.1
POST /api/v1/operations/{operationId} 引数オブジェクトをリクエストボディとして実行
POST /api/v1/resources/read キーに紐づくエクスポートリソースを読み取る

OpenAPIは利用可能な各操作に具体的なPOSTパスを含みます。入力はMCPと同じスキーマを使用します。ライブラリの健全性、結果の安定性、プロジェクト添付ファイルおよびリリース比較/スナップショットには型付き出力スキーマがあります。他の動的クエリ/アクション結果は拡張可能なJSON契約を保持します。カタログには共有クエリおよびアクションツールが含まれており、すべてのWebメニュー項目に専用エンドポイントがあるわけではありません。

$headers = @{
    Authorization = "Bearer $env:ZTM_API_KEY"
    'X-ZTM-Project-UniqueId' = $env:ZTM_PROJECT_UNIQUE_ID
}
$baseUrl = 'https://your-server.example'
Invoke-RestMethod "$baseUrl/api/v1/operations" -Headers $headers
Invoke-RestMethod "$baseUrl/api/v1/operations/ztm_usage_guide" `
    -Method Post -Headers $headers -ContentType 'application/json' -Body '{}'

これらの環境変数は呼び出し元のPowerShellスクリプトによって読み取られます。サーバーを自動的に構成するものではありません。プロジェクトは操作引数ではなくヘッダーでルーティングします。JSONボディは1MiBおよび32階層のネストに制限されます。重複するプロパティ名は拒否されます。

Office プレビュー設定を読み取る

グローバルMCP APIキーは、POST /api/v1/operations/ztm_admin_office_preview_settings_getおよび本文の{}を使用してインストールの有効なXLSXモードを読み取ることができます。例としてのレスポンスは{"xlsxPreviewMode":"HtmlTable"}であり、もう一つの可能な値はDevExpressPdfです。プロジェクトキーでは不十分です。この操作は読み取り専用です。設定を変更するにはサーバー管理を使用してください。

書き込みおよびエクスポートを行います

各操作のプレビューと明示的なコミット契約に従ってください。例えばztm_project_action_prepareおよびztm_project_action_commit。APIアクセスは業務承認の代替ではありません。プレビュー、冪等キーおよびコミットは同一ユーザーおよびプロジェクトコンテキストに結び付けてください。タイムアウト後は書き込みを盲目的に繰り返すのではなく、アクションの状態を確認してください。

エクスポートはresourceUriを返す場合があります。同じキーとプロジェクトを使用してPOST /api/v1/resources/read経由で{"uri":"<resourceUri>"}を通して読み取ってください。レスポンスにはテキストまたはBase64データとMIMEタイプを含むcontentsが含まれます。チケットは期限切れになるか一度の読み取りのみ許可される場合があります。リソースURIは機密として扱ってください。

エラー

エラーはHTTPステータスとapplication/problem+jsonを返し、codeおよびtraceIdを含みます:400 無効な入力、401 認証欠如または拒否、403 権限不足、404 利用不可のオブジェクトまたは操作、409 アクションの競合、413 サイズ超過の本文、415 非対応のコンテンツタイプ、500 内部障害。競合は自動再試行ではなくレビューが必要です。サポートにはtraceIdを提供し、キーや機密ペイロードは絶対に提供しないでください。

前提条件ルールとブロックされたテスト

ztm_project_queryはライブラリおよび計画された依存関係のためにruleを含みます:0 = ヒントのみ、1 = 成功必須、2 = 失敗してはならない。

既存のライブラリ依存関係を変更するにはztm_project_action_contextを使用し、次にztm_project_action_prepareでcapabilityId: project.test-case.dependency.set-ruleおよび引数testCaseId、dependencyId、ruleを指定してください。プレビューを確認し、ztm_project_action_commitで確定します。このキーには明示的な書き込み権限が必要です。作成は互換性を維持します:新しい関係はヒントとして開始し、そのルールは後で変更可能です。既存の計画および実行は自動的に同期されません。

POST /api/v1/operations/ztm_test_prerequisites_readは{"plannedVariantId":123}を使用して可視の計画済みテストを評価します。応答にはisBlocked、needsRecheckおよびblockersが含まれます。不可視または欠落した前提は名前で開示されず、hasHiddenPrerequisitesがそれを示します。この時点評価は実行権限を付与せず、個人の再テスト確認に代わるものではありません。同じ操作はMCPでも利用可能です。

プロジェクト添付ファイル

ztm_project_attachments_readはプロジェクトの添付ファイルとそのownerIdをoffsetおよびlimit(最大100)と共に一覧表示します。attachmentIdを指定してcontentBase64(最大32 MiB)をダウンロードしてください。アクティブなプロジェクト管理者またはプロジェクトマネージャーが必要です。動的リンクファイルは一覧表示されますが、この操作ではダウンロードできません。

書き込みには別途project.attachment.upload、project.attachment.updateまたはproject.attachment.delete機能が必要です。既存の計画添付権限はプロジェクトファイルアクセスを付与しません。返されるownerIdを使用してください。これはプロジェクトで0の場合があります。

  1. アップロード:ztm_project_attachment_stageをtargetKind: "project"、targetId: <ownerId>、fileName、mimeTypeおよびcontentBase64で呼び出します。既存のステージング制限はファイルごとに512 KiBです。
  2. 機能を持つztm_project_action_prepareを呼び出し、新しいidempotencyKeyおよびargumentsを使用します。アップロード引数:ownerKind: "project"、ownerId、チケットのattachmentReferenceId、オプションのdisplayNameおよびremarks。メタデータ更新:ownerKind、ownerId、attachmentId、displayName、remarks。削除:ownerKind、ownerId、attachmentId。
  3. プレビューを確認し、同じキーを持つztm_project_action_commitを通じて承認してください。同時編集が発生すると競合が生じます。成功したコミットの再実行は別の添付ファイルを作成しません。

リリース比較と決定

ztm_release_snapshots_listは読み取り可能な保存済み比較をオプションのtargetIdフィルター付きで一覧表示します。返されたNextCursorをcursorとして渡すと次ページを読み取れます。

ztm_release_compare は baseId、targetId、明示的な baseRunIds/targetRunIds およびオプションの baseScopeRunIds/targetScopeRunIds 配列の { "runId": 123, "scopeRunId": 123 } を受け入れます。オプションの baseSnapshotId/targetSnapshotId は保存された証拠を選択します。Web比較を返し、Fingerprint を含み、同じ選択およびオブジェクト権限ルールを適用します。

証拠を保存するには、明示的にproject.release-review.snapshot-createに許可を与え、準備/コミット引数query(比較引数オブジェクト)、nameおよびfingerprintを用意してください。証拠の変更は拒否されます。保存された比較、decisionRevisionおよび決定履歴はztm_release_snapshot_readとsnapshotIdで読み取り、historyBeforeRevisionページで古い決定を確認してください。

決定にはproject.release-review.decision-record、プロジェクト管理権限、および明示的な人間の承認が必要です。準備はsnapshotId、targetId、revision、outcome(1承認、2条件付き承認、3拒否、4取り消し)、responsibleUserId、comment、openPoints(1行につき1つ)、humanConfirmed: trueを受け入れます。サーバーは認証された実行者を記録し、このフラグは実際の人間の承認に代わるものではありません。プレビューを確認し、その後コミットしてください。Webルールは引き続き適用されます:現在のリビジョン、適格な責任ユーザー、説明、完全なスコープ、変更されていない証拠。履歴プロジェクトコピーは新しい決定を受け取れません。

カバレッジと制限

REST と MCP は操作カタログを共有しています。これはすべての Web 機能を完全にカバーしていることを意味しません。プロジェクトの添付ファイルは別の書き込み契約を持ちますが、既存のテストケース、要件、テスト計画のアップロード契約は別のままです。保留中の操作は機能カタログに引き続き表示されます。

ブラウザの表示、ファイルピッカーダイアログ、およびインタラクティブログインは、別個のドメインエンドポイントを必要としません。実際の手動再テストの個人確認はテスターの代わりに自動生成されません。リリース概要/PDFおよび自動化インポートは既存の操作を使用し、RESTトランスポートはそれらのドメインカバレッジを拡張しません。 プロジェクト添付ファイルの書き込みおよびリリース比較/決定操作は上記の通り利用可能です。任意のサーバーパスおよびLocal BridgeファイルリンクはこれらのAPI操作の対象外です。スタンドアロンのバリアントコピーおよびマニフェストファイルのインポートは、レビューされたWeb実装では別個の操作ではありません。型付き出力はプロジェクト添付ファイルおよびリリース比較/スナップショットをカバーし、既存の動的クエリ/アクション出力は拡張可能なJSONであり、完全な型付きSDKモデルではありません。

テストケースのバージョン

テストケースのバージョニングはPOST /api/v1/operations/ztm_project_test_case_versionsを通じて利用可能です。現在のヘッドで境界付きリストにはoperation: "list"、testCaseIDおよびオプションのskipとtakeを使用してください。readはrevisionIDも必要とし、compareはotherRevisionIDを追加します。assetはrevisionIDとassetIDを使用し、base64エンコードされたバイトを返します。restore-previewはrevisionIDをexpectedHeadと照合します。

ztm_project_action_prepare、機能project.test-case-version.restore、および引数testCaseID、revisionID、expectedHead、オプションのnoteとoptionsを使用して復元の準備を行います。ztm_project_action_commitを通じて返されたトークンを確認してください。optionsには明示的に除外されたexcludedAttributeIDsおよびflattenUnavailableReusableStepsが含まれる場合があります。プロジェクトのバインディング、アクティブユーザーの識別、オブジェクトの権限、書き込みスコープ、およびデモ保護は引き続き適用されます。APIキーを例、ログ、またはシェル履歴に絶対に含めないでください。

ライブラリの健全性と結果の安定性

これらの読み取り操作はWebレポートと同じサービスおよびオブジェクト権限を使用します。書き込み権限は不要です。テストの変更、削除、実行は行いません。

操作 オプションのフィルター
ztm_library_health_read unitIdは子孫を含みまたは caseId; ageDays 1–36500(デフォルト180); reason; pageは1から; pageSize 1–100(デフォルト50)です。
ztm_test_stability_read testPlanId;testEnvironmentId(環境なしは0);fromUtc、toUtcは2026-11-08T12:00:00ZのようなUTCタイムスタンプ;lookbackRunsは1~200(デフォルト50)

例:POST /api/v1/operations/ztm_library_health_read と {"ageDays":180,"reason":"NoVisibleUsage","pageSize":25} の組み合わせ。型付きレスポンスには Findings、CandidateCount、ScannedCaseCount、IsComplete、Limit、Page、PageSize が含まれます。理由は NoVisibleUsage、NeverVisiblyExecuted、LongUnchanged、MissingTitle、MissingSteps、MissingExpectedResults、EmptyQuickContent、NoVariants です。理由は重複することがあります。可視の使用がないことは、プロジェクト全体でテストが未使用であることを示しません。長期間変更のない内容は自動的に廃止されません。分析は最大 2000 件の可視ケースと 20000 件の可視使用に制限されます。使用分析が不完全な場合、負の使用指標は抑制されます。

例:POST /api/v1/operations/ztm_test_stability_read と {"lookbackRuns":50} の組み合わせ。レスポンスには Series、FailureGroups、個別の Evidence とカウントの EligibleRuns、IncludedRuns、EligibleResults、IncludedResults、Truncated、InvalidEvidenceCount が含まれます。これは、完了済みの可視実行における各実行/ケース/バリアントの最新結果を使用し、完全な実行履歴は使用しません。最大で 20000 件の結果観察が分析されます。バリアント、環境、起源は分離され、ビルドの違いは可視のままです。ContentDifferences と ContentFingerprint は保存されたテストケース記述のみを比較し、完全な履歴仕様は比較しません。結果の変化は指標であり、不安定性の証明ではありません。失敗テキストの一致は共通原因の証明にはなりません。Origin:0 = 現在の自動化が検証済み、1 = その他または未検証の起源、2 = 変更または無効な自動化証拠。

表示されている入力の大文字小文字を使用してください。無効な範囲、タイムスタンプ、未知のフィルターは400を返し、読み取れない明示的なライブラリオブジェクトは403を返します。同じツールとフィルターはMCPでも利用可能です。

参照ベースライン

参照ベースラインはスコープオプション、一覧表示、履歴内容、現在の比較および保存ファイルに対して型付き操作を提供します。作成は明示的に付与されたproject.library-baseline.create権限を用いたprepare/commitで行い、編集、復元、削除操作はありません。ツール名、スコープ引数、リトライ規則およびAPIファイル応答の512 KiB制限についてはリンクされた章を参照してください。

計画ツリーとカスタム結果ステータス

ztm_project_planning_tree_readは許可された計画ツリーと利用可能な結果定義および実行フィルターを返します。リクエスト例:

{"resultDefinitionIds": [12, 15], "includeNoResult": true}

resultDefinitionsの実際のIDを使用してください。例のIDはプレースホルダーです。ステータスIDはORを使用し、オプションのtreeFilterObjectIdは実行をさらに制限します。選択が省略された場合、そのリクエストに対するフィルターはなく、保存されたUI設定に関係なく適用されません。結果はユーザーのツリー表示設定に従い、許可されたノードのみを返します。未知の明示的IDは拒否されます。読み取り操作は個人設定やテスト結果を変更しません。同じ契約はMCPを通じても利用可能です。

属性値の起源

既存の属性アクションについては、ztm_project_action_contextがMetadataをPromotedFieldsおよびObjectAttributesに追加します。これにはAttributeId、AttributeStyleFieldId、フィールド名、スタイルIDと名前、フィールドタイプ、所有者の種類とID、Entail、およびSourceKind(direct、inherited、default)が含まれます。未保存のデフォルトには所有者IDがありません。フィールド定義が欠落している場合は、元のフィールドIDを保持し、定義の詳細はnullとなります。

同じ情報はMCPおよびPOST /api/v1/operations/ztm_project_action_contextを通じて利用可能です。既存の属性アクションの権限および機能は引き続き適用されます。コンテキストアクセスは追加の読み取り権限を付与しません。パスワードフィールドは除外されます。コンテキストの読み取りはデフォルトを保持しません。属性は名前による継承と昇格フィールドの違いを説明します。

ターゲット結果のフィードバック

読み取り専用ツール ztm_result_feedback_read、ztm_result_feedback_preview および ztm_result_feedback_export は /api/v1/operations/ 以下の POST 操作としても利用可能です。それぞれに対応する読み取り能力 project.result-feedback.read、.preview または .export と選択されたオブジェクトへの読み取りアクセスが必要です。

read は testRunId を受け入れます。preview は resultItemIds(1から100のユニークID)を追加し、オプションで recipient、subject、message、externalReference および includeResultText(デフォルトは false)を追加します。応答にはレビュー済みコンテンツの Fingerprint が含まれます。export は同じ入力に加え expectedFingerprint、format(html または xlsx)およびオプションで language(de または en)を使用します。応答には FileName、ContentType および ContentBase64 が含まれます。

変更された内容は再プレビューが必要です。アクセスできない選択結果は出力全体を拒否し、部分的なサイレントエクスポートはありません。操作はメッセージを送信せず、受信者をプロジェクトに保存しません。ユーザーフローおよび内容制限についてはテスト結果を共有を参照してください。

ADロールルール

ztm_ldap_role_rules_getはインポート構成のルールを読み取り、ztm_ldap_role_rules_saveは期待されるリビジョンで保存し、ztm_ldap_role_rules_previewはメンバーシップ変更をプレビューします。ztm_ldap_import_runは保存されたルールを含む既存のADインポートを実行します。同じ操作はMCPツールでも利用可能です。

すべての呼び出しにはconfigurationIdが必要です。保存、プレビュー、インポートには最新の読み取り応答からのexpectedRevisionも必要です。保存は安定したルールID、有効状態、属性名、正確な値、役割、および専用のグループ名を含むrulesを受け入れます。呼び出し元はグループIDを選択しません。生成されたOpenAPI契約は完全なフィールドを記述します。

保存およびインポートは管理者キーが有効でプロジェクトアクセスおよび対応するスコープを持つ管理者書き込み操作です。プロジェクト管理権限もチェックされます。プレビュー変更はメンバーシップ不要ですが、設定されたディレクトリへのアクセスが必要です。公開デモはこれらの管理呼び出しをブロックします。リビジョン競合時は、古い設定で盲目的にインポートを再試行せず、設定を再度読み込みレビューしてください。

鮮度および手動のリリース欠陥評価

ztm_release_evidence_read、ztm_release_evidence_configure、およびztm_release_evidence_observeは、年齢制限や保存制限、明示的な手動欠陥評価を読み取ります。対応するMCP契約と現在のexpectedRevisionを使用します。競合(409)後は再読み込みし、盲目的な再試行は行わないでください。observeには、概要のreport.EvidenceAssessment.Defectsからの実際のreferenceIdおよびsourceFingerprintに加え、state、criticality、observedUtc(明示的なタイムゾーン付き)、およびcommentが必要です。

専用書き込みスコープはproject.release-evidence.configureおよびproject.release-evidence.observeです。有効なプロジェクト書き込みおよびWebと同じリリース管理権限も適用されます。ステートメントには記録ユーザーと時間が含まれ、自動的に検証されたトラッカーデータではなく、明示的な人間の指示なしに作成してはなりません。ztm_release_overview_readは新しいライブキャプチャ用にEvidenceAssessmentを追加します。既存のassessmentレベルおよび理由に組み込まれています。履歴キャプチャは変更されません。詳細はリリース比較と承認を参照してください。

構造化されたテストデータセット

これらのMCPツールは、同じ契約でPOST /api/v1/operations/<tool-name>としても利用可能です。機能ルールについてはテストデータマトリックスを参照してください。

ツール(プレフィックスztm_test_data_set_) 引数 結果
list なし itemsで許可されたデータセット
read dataSetId リビジョンと安定した行IDを持つデータセット
save data, expectedRevision, confirmed:true 新しいリビジョンを持つ永続化されたデータセット
delete dataSetId, expectedRevision, confirmed:true deleted:true;参照されたデータは保護されたままです。
binding variantId bindingまたはnull
preview variantId, dataSetId, rowId テキスト、診断およびフィンガープリントは変更なし
apply プレビュー引数、expectedFingerprint、confirmed:true 永続化されたバインディングと解決済みテキスト
unbind variantId, expectedFingerprint, confirmed:true unbound:true;解決されたテキストは保持されます。
export dataSetId XLSX fileName、mimeType、contentBase64
import_preview dataSetId, expectedRevision, contentBase64 保存されていない提案;明示的にsaveを呼び出してください

データセットフィールドはId、TestUnitId、Name、Revision、ColumnsおよびRowsです。行にはIdおよびValuesが含まれます。作成時にはIdにゼロGUID、expectedRevisionに空の値を使用します。行には一意の非ゼロGUIDが必要です。更新には事前に読み取ったリビジョンが必要です。競合後は再度読み取り、変更を確認してください。

4つの書き込み操作には個別のスコープproject.test-data-set.save、.delete、.applyまたは.unbind、許可されたプロジェクト書き込みおよび関連オブジェクト権限が必要です。インポートプレビューは永続化されず、Webと同様に所有者編集権限が必要です。デモ制限はAPIにも適用されます。RESTはブラウザクッキーではなくベアラキーを使用しCSRFトークンは不要です。Webフォームは依然としてアンチフォージェリトークンを必要とします。

XLSXは1つのワークシートを使用し、最初の列に_RowIdを配置します。数式、マクロ、外部参照は拒否されます。制限:4 MiBのXLSX、16 MiBの展開コンテンツ、30のデータ列、1,000行、セルあたり32,767文字、データセットあたり2 MiB。保存およびインポートプレビューのみ最大6 MiBのJSON転送(Base64含む)を受け入れます。他の操作は既存の1 MiB制限を維持します。

binding はソースが利用できない凍結されたバインディングも返します:SourceAvailable:false と診断用の SourceUnavailable。保存されたテキストはバリアントが読み取り可能な場合に読み取り可能なままです。更新にはソースへのアクセスが必要で、バインディング解除は現在のバインディングフィンガープリントを使用します。

他のテストツールからインポートする

現在の開発ビルドは他のツールからの移行向けにPOST /api/v1/operations/ztm_vendor_migration_previewおよびPOST /api/v1/operations/ztm_vendor_migration_applyを提供しています。同等のMCPツールもこの契約を共有しています。

targetUnitId、sourceKey、workbookBase64、および任意でattachmentsZipBase64を提供してください。

ツールから出力した表を使う場合は、provider(testrail、xray、zephyr、qase、neutral のいずれか)と、拡張子が .xlsx または .csv の fileName を指定します。ファイルのバイト列は引き続き workbookBase64 で送信します。既定では検出された列が使われます。mapping で ExternalId、Name、FolderPath、Description、Prerequisites、Steps、ExpectedResult、AttachmentPath を既存の見出しに割り当てられます。プレビューの適用時には、同じソース、ファイル、マッピングを指定します。これらのフィールドを省略した中立形式 XLSX リクエストの動作は従来どおりです。

プレビューは読み取り機能project.vendor-migration.previewを使用します。プロジェクトの読み取りキーで十分です。対象でケースを作成する権限もユーザーに必要です。プレビューには書き込みスコープは不要です。保存せずにFingerprint、Items、DiagnosticsおよびCanApplyを返します。CanApplyがtrueの場合のみ適用してください。変更後は新しいプレビューを確認してください。

適用するには、同じファイルとプレビューフィンガープリントをexpectedFingerprintとして、新しいUUIDをoperationIdおよびconfirmed: trueとして送信してください。ネットワーク中断後に同じUUIDで同じ操作を再試行してください。

適用には書き込みアクションの有効化とproject.vendor-migration.applyスコープが必要です。オブジェクト権限とデモ制限はWebワークフローに準じます。Base64データを含むJSONリクエストは6 MiBに制限されています。

プロジェクトデータベースがビジー状態の場合、RESTはHTTP 503をDatabaseBusyおよびRetry-After: 2と共に返します。MCPはエラーデータ内でactionErrorCode: "DatabaseBusy"およびretryAfterSeconds: 2を返します。アクセスが解放された後、同じoperationIdを使って同じリクエストを再試行してください。保存されたレシートは、権限と現在の内容を再確認した後に返され、追加のコピーは作成されません。

テスト実行の引き継ぎ

  1. ztm_project_action_context に {"capabilityId":"project.test-run.handover","itemKind":"test-run","itemId":23} を渡し、引き継ぎ先の候補と現在のリビジョンを取得します。
  2. Recipients からユーザーの ID を選び、Revision を expectedRevision として渡します。例えば、{"runId":23,"recipientUserId":7,"expectedRevision":0} を指定して ztm_run_handover または POST /api/v1/operations/ztm_run_handover を呼び出します。

Applied は引き継ぎが保存されたことを示します。メールの送信結果は mailStatus に Sent、NotConfigured、MissingAddress、MissingLink、Failed のいずれかで返ります。現在の担当者を指定して再実行すると AlreadyApplied が返り、mailStatus は null になります。競合(HTTP 409)が発生した場合は、コンテキストを再取得してください。

書き込みスコープ project.test-run.handover を持つ個人用プロジェクトキーを使用します。キーの所有者には対象のテスト実行を編集する権限が必要です。グローバルキーとデモ環境では引き継ぎを実行できません。

テストのステータスを共有する

ztm_share_link_create はテスト実行、計画、リリースの閲覧専用リンクを作成します。書き込みスコープ project.share-link.create が必要です。秘密情報は再表示できないため、作成時に返されたリンクを保存してください。リンクを個別に取り消すには、スコープ project.share-link.revoke で ztm_share_link_revoke を使用します。

{"targetKind":"run","targetId":"23","validityDays":7,"requestId":"869744c5-8cdb-45e1-a300-918d308345f1","includeErrors":false,"includeFindings":false}

REST では、それぞれ /api/v1/operations/ztm_share_link_create と /api/v1/operations/ztm_share_link_revoke に POST します。該当するスコープと対象への権限を持つ、プロジェクトの個人用キーが必要です。グローバルキーやデモ環境ではリンクを作成したり取り消したりできません。ステータスを共有も参照してください。

複数のテストケースを編集する

MCP の ztm_library_bulk_update または POST /api/v1/operations/ztm_library_bulk_update を呼び出します。属性の設定内容を確認する例です。

{"operation":"preview","action":"attribute","caseIds":[12,31],"attributeName":"Modul","attributeValue":"Checkout"}

Rows を確認し、operation を apply に変更します。同じパラメーターに、返された Fingerprint を fingerprint として追加します。再試行する場合は requestId に UUID を指定します。サーバーが処理を保持している間は、同じ ID と引数で再送すると元の処理結果が返ります。HTTP 409 の場合は再度プレビューしてください。

move と archive には targetUnitId、review には reviewGroupId、variant には variantValueIds を指定します。アーカイブ先にはアーカイブとして指定したユニットが必要です。1 回につき最大 200 件です。project.test-library.bulk-update スコープを持つ個人用プロジェクトキーが必要です。ケースごとに現在の権限が確認されます。グローバルキーおよびデモでは利用できません。

{"operation":"undo","requestId":"<結果のRequestId>"} と同じプロジェクトキーを使用すると、サーバーのメモリに操作が残っている間、移動または属性変更を取り消せます。権限とその後の変更を再確認します。

project.test-unit.update の引数に任意の真偽値 isArchive を指定すると、ユニットをアーカイブとして設定できます。itemId と title を指定する既存のプレビュー・確定手順を使用します。省略すると設定を保持します。Project Knowledge のユニット読み取りでも isArchive を取得できます。

選択した指摘を再テストする

ztm_library_retest または POST /api/v1/operations/ztm_library_retest を使用します。

  1. operation: "options" と findings を送信し、利用可能な元のテスト実行、環境、担当者を取得します。各指摘には caseId、plannedCaseId、resultId のいずれかを指定し、既知の variantId、planId、runId も渡します。候補が複数ある場合は明示的に選択します。
  2. operation: "preview" に同じ選択内容と planId、runId、environment、testerId を指定します。Items には必須の前提条件を含む対象バリアントが表示されます。Skipped は除外された指摘をゼロから始まる選択インデックスで示します。古いテンプレートを使用すると明示的に決めた場合のみ acceptOldTemplate: true を指定します。
  3. operation: "create" に同じ入力と、返された Fingerprint を fingerprint、RequestId を requestId として渡します。結果には RunId、Url、除外された指摘が含まれます。通信が途切れた場合は同じ要求 ID で再試行し、重複作成を防ぎます。

プレビューはプロジェクトとユーザーに紐づき、30 分で期限切れになります。選択、権限、内容が変わった場合は新しいプレビューが必要です。1 回の要求は最大 200 件で、既存の元実行が必要です。任意の tab(health、impact、results)を指定すると、そのタブの利用可否も確認します。

書き込みスコープ project.test-library.retest を持つ個人プロジェクトキーと、選択した計画で実行を作成する権限が必要です。グローバル管理者キーと公開デモモードは使用できません。既存ツールと project.planned-test-case.synchronize-from-library による同期は変更されません。

対象のコメント

ztm_comment_read は、対象のコメントとアクティビティを取得します。kind(test-case、requirement、run、result)と id を指定します。offset と activityOffset でそれぞれのページを取得できます。commentId を指定すると、そのコメントがあるページを取得できます。返された Markdown はユーザーが入力したコンテンツとして扱います。

ztm_comment_add は、クライアント側で生成した UUID を commentId に指定して markdown を保存します。返信する場合は parentId を指定します。mentionUserIds を使うと、明示的に選択した閲覧権限のあるプロジェクトユーザーに通知できます。本文には対象ユーザーへのメンションが必要です。再試行時は同じ UUID と内容を使います。Created は新規作成と再試行を区別します。MailFailed はメールの送信に問題があったことを示します。コメントは保存されています。

両方の操作を使うには、プロジェクトでコメントを有効にする必要があります。どちらのツールも個人プロジェクトキーの有効な所有者として動作し、対象に対する現在の権限を確認します。投稿にはプロジェクトへの書き込みアクセスとスコープ project.comments.add が必要です。REST では POST /api/v1/operations/ztm_comment_read と POST /api/v1/operations/ztm_comment_add を使います。Web での操作

リリースのカバレッジを読み取る

MCP の ztm_coverage_matrix_read または POST /api/v1/operations/ztm_coverage_matrix_read を使用します。閲覧可能なリリースの一覧を取得する場合は releaseId を省略します。対象を指定する場合は releaseId に UUID を設定し、必要に応じて filter に all、without-test、without-result、failed のいずれかを指定します。個人のプロジェクトキーが必要です。閲覧権限のあるデータだけを取得します。

テスト実行から再テストを作成する

MCPツール ztm_retest_create とRESTの POST /api/v1/operations/ztm_retest_create は同じ引数を使用します。最初に選択内容をプレビューします。次の例は、失敗したバリアントとブロックされたバリアントに加えて、未テストのバリアントも対象にします。

{"mode":"preview","sourceRunId":36,"includeUntested":true}

RequestedCount、追加が必要な前提バリアント数(RequiredCount)、Errors を確認します。作成時には、そのプレビューの環境(Environment)、Testers に含まれるテスターのID、ComparisonToken を使用します。例の値は実際の値に置き換え、新規の作成要求ごとにUUIDを生成してください。RequiresOldTemplate が真の場合、古いテンプレートを使用するには acceptOldTemplate: true で明示的に承認する必要があります。

{
  "mode": "create",
  "sourceRunId": 36,
  "includeUntested": true,
  "environment": "Staging",
  "testerId": 7,
  "comparisonToken": "<ComparisonToken>",
  "creationId": "179e6928-a673-4dac-acae-b913914a13df"
}

応答の testRunId は、作成された未開始のテスト実行を示します。通信が切れた場合は、creationId を含めて同じ内容の要求を再送します。どちらのモードにも、書き込みの有効化、project.retest.create スコープ、および元のテスト実行の表示と新しい実行の作成に必要なプロジェクト権限とオブジェクト権限が必要です。デモ環境の制限も適用されます。Webダッシュボードでの操作を参照してください。

テスト結果から課題を作成する

ztm_issue_create_from_result · POST /api/v1/operations/ztm_issue_create_from_result

個人用の書き込みスコープ project.defect.create で MCP ツールまたは同名の REST 操作を使用します。testCaseId は計画済みバリアントの ID です。構造化手順、Quick の行、リスト項目の stepIndex は 0 から始まります。全体結果や自由記述では省略します。

{"mode":"prepare","testRunId":40,"testCaseId":371,"stepKind":"structured","stepIndex":3}

返されたフィールドと添付ファイルの候補を確認します。確認後、返された RequestId を requestId として、選んだフィールド値とテスト結果の添付 ID を送信します。

{"mode":"create","testRunId":40,"testCaseId":371,"requestId":"4c2ef7c8-b3a2-43e4-a721-6f04bb164b42","attachmentIds":[38]}

Retryable の場合は、トラッカーが復旧してから同じ ID で再試行します。Unknown の場合はトラッカーを確認し、既存の番号を existingIssueReference で指定します。LinkPending の場合は同じリクエストを再送信して既知の課題をリンクします。スクリーンショットの貼り付けには Web ダイアログを使用します。