ブックの更新

名前空間: microsoft.graph.security

クライアントが選択した ID を使用して ブック を作成または置換する。

要求 URL に GUID を指定します。 条件付きヘッダーがない場合、このメソッドは、その ID が存在しない場合はブックを作成します。ある場合は、その名前と内容を置き換えます。 同じ GUID を再利用すると、ブックの ID が保持されます。 Updates では createdByUpn と createdAtDateTime を保持します。

CONTENT 値によって、JSON ドキュメント全体が置き換えられます。 部分的な更新や入れ子になったマージではありません。

この API は、次の国内クラウド展開で使用できます。

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

Workbooks API を使用するには、テナントがアクティブでオンボードされている必要があります。 委任された職場または学校とアプリケーションのアクセス許可には、管理者の同意が必要です。 委任アクセスでは、サインイン ユーザーが該当する Microsoft Defender XDR 統合 RBAC 承認を持っている必要もあります。 個人用の Microsoft アカウントはサポートされていません。

HTTP 要求

PATCH /security/workbooks/{workbookId}

要求ヘッダー

If-Matchについては、ブックの HTTP ETag応答ヘッダーから、W/ プレフィックスと引用符を含めて、値を変更せずにコピーします。 現在の ETag の一致する強い表現と弱い表現が受け入れられます。 ETag を不透明な値として扱います。自分で生成しないでください。

要求本文

要求本文で 名前 と 内容 の両方を指定します。 完全な コンテンツ ドキュメントを含めます。省略した入れ子になったプロパティは、以前のバージョンから保持されません。

要求本文には、 id、 etag、 createdByUpn、 lastUpdatedByUpn、 createdAtDateTime、または updatedAtDateTime を指定しないでください。 URL によって ID が決まります。サービスは、同時実行プロパティと監査プロパティを管理します。

応答

成功した場合、このメソッドは応答本文で microsoft.graph.security.workbook オブジェクトと、次のいずれかの応答コードを返します。

• 201 Created ブックの作成時。 Location ヘッダーには、ブックの Microsoft Graph URL が含まれています。
• 200 OK 既存のブックを置き換えるとき。

ETag応答ヘッダーには、ブックの現在の同時実行トークンが含まれています。

エラー

次のいずれかの条件に該当する場合、メソッドは 412 Precondition Failed を返します。

• If-None-Match: *を入力しますが、ブックは既に存在します。
• If-Match を入力しましたが、ブックが存在しないか、指定された ETag が現在のバージョンと一致しません。

例

例 1:変更されていない場合にのみブックを置き換える

要求

次の例では、Get ブックによって返される弱いETagを使用します。 指定された コンテンツ オブジェクトは、前のドキュメントを置き換えます。

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."
      }
    ]
  }
}

応答

次の例は応答を示しています。 ID と作成監査プロパティは保持されますが、更新監査プロパティと ETag は新しいバージョンを反映します。 以前の content.settings プロパティは、置換ドキュメントで指定されなかったため保持されません。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

例 2: ID が存在しない場合にのみブックを作成する

要求

この独立した例では、ブック ID が存在しないことを前提としています。 If-None-Match: * ヘッダーは、要求で既に 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
    }
  }
}

応答

次の例は、ID が存在しない場合の応答を示しています。 ブックが存在する後にこの作成専用要求を繰り返すと、 412 Precondition Failedが返されます。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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