オブジェクト エンリッチメントを構成する

Cloud Storage バケット内の画像と PDF ドキュメントの構造化メタデータを生成するには、 特徴構成（FeatureConfig}）リソースを作成します。また、オブジェクト エンリッチメント サービス エージェントにデータへのアクセスを許可する必要があります。 オブジェクト エンリッチメントを構成すると、 Cloud Storage は選択した機械学習モデルを使用して一致するオブジェクトを非同期で評価し、結果をオブジェクトに 直接添付して オブジェクト コンテキストとします。

このページでは、特徴構成の作成、一覧表示、表示、更新、削除の方法について説明します。また、サービス エージェントに必要な Identity and Access Management（IAM）権限を付与する方法についても説明します。

ワークフロー全体は次の手順で構成されます。

  1. 特徴構成（FeatureConfig）リソースを作成してスコープを定義し、モデルを選択します。
  2. サービス エージェントにストレージ バケットへのアクセスを許可します。
  3. オブジェクトのエンリッチメント メタデータを表示して管理します。
  4. BigQuery で SQL を使用してエンリッチメントを一括で分析します。
  5. ワークロードの進化に合わせて、特徴構成を更新または削除します。

コンセプトの詳細とサポートされているユースケースについては、 オブジェクト エンリッチメントの概要をご覧ください。

始める前に

オブジェクト エンリッチメントを構成する前に、次の設定手順を完了してください。

必要なロールを取得する

特徴構成の作成と管理に必要な権限を取得するには、プロジェクトに対するストレージ管理者 （roles/storage.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには 特徴構成の作成と管理に必要な権限が含まれています。必要とされる正確な権限については、必要な権限セクションを開いてご確認ください。

必要な権限

特徴構成の作成と管理には、次の権限が必要です。

  • storage.featureConfigs.create
  • storage.featureConfigs.list
  • storage.featureConfigs.get
  • storage.featureConfigs.update
  • storage.featureConfigs.delete

カスタムロールや 他の事前定義ロールを使用して、 これらの権限 を取得することもできます。

（省略可）SQL 分析用に Storage Insights データセットを準備する

BigQuery で SQL を使用して、数百万のオブジェクトにわたるエンリッチメント メタデータをクエリして分析する場合は、まずStorage Insights データセットを構成する必要があります。Storage Insights データセットは、オブジェクト コンテキストをクエリ可能な BigQuery テーブルに直接エクスポートします。

Google Cloud コンソール、Google Cloud CLI、または API を使用して個々のオブジェクトを検査するだけの場合は、この手順をスキップできます。

特徴構成を作成する

特徴構成（FeatureConfig）では、Cloud Storage がモニタリングするストレージ バケットと、オブジェクトを評価する機械学習モデルを指定します。構成には正確なバケット名を指定します。オブジェクト エンリッチメントでは、正規表現やワイルドカードはサポートされていません。構成を作成した後にバケットを作成、再作成（削除して再度作成）、または再配置 する場合は、それらを含めるように特徴 構成を更新する必要があります。詳細については、 構成とスコープの管理をご覧ください。

特徴構成は、 Google Cloud コンソール、 Google Cloud CLI、または JSON API を使用して作成できます。

