共用方式為

匯出活動 API

本檔案說明Security Copilot 管理員匯出 API 的 API 合約和預期輸出資料結構描述。

匯出 API 可讓工作區管理員以編頁格式匯出提示和提示回應。

驗證和授權

  • 授權：持有人權杖驗證
  • 所需權限：工作區擁有者/管理員

使用服務主體進行驗證

  1. 例如，建立應用程式註冊 (，使用類似) 的 mysecuritycopilotexportapp 名稱。

注意事項

只有現有的所有者才能執行此操作。

  1. 將新的服務主體新增為 Security Copilot 角色指派中的擁有者

    請參閱 Security Copilot 角色和指派。 Security Copilot 支援將許可權指派給可指派角色的群組 (RAG) ，因此請建立 RAG，然後將服務主體 (SP) 新增至其中，如下所示：

  2. 擷取服務主體的持有人權杖。

    使用 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 (v2 模式搭配 /.default) 的範例：

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 錯誤的要求 參數無效或缺少工作區/租用戶資訊
404 未找到 未啟用管理員匯出 API
500 內部伺服器錯誤 匯出期間的伺服器錯誤

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 錯誤的要求 參數無效或缺少工作區/租用戶資訊
404 未找到 未啟用管理員匯出 API
500 內部伺服器錯誤 匯出期間的伺服器錯誤

資料模型

基本回應屬性

這兩個匯出 API 都會傳回具有下列常見屬性的回應：

屬性 類型 描述
workspaceId string 匯出的工作區 ID
workspaceName string 匯出的工作區名稱
tenantId string 匯出的租用戶識別碼
sessionsContinuationToken string? 如果沒有更多資料，下一頁的權杖 (空值)
totalCount integer? 目前頁面中的項目總數
sessionCount integer 用於此請求的工作階段計數

Pagination

這兩個 API 都支援游標型分頁：

  1. 初始請求： 在沒有的情況下 continuationToken提出請求。
  2. 後續請求： 使用上一個回應中的內容 sessionsContinuationToken 。
  3. 資料結束： 當為 null 時 sessionsContinuationToken ，沒有更多可用的資料。

分頁範例

第一個請求

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