This quickstart introduces you to the Entity Reconciliation API. In this quickstart, you use the Google Cloud console to set up your Google Cloud project and authentication, create schema mapping files, and then make a request for Enterprise Knowledge Graph to run an entity reconciliation job.
Create an entity reconciliation job
Use the following steps to create an entity reconciliation job:
REST
To create a simple job with one source table (deduplication), call the projects.locations.entityReconciliationJobs.create
method.
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
- LOCATION: Knowledge Graph location.
- Options:
global
- Global Endpoint
- Options:
- DATASET_ID: ID of the BigQuery Dataset
- TABLE_ID: ID of the BigQuery Table
- MAPPING_FILE_URI: Cloud Storage path to a mapping file in YAML format.
- Example:
gs://ekg-test-gcs/mapping.yml
- Example:
- ENTITY_TYPE: Entity Type for reconciliation.
HTTP method and URL:
POST https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs
Request JSON body:
{ "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" } }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
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
Save the request body in a file named request.json
,
and execute the following command:
$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
You should receive a JSON response similar to the following:
{ "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" }
{
"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
For more information, see the Enterprise Knowledge Graph Python API reference documentation.
To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Get an entity reconciliation job
REST
To retrieve job status from the API, call the projects.locations.entityReconciliationJobs.get
method.
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
- LOCATION: Knowledge Graph location.
- Options:
global
- Global Endpoint
- Options:
- JOB_ID: Entity Reconciliation Job ID.
- Example:
2628838070002699773
- Example:
HTTP method and URL:
GET https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
You should receive a JSON response similar to the following:
{ "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
For more information, see the Enterprise Knowledge Graph Python API reference documentation.
To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
List entity reconciliation jobs
REST
To retrieve all the jobs from the API, call the projects.locations.entityReconciliationJobs.list
method.
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
- LOCATION: Knowledge Graph location.
- Options:
global
- Global Endpoint
- Options:
HTTP method and URL:
GET https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs
To send your request, choose one of these options:
curl
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs"
PowerShell
Execute the following command:
$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
You should receive a JSON response similar to the following:
{ "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
For more information, see the Enterprise Knowledge Graph Python API reference documentation.
To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Cancel an entity reconciliation job
REST
To stop a running job from the API, call the projects.locations.entityReconciliationJobs.cancel
method.
Enterprise Knowledge Graph stops the job at the earliest opportunity. Note that canceling a job is on a best-efforts basis. The success of the cancel
command isn't guaranteed.
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
- LOCATION: Knowledge Graph location.
- Options:
global
- Global Endpoint
- Options:
- JOB_ID: Entity Reconciliation Job ID.
- Example:
2628838070002699773
- Example:
HTTP method and URL:
POST https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID:cancel
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
You should receive a successful status code (2xx) and an empty response.
Python
For more information, see the Enterprise Knowledge Graph Python API reference documentation.
To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Delete an entity reconciliation job
REST
To remove a completed or failed job with the API, call the projects.locations.entityReconciliationJobs.delete
method.
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
- LOCATION: Knowledge Graph location.
- Options:
global
- Global Endpoint
- Options:
- JOB_ID: Entity Reconciliation Job ID.
- Example:
2628838070002699773
- Example:
HTTP method and URL:
DELETE https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entityReconciliationJobs/JOB_ID
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
You should receive a successful status code (2xx) and an empty response.
Python
For more information, see the Enterprise Knowledge Graph Python API reference documentation.
To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.