Exportar API de atividade

Este documento descreve os contratos de API e os esquemas de dados de saída esperados para as APIs de exportação do Security Copilot Administração.

As APIs de exportação fornecem aos administradores de espaço de trabalho a capacidade de exportar prompts e respostas de prompt em um formato paginado.

Autenticar e autorizar solicitações da API de Atividade de Exportação

• Autorização: autenticação de token de portador
• Permissões necessárias: Proprietário / Administrador do workspace

Autenticar com uma entidade de serviço

1. Crie um registro de aplicativo (por exemplo, use um nome como mysecuritycopilotexportapp).

   • Use o início rápido do Microsoft Entra ID: Registrar um aplicativo (portal).

   • Se você preferir a CLI, crie a identidade por meio do tutorial: Criar uma entidade de serviço (CLI do Azure).

   • Adicione credenciais ao registro do aplicativo conforme necessário: Adicione credenciais (segredo do cliente/certificado). Para obter uma criação passo a passo de segredo do cliente, consulte Criar segredo do cliente (etapas explícitas) ou o guia do portal, Registrar um aplicativo e criar uma Entidade de Serviço (portal).

   Observação

   Somente os Proprietários existentes podem realizar a ação específica.

2. Adicionar a nova entidade de serviço como proprietária nas atribuições de função do Security Copilot

   Confira, Funções e atribuições do Security Copilot. O Security Copilot dá suporte à atribuição de permissões a RAGs (grupos atribuíveis a funções), portanto, crie um RAG e adicione sua entidade de serviço (SP) a ele da seguinte maneira:

   • Criar um grupo atribuível à função

   • Adicione o SP ao grupo (escolha uma das opções): Portal — Gerenciar grupos (adicionar membros) ou API — Microsoft Graph: adicionar membro do grupo

3. Recupere um token de portador para a entidade de serviço.

   Exemplo usando a CLI do Azure e um segredo do cliente:

   # 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
   

Autenticar como usuário

Verifique se sua conta de usuário tem a função Proprietário do Security Copilot antes de recuperar um token de portador.

• Exemplo usando a CLI do Azure (padrão v2 com /.default):

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

Conteúdo relacionado

• Entrar como SP (CLI)
• Obter token de acesso (CLI)
• .default Escopo explicado
• Obter token de acesso (CLI) e .default escopo.

Comportamento de resposta para não proprietários

Para não proprietários, a seguinte resposta é retornada para chamadas de 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"
  }
}

Pontos de extremidade da API

Prompts Exportar API

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

GET /exports/prompts

Parâmetros de consulta

N/D

Exemplo de solicitação

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

Esquema de resposta

Resposta de sucesso - (200 OK)

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

Mensagens e códigos de erro

Avaliações Exportar API

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

GET /exports/evaluations

Parâmetros de consulta

Exemplo de solicitação

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

Esquema de resposta

Resposta de sucesso - (200 OK)

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

Mensagens e códigos de erro

Modelos de dados

Propriedades de resposta base

Ambas as APIs de exportação retornam respostas com estas propriedades comuns:

Paginação

Ambas as APIs dão suporte à paginação baseada em cursor:

1. Solicitação inicial: Fazer solicitação sem continuationToken.
2. Solicitações subsequentes: Use sessionsContinuationToken da resposta anterior.
3. Fim dos dados: Quando sessionsContinuationToken é nulo, não há mais dados disponíveis.

Exemplo de paginação

Primeira solicitação

GET /exports/prompts?sessionCount=100

A resposta inclui 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
}

Próxima solicitação usando token (codificada por 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

Conteúdo relacionado

Use os seguintes artigos para orientação:

• Registrar um aplicativo (portal)
• Criar SP (tutorial da CLI)
• Adicionar credenciais (segredo do cliente/cert)
• Criar segredo do cliente (etapas explícitas)
• (Alt) Criar segredo do cliente no portal
• Security Copilot funções & atribuições)
• Adicionar Entidade de Serviço a um grupo (portal)
• Adicionar Entidade de Serviço a um grupo (API)
• Entrar como SP (CLI)
• Obter token de acesso (CLI)