导出活动 API

本文档介绍Security Copilot 管理员导出 API 的 API 协定和预期的输出数据架构。

导出 API 使工作区管理员能够以分页格式导出提示和提示响应。

身份验证和授权

• 授权：持有者令牌身份验证
• 所需权限：工作区所有者/管理员

使用服务主体进行身份验证

1. 例如，创建应用注册 (使用) 等mysecuritycopilotexportapp名称。

   • 使用Microsoft Entra ID 快速入门：) (门户注册应用。

   • 如果首选 CLI，请通过教程创建标识： (Azure CLI) 创建服务主体 。

   • 根据需要向应用注册添加凭据： ) 添加凭据 (客户端机密/证书 。 有关客户端机密的分步创建，请参阅 创建客户端机密 (显式步骤) 或门户指南 注册应用并创建服务主体 (门户) 。

2. 将新的服务主体添加为Security Copilot角色分配中的所有者

   请参阅Security Copilot角色和分配。 Security Copilot支持 (RAG) 向可分配角色的组分配权限，因此请创建 RAG，然后将服务主体 (SP) 添加到其中，如下所示：

   • 创建可分配角色的组

   • 将 SP 添加到组 (选择) ： 门户—管理组 () 添加成员 或 API—Microsoft Graph：添加组成员

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
   

参考：

• 以 SP (CLI) 身份登录
• (CLI) 获取访问令牌
• .default 范围说明

以用户身份进行身份验证

确保你是所有者（类似于步骤 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

查询参数

N/A

请求示例

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"
}

错误代码和消息

2. 评估导出 API

端点

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

GET /exports/evaluations

查询参数

请求示例

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"
}

错误代码和消息

数据模型

基本响应属性

这两个导出 API 都返回具有以下常见属性的响应：

分页

这两个 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

References

• ) (门户注册应用
• 创建 SP (CLI 教程)
• (客户端机密/证书) 添加凭据
• 创建客户端机密 (显式步骤)
• (Alt) 门户中创建客户端密码
• Security Copilot角色 & 分配)
• 将服务主体添加到组 (门户)
• 将服务主体添加到组 (API)
• 以 SP (CLI) 身份登录
• (CLI) 获取访问令牌