Console

  1. コンソール Google Cloud で、Cloud Storage の [オブジェクト エンリッチメント] ページに移動します。

    [オブジェクト エンリッチメント] に移動

  2. [作成] をクリックします。

  3. [ソースを定義] ステップで、構成名とターゲット バケットを指定します。

    1. [名前] フィールドに、特徴構成の一意の名前を入力します。名前は 1 ～ 63 文字で、小文字、数字、ハイフンのみを含める必要があります。小文字で始まり、ハイフンで終わることはできません。構成を作成した後にこの名前を変更することはできません。
    2. 省略可: 構成を識別しやすくするために、[説明] フィールドに説明（最大 256 文字）を入力します。
    3. エンリッチメントするバケットを指定するには、[バケット名] フィールドに 1 つ以上のバケット名をカンマまたはスペースで区切って入力します。または、[**参照**] をクリックしてバケットを選択し、 [**選択**] をクリックします。
    4. [続行] をクリックします。

  4. [モデルを選択] ステップで、有効にする 1 つ以上の 機械学習モデルのチェックボックスをオンにして、 [続行] をクリックします。

    • 画像オブジェクト検出 （object-detector）: 画像内の複数のオブジェクトを識別して配置します。
    • 画像顔検出 （face-detector）: 画像内の人間の顔とその属性を検出します。
    • 画像ラベリング （label-detector）: 画像の内容に基づいてラベルを割り当てます。
    • 画像露骨なコンテンツ検出 （content-safety）: 成人向け、暴力的なコンテンツ、その他の機密性の高いコンテンツを検出します。
    • PDF 分類 （pdf-classification）: ドキュメントの主題カテゴリを識別します。

    各モデルとその出力スキーマの詳細については、 サポートされているモデルとスキーマをご覧ください。

  5. [Select processing location] ステップで、[Processing location] メニューからマルチリージョン ロケーション（us、eu、または asia）を選択し、[Continue] をクリックします。

  6. [必要な権限を付与] ステップで、オブジェクト エンリッチメント サービス エージェントに必要な IAM ロールを付与する方法を選択します。

    • プロジェクト全体の権限を付与: プロジェクト内の現在および将来のすべての Cloud Storage バケットを処理するために必要なロール（roles/storage.annotationGeneratorService と roles/storage.bucketViewer）をサービス エージェントに自動的に付与します。このオプションを選択するには、プロジェクトに対する resourcemanager.projects.setIamPolicy 権限が必要です。この権限がない場合、このオプションは使用できません。
    • 後で手動で権限を付与: 権限をすぐに付与せずに構成を作成します。Cloud Storage がオブジェクトを処理する 前に、 サービス エージェントに権限を付与する必要があります。

  7. [作成] をクリックします。

    特徴構成を作成すると、長時間実行オペレーションが開始されます。オペレーションが完了すると、 コンソールに Google Cloud 構成の詳細ページが開きます。If you selected [Grant project-wide permission], the Google Cloud console applies the IAM policy bindings after creating the configuration.

コマンドライン

特徴構成を作成するには、 gcloud alpha storage feature-configs create コマンドを使用します。

gcloud alpha storage feature-configs create FEATURE_CONFIG_ID \
    --description="DESCRIPTION" \
    --auto-annotate-models=MODELS \
    --auto-annotate-processing-location=PROCESSING_LOCATION \
    --include-bucket-id-regexes=BUCKET_NAME

ここで

  • FEATURE_CONFIG_ID は、特徴構成の一意の ID です。1 ～ 63 文字で、小文字で始まり、小文字、数字、ハイフンのみを含める必要があります。ハイフンで終わることはできません。
  • DESCRIPTION は、特徴構成の説明です（省略可）。例: Scan invoices and receipts
  • MODELS は、有効にする機械学習モデルのカンマ区切りのリストです（face-detector、object-detector、label-detector、content-safety、pdf-classification）。各モデルとその出力スキーマの詳細については、サポートされているモデルと スキーマをご覧ください。
  • PROCESSING_LOCATION は、データ処理が行われるマルチリージョン処理ロケーションです。サポートされている値は us、eu、asia です。
  • BUCKET_NAME は、この構成に含めるバケットの正確な名前です。正確なバケット名のカンマ区切りのリストを指定できます。

JSON API

  1. gcloud CLI のインストールと初期化を行います。これにより、 Authorization ヘッダーのアクセス トークンを生成できます。

  2. 特徴構成の設定を含む JSON ファイルを作成します。

    {
  "description": "DESCRIPTION",
  "autoAnnotateConfig": {
    "models": [
      { "name": "MODEL_NAME" }
    ],
    "processingLocation": "PROCESSING_LOCATION"
  },
  "filter": {
    "includedCloudStorageBuckets": {
      "bucketIdRegexes": [
        "BUCKET_NAME"
      ]
    }
  }
}

    ここで

    • DESCRIPTION は、特徴構成の説明です（省略可）。例: Scan invoices and receipts

    • MODEL_NAME は、有効にする機械学習モデルの名前です（face-detector、object-detector、label-detector、content-safety、pdf-classification）。各 モデルとその出力スキーマの詳細については、サポートされているモデルとスキーマをご覧ください。 複数のモデルを有効にするには、追加のモデル オブジェクトを models 配列に追加します。

    • PROCESSING_LOCATION は、データ処理が行われるマルチリージョン処理ロケーションです。サポートされている値は us、eu、asia です。

    • BUCKET_NAME は、構成に含めるバケットの正確な名前です。例: my-bucket複数のバケットを含めるには、追加のバケット名文字列を bucketIdRegexes 配列に指定します。

  3. cURL を使用して、featureConfigs.create リクエスト を JSON API に送信します。

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs?featureConfigId=FEATURE_CONFIG_ID"

    ここで

    • JSON_FILE_NAME は、前の手順で作成した JSON ファイルのパスです。例: config.json
    • PROJECT_ID は、 Google Cloud プロジェクト ID です。例: my-project
    • FEATURE_CONFIG_ID は、特徴構成の一意の ID です。例: my-feature-config1 ～ 63 文字で、小文字で始まり、小文字、数字、ハイフンのみを含める必要があります。ハイフンで終わることはできません。

  4. 省略可: 特徴構成の作成の長時間実行 オペレーションのステータスを確認するには、cURL を使用して operations.get リクエストを JSON APIに送信します。

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/operations/OPERATION_ID"

    ここで

    • PROJECT_ID は、 Google Cloud プロジェクト ID です。例: my-project
    • OPERATION_ID は、作成レスポンスで返されるオペレーション ID です。

  5. 省略可: アクティブなオペレーションと履歴オペレーションをすべて一覧表示するには、 cURL を使用して operations.list リクエストを JSON API に送信します。

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/operations"

    ここで、PROJECT_ID は Google Cloud プロジェクト ID です。例: my-project

