Exportaktivitäts-API

In diesem Dokument werden die API-Verträge und die erwarteten Ausgabedatenschemas für die Security Copilot Admin Export-APIs beschrieben.

Export-APIs bieten Arbeitsbereichsadministratoren die Möglichkeit, Eingabeaufforderungen und Eingabeaufforderungsantworten in einem paginierten Format zu exportieren.

Authentifizierung und Autorisierung

• Autorisierung: Bearertokenauthentifizierung
• Erforderliche Berechtigungen: Arbeitsbereichsbesitzer/Admin

Authentifizieren mit einem Dienstprinzipal

1. Erstellen Sie eine App-Registrierung (verwenden Sie z. B. einen Namen wie mysecuritycopilotexportapp).

   • Verwenden Sie den Schnellstart Microsoft Entra-ID: Registrieren einer App (Portal).

   • Wenn Sie die CLI bevorzugen, erstellen Sie die Identität im Tutorial Erstellen eines Dienstprinzipals (Azure CLI).

   • Fügen Sie der App-Registrierung nach Bedarf Anmeldeinformationen hinzu: Fügen Sie Anmeldeinformationen (geheimer Clientschlüssel/Zertifikat) hinzu. Eine schrittweise Erstellung eines geheimen Clientschlüssels finden Sie unter Erstellen eines geheimen Clientschlüssels (explizite Schritte) oder im Portalhandbuch Registrieren einer App und Erstellen eines Dienstprinzipals (Portal).

2. Hinzufügen des neuen Dienstprinzipals als Besitzer in Security Copilot Rollenzuweisungen

   Weitere Informationen finden Sie unter Security Copilot Rollen und Zuweisungen. Security Copilot unterstützt das Zuweisen von Berechtigungen zu Gruppen, die rollenzuweisbaren Gruppen (Role Assignable Groups, RAGs) zugewiesen werden. Erstellen Sie daher eine RAG, und fügen Sie dann Ihren Dienstprinzipal (SP) wie folgt hinzu:

   • Erstellen einer Gruppe, die Rollen zugewiesen werden kann

   • Hinzufügen des SP zur Gruppe (wählen Sie eine der folgenden Optionen aus): Portal – Gruppen verwalten (Mitglieder hinzufügen) oder API – Microsoft Graph: Hinzufügen eines Gruppenmitglieds

3. Rufen Sie ein Bearertoken für Ihren Dienstprinzipal ab.

   Beispiel für die Verwendung der Azure CLI und eines geheimen Clientschlüssels:

   # 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
   

Referenzen:

• Anmelden als SP (CLI)
• Abrufen des Zugriffstokens (CLI)
• .default Bereich erläutert

Authentifizieren als Benutzer

Stellen Sie wie in Schritt 2 sicher, dass Sie besitzer sind, und rufen Sie ein Bearertoken ab, das auf Security Copilot festgelegt ist.

Beispiel für die Verwendung der Azure CLI (v2-Muster mit /.default):

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

Referenz:

Abrufen des Zugriffstokens (CLI) und .default des Bereichs.

Antwort als Nicht-Besitzer

Für Nichtbesitzer wird die folgende Antwort für API-Aufrufe zurückgegeben:

{
  "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-Endpunkte

1. Prompts Export-API

Endpunkt

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

GET /exports/prompts

Abfrageparameter

N/V

Anforderungsbeispiel

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

Antwortschema

Erfolgsantwort - (200 OK)

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

Fehlercodes und -meldungen

2. Auswertungsexport-API

Endpunkt

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

GET /exports/evaluations

Abfrageparameter

Anforderungsbeispiel

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

Antwortschema

Erfolgsantwort - (200 OK)

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

Fehlercodes und -meldungen

Datenmodelle

Basisantworteigenschaften

Beide Export-APIs geben Antworten mit den folgenden allgemeinen Eigenschaften zurück:

Paginierung

Beide APIs unterstützen cursorbasierte Paginierung:

1. Anfängliche Anforderung: Stellen Sie eine Anforderung ohne continuationToken.
2. Nachfolgende Anforderungen: Verwenden Sie sessionsContinuationToken aus der vorherigen Antwort.
3. Ende der Daten: Wenn sessionsContinuationToken NULL ist, sind keine weiteren Daten verfügbar.

Paginierungsbeispiel

Erste Anforderung

GET /exports/prompts?sessionCount=100

Antwort enthält 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
}

Nächste Anforderung mit Token (URL-codiert)

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

Verweise

• Registrieren einer App (Portal)
• Erstellen eines SP (CLI-Tutorial)
• Hinzufügen von Anmeldeinformationen (geheimer Clientschlüssel/Zertifikat)
• Erstellen eines geheimen Clientschlüssels (explizite Schritte)
• (Alt) Erstellen eines geheimen Clientschlüssels im Portal
• Security Copilot Rollen & Zuweisungen)
• Hinzufügen eines Dienstprinzipals zu einer Gruppe (Portal)
• Hinzufügen eines Dienstprinzipals zu einer Gruppe (API)
• Anmelden als SP (CLI)
• Abrufen des Zugriffstokens (CLI)