このドキュメントでは、REST API を使用して、Knowledge Catalog（旧 Dataplex Universal Catalog）のエントリ グループに対してバッチ メタデータ変更リクエストを送信する方法について説明します。
エントリ グループへの直接書き込みアクセス権がない場合は、エントリとエントリリンクの作成、更新、削除オペレーションを最大 250 個まで 1 つの変更リクエストにグループ化して、確認と承認を行うことができます。
始める前に
バッチ メタデータ変更リクエストを送信するには、必要な API が有効になっていること、ターゲット エントリ グループに必要な Identity and Access Management（IAM）ロールと権限があることを確認します。
Dataplex API が有効になっていない場合は、有効にします。
API を有効にするために必要なロール
API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。
必要なロール
エントリ グループのバッチ メタデータの変更をリクエストするために必要な権限を取得するには、ターゲット エントリ グループに対する次の IAM ロールを付与するよう管理者に依頼してください。
-
バッチ メタデータ変更リクエストを送信する: Dataplex Catalog 閲覧者（
roles/dataplex.catalogViewer）
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
ロールと権限の詳細については、Knowledge Catalog の IAM ロールをご覧ください。
メタデータの一括変更リクエストを作成する
バッチ変更リクエストを送信すると、Knowledge Catalog はリクエストの構文をチェックし、参照されているエントリタイプ、アスペクト タイプ、エントリリンク タイプ、親エントリが存在することを確認します。リクエストが承認されると、Knowledge Catalog はターゲット エントリとエントリリンクが存在するかどうかを確認します。たとえば、既存のリソースを作成するときに ALREADY_EXISTS エラーを返し、存在しないリソースを更新または削除するときに NOT_FOUND エラーを返します。
承認者がバッチ変更リクエストを承認すると、Knowledge Catalog は次の依存関係の順序でオペレーションを自動的に適用します。
- エントリリンクを削除します。
- エントリを削除します。
- エントリを作成、更新する。
- エントリリンクを作成、更新する。
バッチ変更リクエストでは、トランザクションの一貫性や自動ロールバックは提供されません。承認されると、Knowledge Catalog は各オペレーションを個別に評価して適用します。
バッチを作成する際は、次の参照ルールに注意してください。
- 同じバッチで削除されたエントリを参照しない: 同じバッチで削除されるエントリを参照するエントリリンクを作成または更新することはできません。また、同じバッチで削除するエントリに
parentEntryを設定することはできません。 - 子エントリの前に親エントリをリストする: 新しいエントリが同じバッチ内の別のエントリを
parentEntryとして参照する場合は、子エントリを作成するリクエストの前に親エントリを作成するリクエストをリストします。エントリまたはエントリリンクを作成する場合、parentエントリ グループ フィールドは省略可能です。parentを省略すると、Knowledge Catalog はchangePayload.nameのエントリ グループを使用します。parentを含める場合は、changePayload.nameと一致する必要があります。
基本的なバッチ メタデータ変更リクエストを送信するには、entryGroups.requestBatchMetadataChange メソッドを使用します。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
"changePayload": {
"name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
"changes": [
{
"createEntryRequest": {
"parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
"entryId": "ENTRY_ID",
"entry": {
"entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID"
}
}
}
]
},
"justification": "JUSTIFICATION"
}' \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"
次のように置き換えます。
PROJECT_ID: エントリ グループを含む Google Cloudプロジェクトの ID。LOCATION: エントリ グループのロケーション（us-central1など）。ENTRY_GROUP_ID: ターゲット エントリ グループの ID。ENTRY_ID: 作成する新しいエントリの ID。ENTRY_TYPE_ID: 新しいエントリのエントリタイプの ID。JUSTIFICATION: メタデータ変更リクエストが必要な理由（最大 1,024 文字）。
サービスは、作成された変更リクエストのリソース名を含むレスポンスを返します。
{
"changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}
作成されたバッチ変更リクエストを確認する
作成された変更リクエストを検査するには、changeRequests.get メソッドを使用します。
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID"
次のように置き換えます。
PROJECT_ID: 実際のGoogle Cloud プロジェクト ID。LOCATION: リソースが存在するリージョン（us-central1など）。CHANGE_REQUEST_ID: リクエストの一意の ID。
サービスは、バッチ ペイロードを含む ChangeRequest リソースを返します。
ユーザーが送信した一括変更リクエストに対するレスポンスの例
{ "name": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32", "uid": "eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32", "createTime": "2026-09-14T09:06:40.352156739Z", "updateTime": "2026-09-14T09:06:41.714939166Z", "justification": "Requesting creation of a new entry", "author": "requester@example.com", "state": "NEW", "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group", "etag": "0YSwO12PxwypRJj6kqM3CTZ9BYk4wk3yasxdiMDE3MU", "changeType": "BATCH_CHANGE_METADATA", "batchChangeMetadataRequest": { "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group", "changes": [ { "createEntryRequest": { "parent": "projects/my-project/locations/us-central1/entryGroups/my-entry-group", "entryId": "new-entry-id", "entry": { "entryType": "projects/my-project/locations/us-central1/entryTypes/my-entry-type" } } } ] } }
拡充エージェントの実行によってバッチ変更リクエストが自動的に作成された場合、author フィールドには拡充エージェントのサービス アカウントが含まれ、batchChangeMetadataRequest.description.job.name フィールドには拡充実行リソース名が含まれます。
マルチリソース バッチ変更リクエストを作成する
1 つのエントリ グループ内の複数のリソースに変更を提案するには、entryGroups.requestBatchMetadataChange メソッドを使用します。たとえば、このメソッドを使用して、最初のエントリを作成し、アスペクトがアタッチされた 2 番目のエントリを作成して、それらを接続する方向性のあるエントリリンクを作成できます。
マルチリソース バッチ変更リクエストを作成するには、次の POST リクエストを送信します。
マルチリソース バッチ変更リクエストを作成するためのサンプル リクエスト
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "changePayload": { "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "changes": [ { "createEntryRequest": { "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "entryId": "FIRST_ENTRY_ID", "entry": { "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID" } } }, { "createEntryRequest": { "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "entryId": "SECOND_ENTRY_ID", "entry": { "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID", "aspects": { "PROJECT_ID.LOCATION.ASPECT_TYPE_ID": { "data": { "ASPECT_FIELD_NAME": "ASPECT_FIELD_VALUE" } } } } } }, { "createEntryLinkRequest": { "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "entryLinkId": "ENTRY_LINK_ID", "entryLink": { "entryLinkType": "projects/PROJECT_ID/locations/LOCATION/entryLinkTypes/ENTRY_LINK_TYPE_ID", "entryReferences": [ { "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/FIRST_ENTRY_ID", "type": "SOURCE" }, { "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/SECOND_ENTRY_ID", "type": "TARGET" } ] } } } ] }, "justification": "JUSTIFICATION" }' \ "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"
次のように置き換えます。
PROJECT_ID: エントリ グループを含むGoogle Cloud プロジェクトの ID。LOCATION: エントリ グループのロケーション（us-central1など）。ENTRY_GROUP_ID: ターゲット エントリ グループの ID。FIRST_ENTRY_ID: 最初のカスタム エントリの ID。エントリリンクのSOURCEとして使用されます。SECOND_ENTRY_ID: アスペクトがアタッチされた 2 番目のカスタム エントリの ID。エントリリンクのTARGETとして使用されます。ENTRY_TYPE_ID: 新しいエントリのエントリタイプの ID。ASPECT_TYPE_ID: 2 番目のエントリにアタッチされているアスペクト タイプの ID。ASPECT_FIELD_NAME: アスペクト テンプレートのフィールドの名前。ASPECT_FIELD_VALUE: アスペクト フィールドの値。ENTRY_LINK_ID: 2 つのエントリを接続するエントリリンクの ID。ENTRY_LINK_TYPE_ID: エントリリンク タイプの ID（my-entry-link-typeなど）。JUSTIFICATION: これらのメタデータの変更が必要な理由の説明。
サービスは、作成された変更リクエストのリソース名を含むレスポンスを返します。
{
"changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}
次のステップ
- 変更リクエストの編集、承認、拒否、拡充エージェント バッチのキュレーション方法を確認する。
- 単一リソースのメタデータの変更をリクエストする方法を学習する。
- ガバナンス ワークフローの詳細を確認する。