サービス エージェントに権限を付与する

特徴構成を作成すると、 Google Cloud はプロジェクト専用のサービス エージェント service-PROJECT_NUMBER@gcp-sa-autoannotate.iam.gserviceaccount.com をプロビジョニングします。

このサービス エージェントがバケットをスキャンし、構造化されていないオブジェクトを読み取り、エンリッチメント メタデータを添付できるようにするには、必要な IAM ロールを付与する必要があります。

Console

特徴構成の作成時に [後で手動で権限を付与] を選択した場合、またはプロジェクト全体の権限を再適用する必要がある場合は、構成の詳細ページから権限を付与できます。

  1. コンソール Google Cloud で、Cloud Storage の [オブジェクト エンリッチメント] ページに移動します。

    [オブジェクト エンリッチメント] に移動

  2. [構成名] 列で、特徴構成の名前をクリックします。

  3. アクションバーで [権限を付与] をクリックします。

  4. [権限を付与] ペインで、[プロジェクト全体の権限を付与] をクリックします。

    この操作により、サービス エージェントにプロジェクトに対するストレージ アノテーション生成サービス （roles/storage.annotationGeneratorService）ロールとストレージ バケット閲覧者 （roles/storage.bucketViewer）ロールが付与されます。 コンソールで Google Cloud プロジェクト全体の権限を付与するには、プロジェクトに対する resourcemanager.projects.setIamPolicy 権限が必要です。

    プロジェクト全体ではなく個々のバケットに roles/storage.annotationGeneratorService ロールを付与するには、Google Cloud CLI を使用します。

コマンドライン

  1. モニタリング対象の各バケットまたはプロジェクト レベルで、サービス エージェントにストレージ アノテーション生成サービス （roles/storage.annotationGeneratorService）ロールを付与します。

    • 特定の バケットにロールを付与するには、 gcloud storage buckets add-iam-policy-binding コマンドを使用します。

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.iam.gserviceaccount.com \
    --role=roles/storage.annotationGeneratorService

      ここで

      • BUCKET_NAME は、権限を付与するバケットの名前です。
      • PROJECT_NUMBER は Google Cloud プロジェクト番号です。

    • プロジェクト内のすべての バケットにロールを付与するには、 gcloud projects add-iam-policy-binding コマンドを使用します。

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.iam.gserviceaccount.com \
    --role=roles/storage.annotationGeneratorService

      ここで

      • PROJECT_ID は Google Cloud プロジェクト ID です。
      • PROJECT_NUMBER は Google Cloud プロジェクト番号です。

  2. サービス エージェントがバケット構成を検査できるように、プロジェクト レベルでStorage バケット閲覧者 （roles/storage.bucketViewer） ロールを付与するには、gcloud projects add-iam-policy-binding コマンドを使用します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.iam.gserviceaccount.com \
    --role=roles/storage.bucketViewer

    ここで

    • PROJECT_ID は、 Google Cloud プロジェクト ID です。
    • PROJECT_NUMBER は Google Cloud プロジェクト番号です。

ロールを付与した後、非同期処理が開始されるまでに IAM 権限が反映されるまでに数分かかることがあります。

