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

Authentifier et autoriser les demandes d’API d’activité d’exportation

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

S’authentifier avec un principal de service

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

    Remarque

    Seuls les propriétaires existants peuvent effectuer l’action spécifique.

  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 :

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

    Exemple utilisant Azure CLI et 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

S’authentifier en tant qu’utilisateur

Vérifiez que votre compte d’utilisateur dispose du rôle Propriétaire Security Copilot avant de récupérer un jeton du porteur.

  • Exemple utilisant Azure CLI (modèle v2 avec/.default) :
az account get-access-token --scope https://api.securitycopilot.microsoft.com/.default

Contenu connexe

Comportement de réponse pour les non-propriétaires

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

Points de terminaison d’API

API d’exportation Requêtes

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

Code d’état Code d’erreur Message d’erreur
400 Demande incorrecte (Bad Request) Paramètres non valides ou informations manquantes sur l’espace de travail/locataire
404 Introuvable (Not Found) Administration’API d’exportation non activées
500 Erreur interne du serveur (Internal Server Error) Erreur du serveur lors de l’exportation

API d’exportation d’évaluations

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

GET /exports/evaluations

Paramètres de requête

Paramètre Type Requis Par défaut Description
sessionCount integer Non 100 Nombre de sessions à récupérer (plage : 1 à 1000).
continuationToken string Non null Jeton pour la pagination.
startDate DateTimeOffset Non null Filtre de date de début (inclus, format ISO).
endDate DateTimeOffset Non null Filtre de date de fin (inclus, format ISO).
orderByDescending boolean Non false Trier les résultats par ordre décroissant.

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

Code d’état Code d’erreur Message d’erreur
400 Demande incorrecte (Bad Request) Paramètres non valides ou informations manquantes sur l’espace de travail/locataire
404 Introuvable (Not Found) Administration’API d’exportation non activées
500 Erreur interne du serveur (Internal Server Error) Erreur du serveur lors de l’exportation

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 :

Propriété Type Description
workspaceId string ID de l’espace de travail exporté
workspaceName string Nom de l’espace de travail exporté
tenantId string ID de locataire exporté
sessionsContinuationToken string? Jeton pour la page suivante (null si plus de données)
totalCount integer? Nombre total d’éléments dans la page active
sessionCount integer Nombre de sessions utilisées pour cette requête

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

Remarque

  • Si votre principal de service n’a aucun abonnement, az login peut signaler qu’aucun n’a été trouvé ; dans ce cas, incluez --allow-no-subscriptions.
  • Pour les jetons, vous pouvez utiliser --resource https://api.securitycopilot.microsoft.com (v1) ou --scope https://api.securitycopilot.microsoft.com/.default (v2), en fonction de votre flux d’authentification. Consultez Obtenir un jeton d’accès (CLI) et .default l’étendue.

Contenu connexe

Utilisez les articles suivants pour obtenir des conseils :

  • Last updated on