Freigeben über

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

Hinweis

Nur vorhandene Besitzer können dies tun.

  1. 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:

  2. 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:

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

Statuscode Fehlercode Fehlermeldung
400 Ungültige Anforderung (Bad Request) Ungültige Parameter oder fehlende Arbeitsbereichs-/Mandanteninformationen
404 Nicht gefunden (Not Found) Admin Export-APIs nicht aktiviert
500 Interner Serverfehler (Internal Server Error) Serverfehler beim Export

2. Auswertungsexport-API

Endpunkt

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

GET /exports/evaluations

Abfrageparameter

Parameter Typ Erforderlich Standard Beschreibung
sessionCount integer Nein 100 Anzahl der abzurufenden Sitzungen (Bereich: 1–1000).
continuationToken string Nein null Token für die Paginierung.
startDate DateTimeOffset Nein null Startdatumsfilter (einschließlich, ISO-Format).
endDate DateTimeOffset Nein null Enddatumsfilter (einschließlich, ISO-Format).
orderByDescending boolean Nein false Sortieren Sie die Ergebnisse nach absteigend.

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

Statuscode Fehlercode Fehlermeldung
400 Ungültige Anforderung (Bad Request) Ungültige Parameter oder fehlende Arbeitsbereichs-/Mandanteninformationen
404 Nicht gefunden (Not Found) Admin Export-APIs nicht aktiviert
500 Interner Serverfehler (Internal Server Error) Serverfehler beim Export

Datenmodelle

Basisantworteigenschaften

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

Eigenschaft Typ Beschreibung
workspaceId string Die Arbeitsbereichs-ID, die exportiert wird
workspaceName string Der Arbeitsbereichsname, der exportiert wird
tenantId string Die Mandanten-ID, die exportiert wird
sessionsContinuationToken string? Token für die nächste Seite (NULL, wenn keine daten mehr)
totalCount integer? Gesamtanzahl der Elemente auf der aktuellen Seite
sessionCount integer Für diese Anforderung verwendete Sitzungsanzahl

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

Hinweis

  • Wenn Ihr Dienstprinzipal über keine Abonnements verfügt, kann gemeldet werden, az login dass keine gefunden wurden. Fügen Sie in diesem Fall ein --allow-no-subscriptions.
  • Für Token können Sie je nach Authentifizierungsfluss entweder --resource https://api.securitycopilot.microsoft.com (v1) oder --scope https://api.securitycopilot.microsoft.com/.default (v2) verwenden. Weitere Informationen finden Sie unter Abrufen von Zugriffstoken (CLI) und .default Bereich.

Verweise

  • Last updated on