共用方式為

匯出活動 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 匯出的租戶 ID
sessionsContinuationToken string? 如果沒有更多資料 (，下一頁的令牌會為空)
totalCount integer? 本頁項目總數
sessionCount integer 此請求所使用的會話計數

Pagination

兩個 API 都支援游標分頁：

  1. 初步請求： 請不要 continuationToken。
  2. 後續請求： 參考 sessionsContinuationToken 前面的回覆。
  3. 資料結束： 當 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