使用 API 管理实体协调作业

本快速入门为您介绍实体调和 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")