すべての特徴構成を一覧表示する

プロジェクト内のすべての特徴構成を一覧表示するには、次の操作を行います。

Console

  1. コンソール Google Cloud で、Cloud Storage の [オブジェクト エンリッチメント] ページに移動します。

    [オブジェクト エンリッチメント] に移動

    [構成] タブには、プロジェクト内のすべての特徴構成が一覧表示されます。有効なモデル、処理を行うロケーション、スコープ、バケット フィルタ、作成日、最終更新日などが表示されます。

  2. 省略可: リストをフィルタするには、[フィルタ] フィールドにプロパティ名または値を入力します。

コマンドライン

gcloud alpha storage feature-configs list コマンドを使用します。

gcloud alpha storage feature-configs list

JSON API

  1. gcloud CLI のインストールと初期化を行います。これにより、 Authorization ヘッダーのアクセス トークンを生成できます。

  2. cURL を使用して、featureConfigs.list リクエスト を JSON API に送信します。

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs"

    ここで、PROJECT_ID はプロジェクトの Google Cloud ID です。例: my-project

特徴構成の詳細を表示する

特定の特徴構成のモデル、ターゲット バケット、処理を行うロケーションを検査するには、次の操作を行います。

Console

  1. コンソール Google Cloud で、Cloud Storage の [オブジェクト エンリッチメント] ページに移動します。

    [オブジェクト エンリッチメント] に移動

  2. [構成名] 列で、検査する特徴構成の名前をクリックします。

    構成の詳細ページには、構成名、説明、スコープ、含まれるバケット、処理を行うロケーション、有効なモデル、作成日、最終更新日が表示されます。

コマンドライン

gcloud alpha storage feature-configs describe コマンドを使用します。

gcloud alpha storage feature-configs describe FEATURE_CONFIG_ID

FEATURE_CONFIG_ID は、特徴構成の ID に置き換えます。

JSON API

  1. gcloud CLI のインストールと初期化を行います。これにより、 Authorization ヘッダーのアクセス トークンを生成できます。

  2. cURL を使用して、featureConfigs.get リクエスト を JSON API に送信します。

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID"

    ここで

    • PROJECT_ID は Google Cloud プロジェクトの ID です。例: my-project
    • FEATURE_CONFIG_ID は、特徴構成の ID です。例: my-feature-config

特徴構成を更新する

既存の特徴構成を更新して、機械学習モデルの追加または削除、ターゲット バケットの変更、処理を行うロケーションの変更、説明の更新を行うことができます。

Console

  1. コンソール Google Cloud で、Cloud Storage の [オブジェクト エンリッチメント] ページに移動します。

    [オブジェクト エンリッチメント] に移動

  2. [構成名] 列で、更新する特徴構成の名前をクリックします。

  3. 構成の詳細ページで、変更する設定を更新します。

    • 説明を更新するには、 [Edit configuration description] の横にある [Configuration description] をクリックします。[説明を編集] ペインで、[説明] フィールドのテキストを更新し、[保存] をクリックします。
    • バケット スコープを更新するには、 [Edit configuration scope] の横にある [Configuration scope] をクリックします。[スコープを定義] ステップで、[バケット名] フィールドでターゲット バケットを追加または削除し、[続行] をクリックします。[必要な権限を付与] ステップで、サービス エージェントの権限オプションを選択し、[保存] をクリックします。
    • 処理を行うロケーションを更新するには、[処理を行うロケーション] の横にある [Edit configuration] [processing location] をクリックします。[**処理を行うロケーションの編集**] ペインで、[**処理を行うロケーション**] メニューからマルチリージョン ロケーション（us、eu、または asia）を選択し、 [保存] をクリックします。
    • 有効なモデルを更新するには、[有効なモデル] の横にある [Edit configuration enabled models] をクリックします。[モデルを編集] ペインで、更新するモデルのチェックボックスをオンまたはオフにして、[保存] をクリックします。

コマンドライン

gcloud alpha storage feature-configs update コマンドを使用して、 説明、モデル、処理を行うロケーション、バケット フィルタを更新します。

gcloud alpha storage feature-configs update FEATURE_CONFIG_ID \
    --description="DESCRIPTION" \
    --auto-annotate-models=MODELS \
    --auto-annotate-processing-location=PROCESSING_LOCATION \
    --include-bucket-id-regexes=BUCKET_NAME

