使用 API 管理實體協調工作

本快速入門導覽課程將介紹 Entity Reconciliation API。在本快速入門導覽課程中，您將使用 Google Cloud 控制台設定Google Cloud 專案和驗證、建立結構定義對應檔案，然後要求 Enterprise Knowledge Graph 執行實體比對工作。

建立實體協調工作

請按照下列步驟建立實體對帳工作：

REST

如要建立含有一個來源資料表 (重複資料刪除) 的簡單工作，請呼叫 projects.locations.entityReconciliationJobs.create 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：知識圖譜位置。
    • 選項：global - 全球端點
  • DATASET_ID：BigQuery 資料集 ID
  • TABLE_ID：BigQuery 資料表 ID
  • MAPPING_FILE_URI：YAML 格式的對應檔案 Cloud Storage 路徑。
    • 範例：gs://ekg-test-gcs/mapping.yml
  • ENTITY_TYPE：對帳的實體類型。

HTTP 方法和網址：

POST https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs

JSON 要求內文：

{
  "inputConfig": {
    "bigqueryInputConfigs": [
      {
        "bigqueryTable": "projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID",
        "gcsUri": "MAPPING_FILE_URI"
      }
    ],
    "entityType": "ENTITY_TYPE"
  },
  "outputConfig": {
    "bigqueryDataset": "projects/PROJECT_ID/datasets/DATASET_ID"
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID",
  "inputConfig": {
    "bigqueryInputConfigs": [
      {
        "bigqueryTable": "projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID",
        "gcsUri": "MAPPING_FILE_URI"
      }
    ],
    "entityType": "ENTITY_TYPE"
  },
  "outputConfig": {
    "bigqueryDataset": "projects/PROJECT_ID/datasets/DATASET_ID"
  },
  "state": "JOB_STATE_RUNNING",
  "createTime": "2021-07-31T14:39:14.145568Z",
  "updateTime": "2021-07-31T14:39:14.145568Z"
}
如要使用進階選項和多個 BigQuery 資料表建立工作，請使用類似下列範例的要求主體： 

{
  "inputConfig": {
    "bigqueryInputConfigs": [
      {
        "bigqueryTable": "projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID",
        "gcsUri": "MAPPING_FILE_URI"
      },
      {
        "bigqueryTable": "projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID",
        "gcsUri": "MAPPING_FILE_URI"
      }
    ],
    "entityType": "ENTITY_TYPE",
    "previousResultBigqueryTable": "projects/PROJECT_ID/datasets/DATASET_ID/tables/clusters_13689265293502324307"
  },
  "outputConfig": {
    "bigqueryDataset": "projects/PROJECT_ID/datasets/DATASET_ID"
  },
  "reconConfig": {
    "affinityClusteringConfig": {
      "compressionRoundCount": "2"
    },
    "options": {
      "enableGeocodingSeparation": true
    }
  }
}

Python

詳情請參閱 Enterprise Knowledge Graph Python API 參考文件。

如要向 Enterprise Knowledge Graph 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'          # Values: 'global'
# input_dataset = 'YOUR_INPUT_DATASET'      # BigQuery Dataset Name
# input_table = 'YOUR_INPUT_TABLE'          # BigQuery Table Name
# mapping_file_uri = 'YOUR_MAPPING_FILE     # GCS Path. Example: gs://ekg-test-gcs/mapping.yml
# output_dataset = 'YOUR_OUTPUT_DATASET'    # BigQuery Dataset Name

# Refer to https://cloud.google.com/enterprise-knowledge-graph/docs/schema
# entity_type = ekg.InputConfig.EntityType.Person


def create_entity_reconciliation_job_sample(
    project_id: str,
    location: str,
    input_dataset: str,
    input_table: str,
    mapping_file_uri: str,
    entity_type: int,
    output_dataset: str,
) -> None:
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the location
    # e.g. projects/{project_id}/locations/{location}
    parent = client.common_location_path(project=project_id, location=location)

    # Input Parameters
    input_config = ekg.InputConfig(
        bigquery_input_configs=[
            ekg.BigQueryInputConfig(
                bigquery_table=client.table_path(
                    project=project_id, dataset=input_dataset, table=input_table
                ),
                gcs_uri=mapping_file_uri,
            )
        ],
        entity_type=entity_type,
    )

    # Output Parameters
    output_config = ekg.OutputConfig(
        bigquery_dataset=client.dataset_path(project=project_id, dataset=output_dataset)
    )

    entity_reconciliation_job = ekg.EntityReconciliationJob(
        input_config=input_config, output_config=output_config
    )

    # Initialize request argument(s)
    request = ekg.CreateEntityReconciliationJobRequest(
        parent=parent, entity_reconciliation_job=entity_reconciliation_job
    )

    # Make the request
    response = client.create_entity_reconciliation_job(request=request)

    print(f"Job: {response.name}")
    print(
        f"Input Table: {response.input_config.bigquery_input_configs[0].bigquery_table}"
    )
    print(f"Output Dataset: {response.output_config.bigquery_dataset}")
    print(f"State: {response.state.name}")

取得實體協調工作

REST

如要從 API 擷取工作狀態，請呼叫 projects.locations.entityReconciliationJobs.get 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：知識圖譜位置。
    • 選項：global - 全球端點
  • JOB_ID：實體協調工作 ID。
    • 範例：2628838070002699773

HTTP 方法和網址：

GET https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令： 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID"

PowerShell

執行下列指令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID",
  "inputConfig": {
    "bigqueryInputConfigs": [
      {
        "bigqueryTable": "projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID",
        "gcsUri": "MAPPING_FILE_URI"
      }
    ],
    "entityType": "ENTITY_TYPE"
  },
  "outputConfig": {
    "bigqueryDataset": "projects/PROJECT_ID/datasets/DATASET_ID"
  },
  "state": "JOB_STATE_SUCCEEDED",
  "createTime": "2021-07-31T14:39:14.145568Z",
  "updateTime": "2021-07-31T14:39:14.145568Z"
}

