Google Cloud コンソールからエンティティ調整ジョブを実行する

このクイックスタートでは、Entity Reconciliation API について説明します。このクイックスタートでは、 Google Cloud コンソールを使用してGoogle Cloud プロジェクトと承認を設定し、スキーマ マッピング ファイルを作成して、Enterprise Knowledge Graph にエンティティ調整ジョブの実行をリクエストします。

このタスクを Google Cloud コンソールで直接行う際の順を追ったガイダンスについては、「ガイドを表示」をクリックしてください。

ガイドを表示

データソースを特定する

Entity Reconciliation API は、入力として BigQuery テーブルのみをサポートします。データが BigQuery に保存されていない場合は、コネクタがさらに利用可能になる前に、データを BigQuery に転送することをおすすめします。また、構成したサービス アカウントまたは OAuth クライアントに、使用する予定のテーブルに対する読み取りアクセス権と、宛先データセットに対する書き込み権限があることを確認してください。

スキーマ マッピング ファイルを作成する

データソースごとに、Enterprise Knowledge Graph にデータの取り込み方法を通知するスキーマ マッピング ファイルを作成する必要があります。

Enterprise Knowledge Graph は、YARRRML という人間が読めるシンプルな形式の言語を使用して、ソーススキーマとターゲットの共通グラフ オントロジー schema.org 間のマッピングを定義します。

Enterprise Knowledge Graph は、1 対 1 の単純なマッピングのみをサポートしています。

schema.org の型に対応する次のエンティティ タイプがサポートされています。

スキーマ マッピング ファイルの例

組織

prefixes:
  ekg: http://cloud.google.com/ekg/0.0.1#
  schema: https://schema.org/

mappings:
  Organization:
    sources:
      - [example_project:example_dataset.example_table~bigquery]
    s: ekg:company_$(record_id)
    po:
      - [a, schema:Organization]
      - [schema:name, $(company_name_in_source)]
      - [schema:streetAddress, $(street)]
      - [schema:postalCode, $(postal_code)]
      - [schema:addressCountry, $(country)]
      - [schema:addressLocality, $(city)]
      - [schema:addressRegion, $(state)]
      - [ekg:recon.source_name, $(source_system)]
      - [ekg:recon.source_key, $(source_key)]

LocalBusiness

prefixes:
  ekg: http://cloud.google.com/ekg/0.0.1#
  schema: https://schema.org/
mappings:
  LocalBusiness:
    sources:
      - [example_project:example_dataset.example_table~bigquery]
    s: ekg:local_business_$(record_id)
    po:
      - [a, schema:LocalBusiness]
      - [schema:name, $(company_name_in_source)]
      - [schema:streetAddress, $(street)]
      - [schema:postalCode, $(postal_code)]
      - [schema:addressCountry, $(country)]
      - [schema:addressLocality, $(city)]
      - [schema:addressRegion, $(state)]
      - [schema:url, $(url)]
      - [schema:telephone, $(telephone)]
      - [schema:latitude, $(latitude)]
      - [schema:longitude, $(longitude)]
      - [ekg:recon.source_name, $(source_system)]
      - [ekg:recon.source_key, $(source_key)]

人物

prefixes:
  ekg: http://cloud.google.com/ekg/0.0.1#
  schema: https://schema.org/
mappings:
  Person:
    sources:
      - [example_project:example_dataset.example_table~bigquery]
    s: ekg:person_$(record_id)
    po:
      - [a, schema:Person]
      - [schema:postalCode, $(ZIP)]
      - [schema:birthDate, $(BIRTHDATE)]
      - [schema:name, $(NAME)]
      - [schema:gender, $(GENDER)]
      - [schema:streetAddress, $(ADDRESS)]
      - [ekg:recon.source_name, (Patients)]
      - [ekg:recon.source_key, $(source_key)]

ソース文字列 example_project:example_dataset.example_table~bigquery の場合、~bigquery はデータソースが BigQuery からのものであることを示す固定文字列です。

述語リスト（po）では、ekg:recon.source_name と ekg:recon.source_key はシステムで使用される予約済みの述語名であり、マッピング ファイルで常に言及する必要があります。通常、述語 ekg:recon.source_name はソースの定数値（この例では (Patients)）を受け取ります。述語 ekg:recon.source_key は、ソーステーブルの一意のキー（この例では $(source_key)）を受け取ります。これは、ソース列 ID の変数値を表します。

マッピング ファイルで複数のテーブルまたはソースを定義する場合、または 1 回の API 呼び出しで異なるマッピング ファイルを定義する場合は、サブジェクト値が異なるソース間で一意であることを確認する必要があります。接頭辞とソース列キーを組み合わせて一意にすることができます。たとえば、同じスキーマを持つ 2 つの人物テーブルがある場合、サブジェクト（s）値に異なる形式（ekg:person1_$(record_id) と ekg:person2_$(record_id)）を割り当てることができます。

テーブル スキーマの例

マッピング ファイルの例を次に示します。

prefixes:
  ekg: http://cloud.google.com/ekg/0.0.1#
  schema: https://schema.org/