次のように置き換えます。

  • FEATURE_CONFIG_ID: 更新する特徴構成の ID。
  • DESCRIPTION: 特徴構成の説明（省略可）。例: Scan invoices and receipts
  • MODELS: 有効にする機械学習モデルのカンマ区切りのリスト（face-detector、object-detector、label-detector、content-safety、pdf-classification）。
  • PROCESSING_LOCATION: データ処理が行われるマルチリージョン処理ロケーション。有効な値は us、eu、asia です。
  • BUCKET_NAME: スキャンする正確なバケット名のカンマ区切りのリスト。オブジェクト エンリッチメントでは、ワイルドカードや正規表現はサポートされていません。バケットを作成、再作成、または再配置する場合は、それらを含めるようにこのリストを更新する必要があります。

JSON API

  1. gcloud CLI のインストールと初期化を行います。これにより、 Authorization ヘッダーのアクセス トークンを生成できます。

  2. 更新する設定を含む JSON ファイルを作成します。 たとえば、説明、有効なモデル、ターゲット バケットを更新するには、次のようにします。

    {
  "description": "DESCRIPTION",
  "autoAnnotateConfig": {
    "models": [
      { "name": "MODEL_NAME" }
    ],
    "processingLocation": "PROCESSING_LOCATION"
  },
  "filter": {
    "includedCloudStorageBuckets": {
      "bucketIdRegexes": [
        "BUCKET_NAME"
      ]
    }
  }
}

    ここで

    • DESCRIPTION は、特徴構成の説明です（省略可）。例: Scan invoices and receipts

    • MODEL_NAME は、含める機械学習モデルです（face-detector、object-detector、label-detector、content-safety、pdf-classification）。各 モデルとその出力スキーマの詳細については、サポートされているモデルとスキーマをご覧ください。複数のモデルを有効にするには、追加のモデル オブジェクトを models 配列に追加します。

    • PROCESSING_LOCATION は、データ処理が行われるマルチリージョン処理ロケーションです。有効な値は us、eu、asia です。

    • BUCKET_NAME は、スキャンに含めるバケットの正確な名前です。例: my-bucketオブジェクト エンリッチメントでは、正規表現やワイルドカードはサポートされていません。バケットを作成、再作成、または再配置する場合は、それらを含めるようにこのリストを更新する必要があります。複数のバケットを含めるには、追加のバケット名文字列を bucketIdRegexes 配列に指定します。

  3. cURL を使用して、featureConfigs.patch リクエスト を JSON API に送信します。

    curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID?updateMask=UPDATE_MASK"

    ここで

    • JSON_FILE_NAME は、ステップ 2 で作成した JSON リクエスト ファイルのローカルパスです。例: update.json
    • PROJECT_ID は Google Cloud プロジェクトの ID です。例: my-project
    • FEATURE_CONFIG_ID は、更新する特徴構成の ID です。例: my-feature-config
    • UPDATE_MASK は、更新するフィールドのカンマ区切りのリストです（description,filter、autoAnnotateConfig.models など）。構文ルールについては、FieldMask をご覧ください。

特徴構成を削除する

特徴構成を削除すると、Cloud Storage は一致するバケットの新しいエンリッチメントを生成しなくなります。構成を削除しても、保存されているオブジェクトにすでに添付されている既存のエンリッチメントは削除されません。

特徴構成を削除するには、次の操作を行います。

Console

  1. コンソール Google Cloud で、Cloud Storage の [オブジェクト エンリッチメント] ページに移動します。

    [オブジェクト エンリッチメント] に移動

  2. [構成名] 列で、削除する特徴 構成の名前をクリックし、 [削除] をクリックします。

  3. 確認のダイアログで [確認] をクリックします。

コマンドライン

gcloud alpha storage feature-configs delete コマンドを使用します。

gcloud alpha storage feature-configs delete FEATURE_CONFIG_ID

FEATURE_CONFIG_ID は、特徴構成の ID に置き換えます。

JSON API

  1. gcloud CLI のインストールと初期化を行います。これにより、 Authorization ヘッダーのアクセス トークンを生成できます。

  2. cURL を使用して、featureConfigs.delete リクエスト を JSON API に送信します。

    curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID"

    ここで

    • PROJECT_ID は Google Cloud プロジェクトの ID です。例: my-project
    • FEATURE_CONFIG_ID は、削除する特徴構成の ID です。例: my-feature-config

次のステップ