Python

詳情請參閱 Enterprise Knowledge Graph Python API 參考文件。

如要向 Enterprise Knowledge Graph 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'  # Values: 'global'
# job_id = 'YOUR_JOB_ID'            # Entity Reconciliation Job ID


def get_entity_reconciliation_job_sample(
    project_id: str, location: str, job_id: str
) -> None:
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the job
    # e.g. projects/{project_id}/locations/{location}/entityReconciliationJobs/{entity_reconciliation_job}
    name = client.entity_reconciliation_job_path(
        project=project_id, location=location, entity_reconciliation_job=job_id
    )

    # Initialize request argument(s)
    request = ekg.GetEntityReconciliationJobRequest(name=name)

    # Make the request
    response = client.get_entity_reconciliation_job(request=request)

    print(f"Job: {response.name}")
    print(
        f"Input Table: {response.input_config.bigquery_input_configs[0].bigquery_table}"
    )
    print(f"Output Dataset: {response.output_config.bigquery_dataset}")
    print(f"State: {response.state.name}")

列出實體協調工作

REST

如要從 API 擷取所有工作，請呼叫 projects.locations.entityReconciliationJobs.list 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：知識圖譜位置。
    • 選項：global - 全球端點

HTTP 方法和網址：

GET https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令： 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs"

PowerShell

執行下列指令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "entityReconciliationJobs": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID",
      "inputConfig": {
        "bigqueryInputConfigs": [
          {
            "bigqueryTable": "projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID",
            "gcsUri": "MAPPING_FILE_URI"
          }
        ],
        "entityType": "ENTITY_TYPE"
      },
      "outputConfig": {
        "bigqueryDataset": "projects/PROJECT_ID/datasets/DATASET_ID"
      },
      "state": "JOB_STATE_SUCCEEDED",
      "createTime": "2021-07-31T14:39:14.145568Z",
      "updateTime": "2021-07-31T14:39:14.145568Z"
    }
  ],
  "nextPageToken": ""
}

Python

詳情請參閱 Enterprise Knowledge Graph Python API 參考文件。

如要向 Enterprise Knowledge Graph 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'  # Values: 'global'


def list_entity_reconciliation_jobs_sample(project_id: str, location: str) -> None:
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the location
    # e.g. projects/{project_id}/locations/{location}
    parent = client.common_location_path(project=project_id, location=location)

    # Initialize request argument(s)
    request = ekg.ListEntityReconciliationJobsRequest(parent=parent)

    # Make the request
    pager = client.list_entity_reconciliation_jobs(request=request)

    for response in pager:
        print(f"Job: {response.name}")
        print(
            f"Input Table: {response.input_config.bigquery_input_configs[0].bigquery_table}"
        )
        print(f"Output Dataset: {response.output_config.bigquery_dataset}")
        print(f"State: {response.state.name}\n")

取消實體協調工作

REST

如要透過 API 停止執行中的工作，請呼叫 projects.locations.entityReconciliationJobs.cancel 方法。

Enterprise Knowledge Graph 會盡快停止工作。請注意，系統會盡可能取消工作。我們無法保證 cancel 指令會成功執行。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：知識圖譜位置。
    • 選項：global - 全球端點
  • JOB_ID：實體協調工作 ID。
    • 範例：2628838070002699773

HTTP 方法和網址：

POST https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID:cancel

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID:cancel"

PowerShell

執行下列指令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID:cancel" | Select-Object -Expand Content

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

Python

詳情請參閱 Enterprise Knowledge Graph Python API 參考文件。

如要向 Enterprise Knowledge Graph 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'  # Values: 'global'
# job_id = 'YOUR_JOB_ID'            # Entity Reconciliation Job ID


def cancel_entity_reconciliation_job_sample(
    project_id: str, location: str, job_id: str
) -> None:
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the job
    # e.g. projects/{project_id}/locations/{location}/entityReconciliationJobs/{entity_reconciliation_job}
    name = client.entity_reconciliation_job_path(
        project=project_id, location=location, entity_reconciliation_job=job_id
    )

    # Initialize request argument(s)
    request = ekg.CancelEntityReconciliationJobRequest(name=name)

    # Make the request
    client.cancel_entity_reconciliation_job(request=request)

    print(f"Job: {name} successfully cancelled")

刪除實體協調工作

REST

如要透過 API 移除已完成或失敗的工作，請呼叫 projects.locations.entityReconciliationJobs.delete 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：知識圖譜位置。
    • 選項：global - 全球端點
  • JOB_ID：實體協調工作 ID。
    • 範例：2628838070002699773

HTTP 方法和網址：

DELETE https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令： 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID"

PowerShell

執行下列指令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID" | Select-Object -Expand Content

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

Python

詳情請參閱 Enterprise Knowledge Graph Python API 參考文件。

如要向 Enterprise Knowledge Graph 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'  # Values: 'global'
# job_id = 'YOUR_JOB_ID'            # Entity Reconciliation Job ID


def delete_entity_reconciliation_job_sample(
    project_id: str, location: str, job_id: str
) -> None:
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the job
    # e.g. projects/{project_id}/locations/{location}/entityReconciliationJobs/{entity_reconciliation_job}
    name = client.entity_reconciliation_job_path(
        project=project_id, location=location, entity_reconciliation_job=job_id
    )

    # Initialize request argument(s)
    request = ekg.DeleteEntityReconciliationJobRequest(name=name)

    # Make the request
    client.delete_entity_reconciliation_job(request=request)

    print(f"Job: {name} successfully deleted")