API de Atividade de Exportação

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

As APIs de exportação fornecem aos administradores da área de trabalho a capacidade de exportar pedidos e pedir respostas num formato paginado.

Autenticação e Autorização

• Autorização: Autenticação de tokens de portador
• Permissões Necessárias: Proprietário da Área de Trabalho/Administração

Autenticar com um Principal de Serviço

1. Crie um registo de aplicação (por exemplo, utilize um nome como mysecuritycopilotexportapp).

   • Utilize o início rápido Microsoft Entra ID: Registar uma aplicação (portal).

   • Se preferir a CLI, crie a identidade através do tutorial: Criar um principal de serviço (CLI do Azure).

   • Adicione credenciais ao registo da aplicação conforme necessário: Adicione credenciais (segredo/certificado do cliente). Para uma criação passo a passo do segredo do cliente, veja Criar segredo do cliente (passos explícitos) ou o guia do portal Registar uma aplicação e criar um Principal de Serviço (portal).

2. Adicionar o novo Principal de Serviço como Proprietário no Security Copilot atribuições de funções

   Veja Security Copilot funções e atribuições. Security Copilot suporta a atribuição de permissões a grupos atribuíveis a funções (RAGs), por isso, crie um RAG e, em seguida, adicione o Principal de Serviço (SP) ao mesmo da seguinte forma:

   • Criar um grupo atribuível a funções

   • Adicionar o SP ao grupo (escolha: Portal — Gerir grupos (adicionar membros) ou API — Microsoft Graph: Adicionar membro do grupo

3. Obtenha um token de portador para o principal de serviço.

   Exemplo com 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
   

Referências:

• Iniciar sessão como SP (CLI)
• Obter token de acesso (CLI)
• .default âmbito explicado

Autenticar como Utilizador

Certifique-se de que é proprietário, semelhante ao passo 2, e obtenha um token de portador no âmbito Security Copilot.

Exemplo de utilização da CLI do Azure (padrão v2 com /.default):

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

Referência:

Obter o token de acesso (CLI) e .default o âmbito.

Resposta como Não Proprietário

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

Pontos Finais da API

1. Prompts Exportar API

Ponto de extremidade

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

GET /exports/prompts

Parâmetros de Consulta

N/D

Exemplo de Pedido

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

Esquema de Resposta

Resposta com Êxito - (200 OK)

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

Códigos de erro e mensagens

2. API de Exportação de Avaliações

Ponto de extremidade

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

GET /exports/evaluations

Parâmetros de Consulta

Exemplo de Pedido

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

Esquema de Resposta

Resposta com Êxito - (200 OK)

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

Códigos de erro e mensagens

Modelos de Dados

Propriedades da Resposta Base

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

Paginação

Ambas as APIs suportam a paginação baseada no cursor:

1. Pedido Inicial: Faça um pedido sem continuationToken.
2. Pedidos Subsequentes: Utilize sessionsContinuationToken a partir da resposta anterior.
3. Fim dos Dados: Quando sessionsContinuationToken é nulo, não existem 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
}

Pedido seguinte com token (codificado 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

Referências

• Registar uma aplicação (portal)
• Criar SP (tutorial da CLI)
• Adicionar credenciais (segredo/certificado do cliente)
• Criar segredo do cliente (passos explícitos)
• (Alt) Criar segredo do cliente no portal
• Security Copilot funções & atribuições)
• Adicionar Principal de Serviço a um grupo (portal)
• Adicionar Principal de Serviço a um grupo (API)
• Iniciar sessão como SP (CLI)
• Obter token de acesso (CLI)