在 BigQuery 中配置和使用实体解析

本文档介绍如何为实体解析最终用户（以下称为“最终用户”）和身份提供方实现实体解析。

最终用户可以使用此文档与身份提供方连接，并使用提供方的服务来匹配记录。身份提供方可以使用本文档设置和配置服务，以在 Google Cloud Marketplace 上分享给最终用户。

最终用户的工作流

以下部分向最终用户介绍如何在 BigQuery 中配置实体解析。如需查看完整设置的直观呈现，请参阅实体解析架构。

准备工作

与身份提供方联系并建立关系。BigQuery 使用 LiveRamp 和 TransUnion 支持实体解析。
从身份提供方获取以下各项：
- 服务账号凭证
- 远程函数签名
在您的项目中创建两个数据集：
- 输入数据集
- 输出数据集

所需的角色

如需获得运行实体解析作业所需的权限，请让您的管理员为您授予以下 IAM 角色：

允许身份提供方的服务账号读取输入数据集和写入输出数据集：
- 输入数据集的 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色
- 输出数据集的 BigQuery Data Editor (roles/bigquery.dataEditor) 角色

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

转换或解析实体

如需了解具体的身份提供方说明，请参阅以下部分。

LiveRamp

前提条件

在 BigQuery 中配置 LiveRamp 嵌入式身份。如需了解详情，请参阅在 BigQuery 中启用 LiveRamp 嵌入式身份。
与 LiveRamp 协调，启用用于嵌入式身份的 API 凭据。如需了解详情，请参阅身份验证。

设置

首次使用 LiveRamp 嵌入式身份时，必须执行以下步骤。设置完成后，在各次运行之间只需修改输入表和元数据表。

创建输入表

在输入数据集中创建一个表。在该表中填充 RampID、目标网域和目标类型。如需了解详情和示例，请参阅输入表列和说明。

创建元数据表

元数据表用于控制 LiveRamp 嵌入式身份在 BigQuery 上的执行。在输入数据集中创建一个元数据表。在该表中填充客户端 ID、执行模式、目标网域和目标类型。如需了解详情和示例，请参阅元数据表列和说明。

向 LiveRamp 共享表

向 LiveRamp Google Cloud 服务账号授予查看和处理输入数据集中数据的权限。如需了解详情和示例，请参阅向 LiveRamp 共享表和数据集。

运行嵌入式身份作业

如需在 BigQuery 中使用 LiveRamp 运行嵌入式身份作业，请执行以下操作：

确认在您的网域中编码的所有 RampID 都包含在输入表中。
在运行作业之前，确认元数据表仍然准确。
使用作业进程请求联系 LiveRampIdentitySupport@liveramp.com。添加输入表、元数据表和输出数据集的项目 ID、数据集 ID 和表 ID（如果适用）。如需了解详情，请参阅通知 LiveRamp 启动转码。

结果通常会在 3 个工作日内提交到输出数据集。

LiveRamp 支持

如有支持问题，请与 LiveRamp 身份支持联系。

LiveRamp 结算

LiveRamp 会处理实体解析的结算。

TransUnion

前提条件

请与 TransUnion Cloud 支持团队联系，以签署协议来访问该服务。提供Google Cloud 项目 ID、输入数据类型、使用情形和数据量方面的详细信息。
TransUnion Cloud 支持团队会为您的 Google Cloud 项目启用该服务，并分享一份详细的实施指南，其中包含可用的输出数据。

设置

在 BigQuery 环境中使用 TransUnion 的 TruAudience Identity Resolution and Enrichment 服务时，您需要执行以下步骤。

创建外部连接

创建与外部数据源的连接，该连接的类型为 Vertex AI 远程模型、远程函数和 BigLake（Cloud 资源）。您将使用此连接从Google Cloud 账号触发在 TransUnion Google Cloud 账号中托管的身份解析服务。

复制连接 ID 和服务账号 ID，然后将这些标识符告知 TransUnion 客户交付团队。

创建远程函数

创建远程函数，该函数与托管在 TransUnion Google Cloud 项目上的服务编排器端点进行交互，以将必要的元数据（包括架构映射）传递给 TransUnion 服务。使用您创建的外部连接中的连接 ID 和 TransUnion 客户交付团队共享的 TransUnion 托管云函数端点。

创建输入表

在输入数据集中创建一个表。TransUnion 支持将姓名、邮寄地址、邮箱、手机号码、出生日期、IPv4 地址和设备 ID 作为输入内容。请遵循 TransUnion 与您分享的实施指南中的格式设置准则。

创建元数据表

创建一个元数据表，用于存储身份解析服务处理数据所需的配置，包括架构映射。如需了解详情和查看示例，请参阅 TransUnion 与您分享的实现指南。

创建作业状态表

创建一个表，用于接收有关输入批次处理的更新。您可以查询此表，以触发流水线中的其他下游进程。作业可能的状态如下：RUNNING、COMPLETED 或 ERROR。

