API d’activité d’exportation

Ce document décrit les contrats d’API et les schémas de données de sortie attendus pour les API d’exportation Security Copilot Administration.

Les API d’exportation permettent aux administrateurs de l’espace de travail d’exporter des invites et des réponses d’invite dans un format paginé.

Authentification et autorisation

• Autorisation : Authentification du jeton du porteur
• Autorisations requises : Propriétaire/Administration de l’espace de travail

Authentification avec un principal de service

1. Créez une inscription d’application (par exemple, utilisez un nom comme mysecuritycopilotexportapp).

   • Utilisez le guide de démarrage rapide ID Microsoft Entra : Inscrire une application (portail).

   • Si vous préférez l’interface CLI, créez l’identité via le tutoriel : Créer un principal de service (Azure CLI).

   • Ajoutez des informations d’identification à l’inscription de l’application si nécessaire : Ajoutez des informations d’identification (clé secrète client/certificat) . Pour une création pas à pas d’une clé secrète client, consultez Créer une clé secrète client (étapes explicites) ou le guide du portail , Inscrire une application et créer un principal de service (portail) .

2. Ajouter le nouveau principal de service en tant que propriétaire dans Security Copilot attributions de rôles

   Consultez Security Copilot rôles et affectations. Security Copilot prend en charge l’attribution d’autorisations à des groupes assignables à un rôle( RAG), créez un RAG, puis ajoutez-y votre principal de service comme suit :

   • Créer un groupe assignable à un rôle

   • Ajouter le fournisseur de services au groupe (choisissez l’un ou l’autre choix) : Portail — Gérer les groupes (ajouter des membres) ou API — Microsoft Graph : Ajouter un membre de groupe

3. Récupérez un jeton du porteur pour votre principal de service.

   Exemple d’utilisation d’Azure CLI et d’une clé secrète 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
   

Références :

• Se connecter en tant que fournisseur de services (CLI)
• Obtenir un jeton d’accès (CLI)
• .default étendue expliquée

Authentification en tant qu’utilisateur

Vérifiez que vous êtes propriétaire, comme à l’étape 2, et récupérez un jeton du porteur limité à Security Copilot.

Exemple d’utilisation d’Azure CLI (modèle v2 avec /.default) :

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

Référence :

Obtenir le jeton d’accès (CLI) et l’étendue.default.

Réponse en tant que non-propriétaire

Pour les non-propriétaires, la réponse suivante est retournée pour les appels d’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"
  }
}

Points de terminaison d’API

1. API d’exportation Requêtes

Point de terminaison

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

GET /exports/prompts

Paramètres de requête

N/A

Exemple de requête

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

Schéma de réponse

Réponse de réussite - (200 OK)

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

Codes d’erreur et messages

2. Api d’exportation des évaluations

Point de terminaison

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

GET /exports/evaluations

Paramètres de requête

Exemple de requête

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

Schéma de réponse

Réponse de réussite - (200 OK)

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

Codes d’erreur et messages

Modèles de données

Propriétés de la réponse de base

Les deux API d’exportation retournent des réponses avec les propriétés communes suivantes :

Pagination

Les deux API prennent en charge la pagination basée sur le curseur :

1. Demande initiale : Effectuez une demande sans continuationToken.
2. Demandes suivantes : Utilisez sessionsContinuationToken à partir de la réponse précédente.
3. Fin des données : Lorsque sessionsContinuationToken a la valeur null, plus aucune donnée n’est disponible.

Exemple de pagination

Première requête

GET /exports/prompts?sessionCount=100

La réponse inclut 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
}

Requête suivante à l’aide d’un jeton (encodée 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

Références

• Inscrire une application (portail)
• Créer un fournisseur de services (tutoriel CLI)
• Ajouter des informations d’identification (clé secrète client/certificat)
• Créer une clé secrète client (étapes explicites)
• (Alt) Créer une clé secrète client dans le portail
• Security Copilot rôles & attributions)
• Ajouter un principal de service à un groupe (portail)
• Ajouter un principal de service à un groupe (API)
• Se connecter en tant que fournisseur de services (CLI)
• Obtenir un jeton d’accès (CLI)