Mettre à jour le classeur

Espace de noms : microsoft.graph.security

Créez ou remplacez un classeur à l’aide d’un ID sélectionné par le client.

Fournissez un GUID dans l’URL de demande. Sans en-tête conditionnel, cette méthode crée le classeur si cet ID n’existe pas, ou remplace son nom et son contenu si c’est le cas. La réutilisation du même GUID permet de préserver l’identité du classeur. Les mises à jour conservent createdByUpn et createdAtDateTime.

La valeur de contenu remplace l’ensemble du document JSON. Il ne s’agit pas d’une mise à jour partielle ou d’une fusion imbriquée.

Cette API est disponible dans les déploiements cloud nationaux suivants.

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme étant les moins privilégiées pour cette API. Utilisez une ou plusieurs autorisations privilégiées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, voir Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez la référence des autorisations.

Le client doit être actif et intégré pour utiliser les API Classeurs. Les autorisations déléguées de travail, d’école ou d’application nécessitent le consentement de l’administrateur. L’accès délégué exige également que l’utilisateur connecté dispose de l’autorisation RBAC unifiée de Microsoft Defender XDR applicable. Les comptes Microsoft personnels ne sont pas pris en charge.

Requête HTTP

PATCH /security/workbooks/{workbookId}

En-têtes de demande

Pour If-Match, copiez la valeur de l’en-tête de réponse HTTP ETag du classeur inchangée, y compris son préfixe et les W/ guillemets. Les représentations fortes et faibles correspondantes de l’ETag actuel sont acceptées. Traitez les ETag comme des valeurs opaques ; Ne les générez pas vous-même.

Corps de la demande

Indiquez le nom et le contenu dans le corps de la demande. Inclure le document de contenu complet ; Les propriétés imbriquées que vous omettez ne sont pas conservées de la version précédente.

N’indiquez pas id, etag, createdByUpn, lastUpdatedByUpn, createdAtDateTime ou updatedAtDateTime dans le corps de la demande. L’URL détermine l’ID ; Le service gère les propriétés d’accès concurrentiel et d’audit.

Réponse

En cas de réussite, cette méthode renvoie un objet microsoft.graph.security.workbook dans le corps de la réponse et l’un des codes de réponse suivants :

• 201 Created lors de la création du classeur. L’en-tête Location contient l’URL Microsoft Graph du classeur.
• 200 OK Lorsqu’un classeur existant est remplacé.

L’en-tête ETag de réponse contient le jeton d’accès concurrentiel actuel du classeur.

Erreurs

La méthode renvoie 412 Precondition Failed lorsque l’une des conditions suivantes s’applique :

• Vous fournissez If-None-Match: *, mais le classeur existe déjà.
• Vous fournissez If-Match, mais le classeur n’existe pas ou l’ETag fourni ne correspond pas à sa version actuelle.

Exemples

Exemple 1 : remplacer un classeur uniquement s’il n’a pas changé

Demande

L’exemple suivant utilise le faible ETag renvoyé par Get workbook. L’objet de contenu fourni remplace le document précédent.

PATCH https://graph.microsoft.com/beta/security/workbooks/ba989c62-af63-b8de-286d-7474ec579357
Content-Type: application/json
If-Match: W/"0x8DE000000000001"

{
  "name": "Threat hunting overview - updated",
  "content": {
    "version": "2.0",
    "title": "Priority investigations",
    "items": [
      {
        "type": "text",
        "text": "Review the highest-priority investigations first."
      }
    ]
  }
}

Réponse

L’exemple suivant illustre la réponse. L’ID et les propriétés d’audit de création sont conservés, tandis que les propriétés d’audit de mise à jour et ETag reflètent la nouvelle version. L’ancienne propriété content.settings n’est pas conservée, car elle n’a pas été fournie dans le document de remplacement.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 200 OK
Content-Type: application/json
ETag: W/"0x8DE000000000002"

{
  "@odata.type": "#microsoft.graph.security.workbook",
  "id": "ba989c62-af63-b8de-286d-7474ec579357",
  "name": "Threat hunting overview - updated",
  "content": {
    "version": "2.0",
    "title": "Priority investigations",
    "items": [
      {
        "type": "text",
        "text": "Review the highest-priority investigations first."
      }
    ]
  },
  "createdByUpn": "adelev@contoso.com",
  "lastUpdatedByUpn": "alexw@contoso.com",
  "createdAtDateTime": "2026-09-22T10:00:00Z",
  "updatedAtDateTime": "2026-09-22T10:15:00Z"
}

Exemple 2 : créer un classeur uniquement si son ID n’existe pas

Demande

Cet exemple indépendant suppose que l’ID de classeur n’existe pas. L’en-tête If-None-Match: * empêche la demande de remplacer un classeur qui utilise déjà l’ID.

PATCH https://graph.microsoft.com/beta/security/workbooks/ba989c62-af63-b8de-286d-7474ec579357
Content-Type: application/json
If-None-Match: *

{
  "name": "Threat hunting overview",
  "content": {
    "version": "1.0",
    "title": "Threat hunting overview",
    "items": [
      {
        "type": "text",
        "text": "Investigate recent security activity."
      }
    ],
    "settings": {
      "showTitle": true
    }
  }
}

Réponse

L’exemple suivant montre la réponse lorsque l’ID n’existe pas. La répétition de cette demande de création uniquement après l’existence du classeur retourne 412 Precondition Failed.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://graph.microsoft.com/beta/security/workbooks/ba989c62-af63-b8de-286d-7474ec579357
ETag: W/"0x8DE000000000001"

{
  "@odata.type": "#microsoft.graph.security.workbook",
  "id": "ba989c62-af63-b8de-286d-7474ec579357",
  "name": "Threat hunting overview",
  "content": {
    "version": "1.0",
    "title": "Threat hunting overview",
    "items": [
      {
        "type": "text",
        "text": "Investigate recent security activity."
      }
    ],
    "settings": {
      "showTitle": true
    }
  },
  "createdByUpn": "adelev@contoso.com",
  "lastUpdatedByUpn": "adelev@contoso.com",
  "createdAtDateTime": "2026-09-22T10:00:00Z",
  "updatedAtDateTime": "2026-09-22T10:00:00Z"
}