创建服务调用

按照以下步骤操作，在收集所有元数据、将其打包并传递给 TransUnion 托管的调用 Cloud Functions 端点后，调用 TransUnion 身份解析服务。

-- create service invocation procedure
CREATE OR REPLACE
  PROCEDURE
    `<project_id>.<dataset_id>.TransUnion_get_identities`(metadata_table STRING, config_id STRING)
      begin
        declare sql_query STRING;

declare json_result STRING;
declare base64_result STRING;

SET sql_query =
  '''select to_json_string(array_agg(struct(config_id,key,value))) from `''' || metadata_table
  || '''` where  config_id="''' || config_id || '''" ''';

EXECUTE immediate sql_query INTO json_result;

SET base64_result = (SELECT to_base64(CAST(json_result AS bytes)));

SELECT `<project_id>.<dataset_id>.remote_call_TransUnion_er`(base64_result);

END;

创建匹配的输出表

运行以下 SQL 脚本以创建匹配的输出表。这是应用的标准输出，包括匹配标志、得分、永久性个人 ID 和家庭 ID。

-- create output table
CREATE TABLE `<project_id>.<dataset_id>.TransUnion_identity_output`(
  batchid STRING,
  uniqueid STRING,
  ekey STRING,
  hhid STRING,
  collaborationid STRING,
  firstnamematch STRING,
  lastnamematch STRING,
  addressmatches STRING,
  addresslinkagescores STRING,
  phonematches STRING,
  phonelinkagescores STRING,
  emailmatches STRING,
  emaillinkagescores STRING,
  dobmatches STRING,
  doblinkagescore STRING,
  ipmatches STRING,
  iplinkagescore STRING,
  devicematches STRING,
  devicelinkagescore STRING,
  lastprocessed STRING);

配置元数据

按照 TransUnion 与您分享的实现指南，将您的输入架构映射到应用架构。此元数据还会配置协作 ID 的生成，协作 ID 是可在数据净室中使用的可共享的非持久性标识符。

授予读写权限

从 TransUnion 客户交付团队获取 Apache Spark 连接的服务账号 ID，并向其授予对包含输入和输出表的相应数据集的读取和写入权限。建议您为服务账号 ID 授予数据集的 BigQuery Data Editor 角色。

调用应用

您可以通过运行以下脚本从环境中调用应用。

call `<project_id>.<dataset_id>.TransUnion_get_identities`("<project_id>.<dataset_id>.TransUnion_er_metadata","1");
-- using metadata table, and 1 = config_id for the batch run

支持

如需解决技术问题，请与 TransUnion Cloud 支持团队联系。

结算和使用情况

TransUnion 会跟踪应用的使用情况，并将其用于结算。有效客户可以与 TransUnion 交付代表联系，了解详情。

身份提供方的工作流

以下部分向身份提供方介绍如何在 BigQuery 中配置实体解析。如需查看完整设置的直观呈现，请参阅实体解析架构。

准备工作

创建 Cloud Run 作业或 Cloud Run 函数以与远程函数集成。这两个选项都适合此用途。
记下与 Cloud Run 或 Cloud Run 函数关联的服务账号的名称：
1. 在 Google Cloud 控制台中，前往 Cloud Functions 页面。
  
  转到 Cloud Functions
2. 点击函数的名称，然后点击详情标签页。
3. 在常规信息窗格中，找到并记下远程函数的服务账号名称。
创建远程函数。
从最终用户处获取最终用户主账号。

所需的角色

如需获得运行实体解析作业所需的权限，请让您的管理员为您授予以下 IAM 角色：

允许与您的函数关联的服务账号读取和写入关联的数据集和启动作业：
- 项目的 BigQuery Data Editor (roles/bigquery.dataEditor) 角色
- 针对项目的 BigQuery Job User (roles/bigquery.jobUser)。
允许最终用户主账号查看和连接到远程函数：
- 针对连接的 BigQuery Connection User (roles/bigquery.connectionUser)
- 包含远程函数的控制平面数据集的 BigQuery Data Viewer (roles/bigquery.dataViewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

共享实体解析远程函数

修改以下远程接口代码并分享给最终用户。最终用户需要此代码来启动实体解析作业。

`PARTNER_PROJECT_ID.DATASET_ID`.match`(LIST_OF_PARAMETERS)

将 LIST_OF_PARAMETERS 替换为传递给远程函数的参数列表。

可选：提供作业元数据

您可以视情况提供作业元数据，可以使用单独的远程函数，也可以在用户的输出数据集中写入新的状态表。元数据的示例包括作业状态和指标。

身份提供方的结算

为了简化客户结算和新手引导，我们建议您将实体解析服务与 Google Cloud Marketplace 集成。这样，您就可以根据实体解析作业用量设置价格模式，并由 Google 为您处理结算。如需了解详情，请参阅提供软件即服务 (SaaS) 产品。