エクスポートアクティビティ API

このドキュメントでは、Security Copilot 管理 Export API の API コントラクトと予想される出力データスキーマについて説明します。

エクスポート API を使用すると、ワークスペース管理者は、ページ分割された形式でプロンプトとプロンプト応答をエクスポートできます。

承認と認証

承認: ベアラートークン認証
必要なアクセス許可: ワークスペース所有者/管理

サービスプリンシパルを使用した認証

アプリの登録を作成します (たとえば、 mysecuritycopilotexportapp などの名前を使用します)。
- Microsoft Entra ID クイックスタート: アプリの登録 (ポータル) を使用します。
- CLI を使用する場合は、チュートリアル「サービスプリンシパルの作成 (Azure CLI)」を使用して ID を作成します。
- 必要に応じて、アプリ登録に資格情報を追加します。資格情報 (クライアントシークレット/証明書) を追加します。クライアントシークレットの作成の詳細については、「クライアントシークレットの作成 (明示的な手順)」またはポータルガイドの「アプリを登録してサービスプリンシパル (ポータル)を作成する」を参照してください。

注:

これを行うことができるのは、既存の所有者のみです。

ロールの割り当てに新しいサービスプリンシパルを所有者として追加Security Copilot

「ロールと割り当てをSecurity Copilotする」を参照してください。 Security Copilotでは、ロール割り当て可能グループ (RAG) へのアクセス許可の割り当てをサポートしているため、RAG を作成し、次のようにサービスプリンシパル (SP) を追加します。
- ロール割り当て可能なグループを作成する
- グループに SP を追加する (いずれかを選択): ポータル - グループの管理 (メンバーの追加) または API — Microsoft Graph: グループメンバーの追加

サービスプリンシパルのベアラートークンを取得します。

Azure CLI とクライアントシークレットの使用例:

# Login as service principal (supports no-subscription tenants)
az login --service-principal -u 94e67e0c-7c41-4f5b-b5ae-f5b5918e2382 -p <client-secret> --tenant 536279f6-15cc-45f2-be2d-61e352b51eef --allow-no-subscriptions

# Retrieve access token for Security Copilot (v1 resource pattern)
az account get-access-token --resource https://api.securitycopilot.microsoft.com

参照:

ユーザーとしての認証

手順 2 と同様に所有者であることを確認し、Security Copilotスコープのベアラートークンを取得します。

Azure CLI ( /.default での v2 パターン) の使用例:

az account get-access-token --scope https://api.securitycopilot.microsoft.com/.default

リファレンス:

アクセストークン (CLI) と .default スコープを取得します。

所有者以外の応答

所有者以外の場合は、API 呼び出しに対して次の応答が返されます。

{
  "message": "Your role doesn\u0027t have access to the info requested. Contact a Security Administrator to change your role or try again with a different account. Learn more about copilot",
  "code": "403",
  "traceId": "0HNF1M54NKVJ3:00000041",
  "error": {
    "message": "Your role doesn\u0027t have access to the info requested. Contact a Security Administrator to change your role or try again with a different account. Learn more about copilot",
    "copilotErrorId": "doesNotHaveAccessToSecurityCopilot",
    "code": "403",
    "innerError": {
      "message": null,
      "date": "2025-08-22T19:32:04.4726177Z",
      "correlationId": "a83f0049-7f81-4a56-bf4c-f58d6ad4dd97"
    },
    "traceId": "0HNF1M54NKVJ3:00000041"
  }
}

API エンドポイント

1. エクスポート API のプロンプト

エンドポイント

https://api.securitycopilot.microsoft.com/exports/prompts

GET /exports/prompts

クエリパラメーター

該当なし

要求の例

GET /exports/prompts?sessionCount=500&startDate=2024-01-01T00:00:00Z&endDate=2024-12-31T23:59:59Z
Authorization: Bearer <token>

応答スキーマ

成功応答 - (200 OK)

{
  "workspaceId": "string",
  "workspaceName": "string",
  "tenantId": "string",
  "prompts": [
    {
      // Prompt object schema (see Framework.Models.Prompt)
    }
  ],
  "sessionsContinuationToken": "string?",
  "totalCount": "integer?",
  "sessionCount": "integer"
}

エラーコードとメッセージ

状態コード	エラーコード	エラーメッセージ
400	要求が正しくありません (Bad Request)	無効なパラメーターまたはワークスペース/テナント情報がありません
404	見つかりません (Not Found)	エクスポート API が有効になっていない管理
500	内部サーバーエラー (Internal Server Error)	エクスポート中のサーバーエラー

2. 評価エクスポート API

エンドポイント

