API de actividad de exportación

En este documento se describen los contratos de API y los esquemas de datos de salida esperados para las API de exportación de Security Copilot Administración.

Las API de exportación proporcionan a los administradores del área de trabajo la capacidad de exportar mensajes y solicitar respuestas en un formato paginado.

Autenticación y autorización

• Autorización: autenticación de token de portador
• Permisos necesarios: Propietario del área de trabajo/Administración

Autenticación con una entidad de servicio

1. Cree un registro de aplicación (por ejemplo, use un nombre como mysecuritycopilotexportapp).

   • Use el inicio rápido Microsoft Entra id. : Registro de una aplicación (portal).

   • Si prefiere la CLI, cree la identidad mediante el tutorial Creación de una entidad de servicio (CLI de Azure).

   • Agregue credenciales al registro de la aplicación según sea necesario: agregue credenciales (secreto de cliente/certificado). Para obtener una creación paso a paso del secreto de cliente, consulte Creación de un secreto de cliente (pasos explícitos) o la guía del portal, Registro de una aplicación y creación de una entidad de servicio (portal).

2. Agregar la nueva entidad de servicio como propietario en Security Copilot asignaciones de roles

   Vea, Security Copilot roles y asignaciones. Security Copilot admite la asignación de permisos a grupos asignables por roles (RAG), así que cree un RAG y, a continuación, agréguele la entidad de servicio (SP) de la siguiente manera:

   • Creación de un grupo asignable a roles

   • Agregar el SP al grupo (elija): Portal: Administración de grupos (agregar miembros) o API: Microsoft Graph: Agregar miembro del grupo

3. Recupere un token de portador para la entidad de servicio.

   Ejemplo de uso de la CLI de Azure y un secreto de 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
   

Referencias:

• Inicio de sesión como SP (CLI)
• Obtención del token de acceso (CLI)
• .default ámbito explicado

Autenticación como usuario

Asegúrese de que es propietario, similar al paso 2, y recupere un token de portador con el ámbito de Security Copilot.

Ejemplo de uso de la CLI de Azure (patrón v2 con /.default):

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

Referencia:

Obtenga el token de acceso (CLI) y el .default ámbito.

Respuesta como no propietario

En el caso de los no propietarios, se devuelve la siguiente respuesta para las llamadas 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"
  }
}

Puntos de conexión de API

1. Consultas Export API

Punto de conexión

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

GET /exports/prompts

Parámetros de consulta

N/A

Ejemplo de solicitud

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

Esquema de respuesta

Respuesta correcta - (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 error y mensajes

2. Api de exportación de evaluaciones

Punto de conexión

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

GET /exports/evaluations

Parámetros de consulta

Ejemplo de solicitud

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

Esquema de respuesta

Respuesta correcta - (200 OK)

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

Códigos de error y mensajes

Modelos de datos

Propiedades de respuesta base

Ambas API de exportación devuelven respuestas con estas propiedades comunes:

Paginación

Ambas API admiten la paginación basada en cursores:

1. Solicitud inicial: Realice la solicitud sin continuationToken.
2. Solicitudes posteriores: Use sessionsContinuationToken desde la respuesta anterior.
3. Fin de datos: Cuando sessionsContinuationToken es null, no hay más datos disponibles.

Ejemplo de paginación

Primera solicitud

GET /exports/prompts?sessionCount=100

La respuesta incluye 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
}

Siguiente solicitud mediante token (con codificación 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

Referencias

• Registro de una aplicación (portal)
• Creación de SP (tutorial de la CLI)
• Agregar credenciales (secreto de cliente/certificado)
• Creación de un secreto de cliente (pasos explícitos)
• (Alt) Creación de un secreto de cliente en el portal
• Security Copilot roles & asignaciones)
• Agregar entidad de servicio a un grupo (portal)
• Agregar entidad de servicio a un grupo (API)
• Inicio de sesión como SP (CLI)
• Obtención del token de acceso (CLI)