Chronicle API に移行する

以下でサポートされています。

このドキュメントは、インテグレーション、カスタム スクリプト、カスタム アクションを使用して SOAR API をプログラムで呼び出す場合に適用されます。 このドキュメントでは、Chronicle API の一部として、プログラムによる API 参照を新しい SOAR API エンドポイントに更新する手順と考慮事項について説明します。

Chronicle API サーフェスには、開発プロセスを 効率化するための改善がいくつか導入されています。また、以前の API に存在していた制限事項や 複雑さにも対応しています。

以前の SOAR API と API キーは 2026 年 11 月 30 日まで使用できますが、それ以降は機能しなくなります。

前提条件

SOAR API の移行を行う前に、次の操作を行う必要があります。

主な変更点と機能強化

次の表に、以前の API サーフェスと新しい API サーフェスの主な違いを示します。

機能領域 以前の API 新しい API 詳細
認証 API トークン OAuth 2.0 新しい認証方法では、セキュリティが強化され、プロセスが標準化されます。
データモデル フラット構造 リソース指向の設計 この新しい設計により、データの整合性が向上し、オブジェクトの操作が簡素化されます。
エンドポイントの命名 一貫性がない RESTful で標準化されている 命名規則を統一することで、API がより直感的になり、統合が容易になります。

サポート終了スケジュール

SOAR の以前の API サーフェスは、 2026 年 11 月 30 日に完全にサポート終了となる予定です。サービスの停止を避けるため、この日までに移行を完了することをおすすめします。

移行手順

このセクションでは、アプリケーションを Chronicle API に正常に移行する手順について説明します。

ドキュメントを確認する

Chronicle API リファレンス ガイドなど、新しい API の包括的なドキュメントをよく理解してください。

エンドポイントを新しい API サーフェスにマッピングする

アプリケーションが行う以前の API 呼び出しごとに、対応する新しいエンドポイントを特定します。同様に、構造の変更や新しいフィールドを考慮して、以前のデータモデルを新しいデータモデルにマッピングします。 詳細については、 API エンドポイント マッピング表をご覧ください。

省略可: ステージング インテグレーションを作成する

カスタム インテグレーションまたは商用 インテグレーションのコンポーネントを編集する場合は、まず変更をステージング インテグレーションに push することをおすすめします。 このプロセスにより、本番環境の自動化フローに影響を与えることなくテストできます。 SOAR API を使用するカスタムビルドのアプリケーションを移行する場合は、 次のステップに進んでください。インテグレーションのステージングの詳細については、 ステージング モードでインテグレーションをテストするをご覧ください。

サービス エンドポイントと URL を更新する

サービス エンドポイントは、API サービスのネットワーク アドレスを指定するベース URL です。1 つのサービスに複数のサービス エンドポイントが存在することもあります。Chronicle は リージョン サービスであり、リージョン エンドポイントのみをサポートしています。

新しいエンドポイントはすべて一貫した接頭辞を使用しているため、最終的なエンドポイント アドレスを 予測できます。次の例は、新しいエンドポイント URL の構造を示しています。

[api_version]/projects/[project_id]/locations/[location]/instances[instance_id]/...

この構造により、エンドポイントの最終アドレスは次のようになります。

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

ここで

  • service_endpoint: リージョン 緊急対応用住所
  • api_version: クエリする API のバージョン。v1alpha、v1beta、v1 を指定できます。
  • project_id: プロジェクト ID（IAM 権限に定義したプロジェクトと同じ）
  • location: プロジェクトのロケーション（リージョン）。リージョン エンドポイントと同じ
  • instance_id: Google Security Operations SIEM のお客様 ID。

リージョン アドレス:

  • africa-south1: https://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1: https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12: https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2: https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3: https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6: https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9: https://chronicle.europe-west9.rep.googleapis.com

  • me-central1: https://chronicle.me-central1.rep.googleapis.com

  • me-central2: https://chronicle.me-central2.rep.googleapis.com

  • me-west1: https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

  • us: https://chronicle.us.rep.googleapis.com

  • eu: https://chronicle.eu.rep.googleapis.com

