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

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

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

エクスポート アクティビティ API 要求の認証と承認

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

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

  1. アプリの登録を作成します (たとえば、 mysecuritycopilotexportapp などの名前を使用します)。

    注:

    特定のアクションを実行できるのは、既存の所有者だけです。

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

    「ロールと割り当てをSecurity Copilotする」を参照してください。 Security Copilotでは、ロール割り当て可能グループ (RAG) へのアクセス許可の割り当てをサポートしているため、RAG を作成し、次のようにサービス プリンシパル (SP) を追加します。

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

    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

ユーザーとしての認証

ベアラー トークンを取得する前に、ユーザー アカウントにSecurity Copilot所有者ロールがあることを確認します。

  • Azure CLI の使用例 (/.defaultでの v2 パターン):
az account get-access-token --scope https://api.securitycopilot.microsoft.com/.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": "aaaa0000-bb11-2222-33cc-444444dddddd"
    },
    "traceId": "0HNF1M54NKVJ3:00000041"
  }
}

API エンドポイント

プロンプト Export 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) エクスポート中のサーバー エラー

Evaluations Export 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 でも、カーソルベースの改ページ位置がサポートされています。

  1. 初期要求:continuationTokenなしで要求を行います。
  2. 後続の要求: 前の応答の sessionsContinuationToken を使用します。
  3. データの終わり: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 スコープ」を参照してください。

関連コンテンツ

ガイダンスについては、次の記事を参照してください。

  • Last updated on