ブックの更新

名前空間: microsoft.graph.security

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

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

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

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

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

グローバルサービス	米国政府機関 L4	米国政府機関 L5 (DOD)	21Vianet が運営する中国
✅	❌	❌	❌

アクセス許可

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

アクセス許可の種類	最小特権アクセス許可	より高い特権のアクセス許可
委任 (職場または学校のアカウント)	Workbooks.ReadWrite.All	注意事項なし。
委任 (個人用 Microsoft アカウント)	サポートされていません。	サポートされていません。
アプリケーション	Workbooks.ReadWrite.All	注意事項なし。

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

HTTP 要求

PATCH /security/workbooks/{workbookId}

要求ヘッダー

名前	説明
Authorization	ベアラー {token}。必須です。認証と認可についての詳細をご覧ください。
Content-Type	application/json. Required.
If-Match	現在のブックの ETag。要求を更新専用にします。ブックが存在し、ETag が一致している必要があります。省略可能。
If-None-Match	要求をアトミック作成のみの操作にするには、 `*` に設定します。ブックが既に存在してはなりません。省略可能。

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

要求本文

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

プロパティ	型	説明
content	microsoft.graph.security.workbookContent	保存する完全な JSON ドキュメント。 JSON でエンコードされた文字列ではなく、JSON オブジェクトを指定します。
name	String	ブックの表示名。最大文字数は 256 文字です。

要求本文には、 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が返されます。