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.

Authentifizieren und Autorisieren von Exportaktivitäts-API-Anforderungen

• Autorisierung: Bearertokenauthentifizierung
• Erforderliche Berechtigungen: Arbeitsbereichsbesitzer/Administrator

Authentifizieren mit einem Dienstprinzipal

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

   • Verwenden Sie den Microsoft Entra ID Schnellstart: 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).

   Hinweis

   Nur vorhandene Besitzer können die spezifische Aktion ausführen.

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

Authentifizieren als Benutzer

Stellen Sie sicher, dass Ihr Benutzerkonto über die Rolle Security Copilot Besitzer verfügt, bevor Sie ein Bearertoken abrufen.

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

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

Verwandte Inhalte

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

Reaktionsverhalten für 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": "aaaa0000-bb11-2222-33cc-444444dddddd"
    },
    "traceId": "0HNF1M54NKVJ3:00000041"
  }
}

API-Endpunkte

Prompts-Export-API

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

Auswertungsexport-API

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

Verwandte Inhalte

Verwenden Sie die folgenden Artikel als Anleitung:

• 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)