たとえば、米国のプロジェクトのすべてのケースのリストを取得するには、次のようにします。

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

認証方法を更新する

新しい API では、認証に Google Cloud IAM を使用します。この新しい 認証フローを実装するには、アプリケーションまたはレスポンス インテグレーションを 更新する必要があります。スクリプトを実行するユーザーが、アクセスしようとしているエンドポイントに対する適切な 権限を持っていることを確認してください。 この新しいフローを実装するには、レスポンス インテグレーションまたはアプリケーションを更新する必要があります。スクリプトを実行するユーザーが、ターゲット エンドポイントに必要な権限を持っていることを確認してください。詳細な手順については、Chronicle API で認証するをご覧ください。

サービス アカウントまたは Workload Identity を SOAR パラメータにマッピングする

サービス アカウントまたは Workload Identity 連携を使用して Chronicle API の認証を行う場合は、Google SecOps と正常に通信できるように、プラットフォーム内で承認する必要があります。このマッピングは、サービス アカウントまたは Workload Identity に SOC ロールと環境への必要なアクセス権を付与するために必要です。

Google SecOps への サービス アカウント アクセスまたは Workload Identity 連携アクセスを許可するには、ID をプラットフォームのアクセス制御パラメータにマッピングする必要があります。このマッピングは、自動タスクまたは API オペレーションの実行に必要なSOC ロールと環境への必要なアクセス権を ID に付与するための必須の手順です。

  1. [SOAR 設定]>[詳細]>[グループ マッピング] に移動します。
  2. [add] [Add] をクリックします。

  3. [マッピングを追加] ダイアログのフィールドに値を入力して、ID をプラットフォームのアクセス制御パラメータにマッピングします。

    1. [IdP / ユーザー グループ] フィールドに、次のいずれかを入力します。
      • Cloud Identity を使用して ID を設定した場合は、サービス アカウントの完全なメールアドレス。
      • Workforce Identity 連携を使用して ID を設定した場合は、Workload Identity プリンシパル文字列。

    2. 次のアクセス制御フィールドを構成します。

      フィールド 説明
      権限グループ ID がアクセスできるモジュールとサブモジュールを定義する権限グループを選択します。
      SOC ロール ID のロール（Tier 1 など）を定義する SOC ロールを選択します。
      環境 ID がアクセスできる環境または環境グループ（[すべての環境] など）を選択します。
      グループ メンバー 必要に応じて、必要なユーザーのメールアドレスを入力します。メールアドレスを追加したら、Enter キーを押します。
      制限される操作 制限するアクションを選択して、モジュール内の特定のオペレーションを制限します。

  4. [追加] をクリックします。

ユーザーとサービス アカウントのマッピングの詳細については、 サードパーティ ID を使用してプラットフォームでユーザーをマッピングする方法 または Cloud Identity を使用してプラットフォームでユーザーをマッピングする方法をご覧ください。

API ロジックを更新する

API リファレンスに記載されている新しいデータモデルとエンドポイント構造を分析します。すべてのメソッドが大幅に変更されているわけではなく、既存の コードを再利用できるものもあります。主な目的は、新しいリファレンス ドキュメントを確認し、特定のユースケースごとに、アプリケーションのロジック内のフィールド名とデータ構造に必要な 変更を特定して実装することです。

インテグレーションをテストする

本番環境にデプロイする前に、ステージング インテグレーションで更新したアプリケーションをテストします。

  1. テスト計画を作成する: 移行したすべての 機能を網羅するテストケースを定義します。
  2. テストを実行する: 自動テストと手動テストを実行して、正確性と 有効性を確認します。
  3. パフォーマンスをモニタリングする: 新しい API を使用してアプリケーションのパフォーマンスを評価します。

さらにサポートが必要な場合コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。