Condividi tramite

API Attività di esportazione

Questo documento descrive i contratti API e gli schemi di dati di output previsti per le API di esportazione Security Copilot Amministrazione.

Le API di esportazione offrono agli amministratori dell'area di lavoro la possibilità di esportare richieste e risposte alle richieste in un formato impaginato.

Autenticazione e autorizzazione

  • Autorizzazione: autenticazione del token di connessione
  • Autorizzazioni necessarie: Proprietario/Amministrazione dell'area di lavoro

Autenticazione con un'entità servizio

  1. Creare una registrazione dell'app , ad esempio usare un nome come mysecuritycopilotexportapp.

Nota

Solo i proprietari esistenti possono eseguire questa operazione.

  1. Aggiungere la nuova entità servizio come proprietario nelle assegnazioni di ruolo Security Copilot

    Vedere Security Copilot ruoli e assegnazioni. Security Copilot supporta l'assegnazione di autorizzazioni ai gruppi assegnabili ai ruoli, quindi creare un RAG e quindi aggiungervi l'entità servizio (SP) come indicato di seguito:

  2. Recuperare un token di connessione per l'entità servizio.

    Esempio di uso dell'interfaccia della riga di comando di Azure e di un segreto client:

    # 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

Riferimenti:

Autenticazione come utente

Assicurarsi di essere un proprietario, simile al passaggio 2, e recuperare un token di connessione con ambito per Security Copilot.

Esempio di uso dell'interfaccia della riga di comando di Azure (modello v2 con /.default):

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

Riferimento:

Ottenere il token di accesso el'ambito.default.

Risposta come non proprietario

Per i non proprietari, viene restituita la risposta seguente per le chiamate 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"
  }
}

Endpoint API

1. PROMPT API Export

Endpoint

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

GET /exports/prompts

Parametri di query

N/D

Esempio di richiesta

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

Schema di risposta

Risposta riuscita - (200 OK)

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

Codici e messaggi di errore

Codice di stato Codice di errore Messaggio di errore
400 Richiesta non valida Parametri non validi o informazioni mancanti sull'area di lavoro/tenant
404 Non trovato Amministrazione API di esportazione non abilitate
500 Errore interno del server Errore del server durante l'esportazione

2. API esportazione valutazioni

Endpoint

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

GET /exports/evaluations

Parametri di query

Parametro Tipo Obbligatorio Impostazione predefinita Descrizione
sessionCount integer No 100 Numero di sessioni da recuperare (intervallo: 1-1000).
continuationToken string No null Token per la paginazione.
startDate DateTimeOffset No null Filtro data di inizio (inclusivo, formato ISO).
endDate DateTimeOffset No null Filtro della data di fine (inclusivo, formato ISO).
orderByDescending boolean No false I risultati dell'ordine sono decrescenti.

Esempio di richiesta

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

Schema di risposta

Risposta riuscita - (200 OK)

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

Codici e messaggi di errore

Codice di stato Codice di errore Messaggio di errore
400 Richiesta non valida Parametri non validi o informazioni mancanti sull'area di lavoro/tenant
404 Non trovato Amministrazione API di esportazione non abilitate
500 Errore interno del server Errore del server durante l'esportazione

Modelli di dati

Proprietà della risposta di base

Entrambe le API di esportazione restituiscono risposte con queste proprietà comuni:

Proprietà Tipo Descrizione
workspaceId string ID dell'area di lavoro esportato
workspaceName string Nome dell'area di lavoro esportato
tenantId string ID tenant esportato
sessionsContinuationToken string? Token per la pagina successiva (null se non sono più dati)
totalCount integer? Numero totale di elementi nella pagina corrente
sessionCount integer Numero di sessioni usate per questa richiesta

Impaginazione

Entrambe le API supportano la paginazione basata su cursori:

  1. Richiesta iniziale: Effettuare una richiesta senza continuationToken.
  2. Richieste successive: Usare sessionsContinuationToken dalla risposta precedente.
  3. Fine dei dati: Quando sessionsContinuationToken è Null, non sono disponibili altri dati.

Esempio di paginazione

Prima richiesta

GET /exports/prompts?sessionCount=100

La risposta include 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
}

Richiesta successiva tramite token (codifica 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

Nota

  • Se l'entità servizio non ha sottoscrizioni, az login potrebbe segnalare che non ne sono state trovate; in questo caso, includere --allow-no-subscriptions.
  • Per i token, è possibile usare --resource https://api.securitycopilot.microsoft.com (v1) o --scope https://api.securitycopilot.microsoft.com/.default (v2), a seconda del flusso di autenticazione. Vedere Ottenere il token di accesso el'ambito.default.

Riferimenti

  • Last updated on