mappings:
  organization:
    sources:
      - [ekg-api-test:demo.organization~bigquery]
    s: ekg:company_$(source_key)
    po:
      - [a, schema:Organization]
      - [schema:name, $(source_name)]
      - [schema:streetAddress, $(street)]
      - [schema:postalCode, $(postal_code)]
      - [schema:addressCountry, $(country)]
      - [schema:addressLocality, $(city)]
      - [schema:addressRegion, $(state)]
      - [ekg:recon.source_name, (org)]
      - [ekg:recon.source_key, $(primary_key)]

この例では、テーブル スキーマ自体にこのデータソースの名前（通常はテーブル名またはデータベース名）が含まれていません。そのため、ドル記号 $ のない静的文字列「org」を使用します。

エンティティ調整ジョブを作成する

Google Cloud コンソールを使用して、調整ジョブを作成します。

  1. Enterprise Knowledge Graph ダッシュボードを開きます。

    Enterprise Knowledge Graph ダッシュボードに移動します

  2. [スキーマ マッピング] をクリックして、各データソースのテンプレートからマッピング ファイルを作成し、Cloud Storage に保存します。

    UI の [Schema Mapping] オプションから

  3. [Job]、[Run A Job] の順にクリックして、ジョブを開始する前にジョブ パラメータを構成します。

    エンティティ タイプ

    値 モデル名 説明
    Organization google_brasil Organization レベルでエンティティを調整します。たとえば、会社としての法人の名前。これは、特定の支店、スポット、物理的な場所（たとえば、複数の企業キャンパスの 1 つ）に焦点を当てる LocalBusiness とは異なります。
    LocalBusiness google_cyprus 特定の支店、スポット、実店舗に基づいてエンティティを調整します。地理座標をモデル入力として受け取ることもできます。
    Person google_atlantis schema.org の事前定義された属性のセットに基づいて、人物エンティティを調整します。

    データソース

    BigQuery テーブルのみがサポートされています。

    目的地

    出力パスは、Enterprise Knowledge Graph に書き込み権限がある BigQuery データセットである必要があります。

    実行されたジョブごとに、Enterprise Knowledge Graph はタイムスタンプ付きの新しい BigQuery テーブルを作成して結果を保存します。

    Entity Reconciliation API を使用する場合、ジョブ レスポンスには完全な出力テーブル名とロケーションが含まれます。

  4. 必要に応じて [詳細オプション] を構成します。

  5. ジョブを開始するには、[完了] をクリックします。

ジョブのステータスをモニタリングする

ジョブのステータスは、 Google Cloud コンソールと API の両方からモニタリングできます。データセット内のレコード数によっては、ジョブの完了に最大 24 時間かかることがあります。個々のジョブをクリックして、ジョブの詳細な構成を確認します。

ジョブ履歴 UI

ジョブのステータスを調べて、現在のステップを確認することもできます。

ジョブの表示状態 コードの状態 説明
実行中 JOB_STATE_RUNNING ジョブは進行中です。
ナレッジの抽出 JOB_STATE_KNOWLEDGE_EXTRACTION Enterprise Knowledge Graph は、BigQuery からデータを抽出し、特徴を作成しています。
調整の前処理中 JOB_STATE_RECON_PREPROCESSING ジョブは調整の前処理ステップにあります。
クラスタリング JOB_STATE_CLUSTERING ジョブはクラスタリング ステップにあります。
クラスタのエクスポート中 JOB_STATE_EXPORTING_CLUSTERS ジョブは出力を BigQuery の宛先データセットに書き込んでいます。

各ジョブの実行時間は、データの複雑さ、データセットのサイズ、同時に実行されている他の並列ジョブの数など、多くの要因によって異なります。参考として、ジョブの実行時間とデータセットのサイズのおおよその見積もりを以下に示します。実際のジョブ完了時間は異なります。

レコードの合計数 実行時間
10 万人 2 時間以下
1 億 約 16 時間
3 億 約 24 時間

調整ジョブをキャンセルする

実行中のジョブは、 Google Cloud コンソール（ジョブの詳細ページ）と API の両方から cancel できます。Enterprise Knowledge Graph は、ベスト エフォートで可能な限り早くジョブを停止します。cancel コマンドが成功するとは限りません。

詳細オプション

構成 説明
以前の結果の BigQuery テーブル 以前の結果テーブルを指定すると、クラスタ ID がさまざまなジョブで安定します。その後、クラスタ ID を永続 ID として使用できます。
アフィニティ クラスタリング ほとんどの場合におすすめのオプションです。これは階層型凝集クラスタリングの並列バージョンであり、スケーリングに優れています。クラスタリング ラウンド（イテレーション）の数は、[1, 5] の範囲で指定できます。数値が大きいほど、アルゴリズムはクラスタを過剰に統合する傾向があります。
連結成分クラスタリング デフォルトのオプション。これは代替のレガシー オプションです。アフィニティ クラスタリングがデータセットでうまく機能しない場合にのみ、このオプションを試してください。重みしきい値は、[0.6, 1] の範囲の数値にできます。
ジオコーディング分離 このオプションにより、異なる地理的リージョンのエンティティが一緒にクラスタ化されることはありません。