https://api.securitycopilot.microsoft.com/exports/evaluations

GET /exports/evaluations

クエリパラメーター

パラメーター	型	必須	既定値	説明
`sessionCount`	`integer`	いいえ	`100`	フェッチするセッションの数 (範囲: 1 ~ 1000)。
`continuationToken`	`string`	不要	`null`	改ページのトークン。
`startDate`	`DateTimeOffset`	不要	`null`	開始日フィルター (包括的な ISO 形式)。
`endDate`	`DateTimeOffset`	不要	`null`	終了日フィルター (包括的な ISO 形式)。
`orderByDescending`	`boolean`	不要	`false`	降順で結果を並べ替えます。

要求の例

GET /exports/evaluations?sessionCount=200&continuationToken=abc123
Authorization: Bearer <token>

応答スキーマ

成功応答 - (200 OK)

{
  "workspaceId": "string",
  "workspaceName": "string",
  "tenantId": "string",
  "evaluations": [
    {
      // Evaluation object schema
    }
  ],
  "sessionsContinuationToken": "string?",
  "totalCount": "integer?",
  "sessionCount": "integer"
}

エラーコードとメッセージ

状態コード	エラーコード	エラーメッセージ
400	要求が正しくありません (Bad Request)	無効なパラメーターまたはワークスペース/テナント情報がありません
404	見つかりません (Not Found)	エクスポート API が有効になっていない管理
500	内部サーバーエラー (Internal Server Error)	エクスポート中のサーバーエラー

データモデル

基本応答プロパティ

両方のエクスポート API は、次の共通プロパティを持つ応答を返します。

プロパティ	型	説明
`workspaceId`	`string`	エクスポートされるワークスペース ID
`workspaceName`	`string`	エクスポートされるワークスペース名
`tenantId`	`string`	エクスポートされるテナント ID
`sessionsContinuationToken`	`string?`	次のページのトークン (データがそれ以上ない場合は null)
`totalCount`	`integer?`	現在のページのアイテムの合計数
`sessionCount`	`integer`	この要求に使用されるセッション数

改ページ

どちらの API でも、カーソルベースの改ページ位置がサポートされています。

初期要求:continuationTokenなしで要求を行います。
後続の要求: 前の応答の sessionsContinuationToken を使用します。
データの終わり:sessionsContinuationTokenが null の場合、それ以上データを使用できません。

改ページの例

最初の要求

GET /exports/prompts?sessionCount=100

応答には continuationToken が含まれます

{
  "sessionsContinuationToken": "[{\"compositeToken\":{\"token\":null,\"range\":{\"min\":\"05C1D1D5378D58\",\"max\":\"05C1D3CFCBB964\"}},\"resumeValues\":[\"2025-08-01T23:49:27.8981554+00:00\"],\"rid\":\"xQAMAIZUJBs7BEAAAADABQ==\",\"skipCount\":1}]",
  "prompts": [...],
  // ... other properties
}

トークンを使用した次の要求 (URL エンコード)

GET /exports/prompts?sessionCount=100&continuationToken=%5B%7B%22compositeToken%22%3A%7B%22token%22%3Anull%2C%22range%22%3A%7B%22min%22%3A%2205C1D1D5378D58%22%2C%22max%22%3A%2205C1D3CFCBB964%22%7D%7D%2C%22resumeValues%22%3A%5B%222025-08-01T23%3A49%3A27.8981554%2B00%3A00%22%5D%2C%22rid%22%3A%22xQAMAIZUJBs7BEAAAADABQ%3D%3D%22%2C%22skipCount%22%3A1%7D%5D

注:

サービスプリンシパルにサブスクリプションがない場合は、 az login が見つからなかったことを報告する場合があります。この場合は、 --allow-no-subscriptionsを含めます。
トークンの場合は、認証フローに応じて、 --resource https://api.securitycopilot.microsoft.com (v1) または --scope https://api.securitycopilot.microsoft.com/.default (v2) を使用できます。「アクセストークンの取得 (CLI)」と「.default スコープ」を参照してください。

次の方法で共有

エクスポート アクティビティ API

承認と認証

サービス プリンシパルを使用した認証

ユーザーとしての認証

所有者以外の応答

API エンドポイント

1. エクスポート API のプロンプト

エンドポイント

クエリ パラメーター

要求の例

応答スキーマ

2. 評価エクスポート API

エンドポイント

クエリ パラメーター

要求の例

応答スキーマ

データ モデル

基本応答プロパティ

改ページ

改ページの例

関連情報

その他のリソース

エクスポートアクティビティ API

サービスプリンシパルを使用した認証

クエリパラメーター

クエリパラメーター

データモデル