本页面介绍了如何创建和管理 AML AI 实例,可用作快速参考指南。
准备工作
-
如需获取创建和管理实例所需的权限,请让管理员向您授予项目的 Financial Services Admin (
financialservices.admin
) IAM 角色。如需详细了解如何授予角色,请参阅管理访问权限。 - 创建加密密钥并授予对密钥的访问权限
创建实例
某些 API 方法会返回长时间运行的操作 (LRO)。这些方法是异步的。当该方法返回响应时,操作可能尚未完成。对于这些方法,请发送请求,然后检查结果。
发送请求
如需创建实例,请使用 projects.locations.instances.create
方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID
:IAM 设置中列出的 Google Cloud 项目 IDLOCATION
:密钥环的位置和实例;请使用某个受支持的区域显示位置us-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
:用户定义的实例标识符KMS_PROJECT_ID
:包含密钥环的项目的 Google Cloud 项目 IDKEY_RING_ID
:用户定义的密钥环标识符KEY_ID
:用户定义的密钥标识符
请求 JSON 正文:
{ "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID" }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json
的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
cat > request.json << 'EOF' { "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID" } EOF
然后,执行以下命令以发送 REST 请求:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?instance_id=INSTANCE_ID"
PowerShell
将请求正文保存在名为 request.json
的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
@' { "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID" } '@ | Out-File -FilePath request.json -Encoding utf8
然后,执行以下命令以发送 REST 请求:
$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://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?instance_id=INSTANCE_ID" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
查看结果
使用 projects.locations.operations.get
方法检查是否已创建实例。如果响应包含 "done": false
,请重复该命令,直到响应包含 "done": true
。此操作可能需要几分钟时间才能完成。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID
:IAM 设置中列出的 Google Cloud 项目 IDLOCATION
:实例的位置;请使用某个受支持的区域显示位置us-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
OPERATION_ID
:操作的标识符
如需发送请求,请选择以下方式之一:
curl
执行以下命令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
PowerShell
执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": CREATE_TIME, "endTime": END_TIME, "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.Instance", "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "createTime": CREATE_TIME, "updateTime": UPDATE_TIME, "state": "ACTIVE", "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID" } }
获取实例
如需获取实例,请使用 projects.locations.instances.get
方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID
:IAM 设置中列出的 Google Cloud 项目 IDLOCATION
:实例的位置;请使用某个受支持的区域显示位置us-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
:用户定义的实例标识符
如需发送请求,请选择以下方式之一:
curl
执行以下命令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID"
PowerShell
执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "createTime": CREATE_TIME, "updateTime": UPDATE_TIME, "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID", "state": "ACTIVE" }
更新实例
如需更新实例,请使用 projects.locations.instances.patch
方法。
并非所有实例中的字段都可以更新。以下示例会更新与实例关联的键值对用户标签。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID
:IAM 设置中列出的 Google Cloud 项目 IDLOCATION
:实例的位置;请使用某个受支持的区域显示位置us-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
:用户定义的实例标识符KEY
:键值对中用于组织实例的键。如需了解详情,请参阅labels
。VALUE
:用于组织实例的键值对中的值。如需了解详情,请参阅labels
。
请求 JSON 正文:
{ "labels": { "KEY": "VALUE" } }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json
的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
cat > request.json << 'EOF' { "labels": { "KEY": "VALUE" } } EOF
然后,执行以下命令以发送 REST 请求:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID?updateMask=labels"
PowerShell
将请求正文保存在名为 request.json
的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
@' { "labels": { "KEY": "VALUE" } } '@ | Out-File -FilePath request.json -Encoding utf8
然后,执行以下命令以发送 REST 请求:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID?updateMask=labels" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "verb": "update", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
如需详细了解如何获取长时间运行的操作 (LRO) 的结果,请参阅检查结果。
列出实例
如需列出给定实例的实例,请使用 projects.locations.instances.list
方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID
:IAM 设置中列出的 Google Cloud 项目 IDLOCATION
:实例的位置;请使用某个受支持的区域显示位置us-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
如需发送请求,请选择以下方式之一:
curl
执行以下命令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances"
PowerShell
执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "instances": [ { "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "createTime": CREATE_TIME, "updateTime": UPDATE_TIME, "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID", "state": "ACTIVE" } ] }
导入注册方
如需导入已注册的实体,请先为您要注册它们的业务领域准备一个 BigQuery 表。如需了解详情,请参阅注册客户。 使用以下架构之一:
零售方架构
列 类型 说明 party_id
STRING
实例数据集中一方的唯一标识符 party_size
STRING
NULL;零售方注册会忽略内容 商业方架构
列 类型 说明 party_id
STRING
实例数据集中一方的唯一标识符 party_size
STRING
请求的就餐人数。层级基于该方在过去 365 天内的平均每月交易次数: - 对于平均每月交易次数低于 500 笔的小型商业交易方,
SMALL
LARGE
(适用于平均每月交易次数大于或等于 500 笔)的大型商业方
所有值都区分大小写。
- 对于平均每月交易次数低于 500 笔的小型商业交易方,
如需导入已注册的各方,请使用 projects.locations.instances.importRegisteredParties
方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID
:IAM 设置中列出的 Google Cloud 项目 IDLOCATION
:实例的位置;请使用某个受支持的区域显示位置us-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
:用户定义的实例标识符BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME
:一个 BigQuery 数据集,其中包含描述注册方的表PARTY_REGISTRATION_TABLE
:列出已注册方的表UPDATE_MODE
:使用REPLACE
将注册方表中可移除的各方替换为新方,或使用APPEND
将新方添加到注册方表中LINE_OF_BUSINESS
:此字段必须与引擎配置所用引擎版本中的lineOfBusiness
值一致;对于商业银行客户(法律实体和自然实体),请使用COMMERCIAL
;对于零售银行客户,请使用RETAIL
请求 JSON 正文:
{ "partyTables": [ "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE" ], "mode": "UPDATE_MODE", "lineOfBusiness": "LINE_OF_BUSINESS" }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json
的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
cat > request.json << 'EOF' { "partyTables": [ "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE" ], "mode": "UPDATE_MODE", "lineOfBusiness": "LINE_OF_BUSINESS" } EOF
然后,执行以下命令以发送 REST 请求:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:importRegisteredParties"
PowerShell
将请求正文保存在名为 request.json
的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
@' { "partyTables": [ "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE" ], "mode": "UPDATE_MODE", "lineOfBusiness": "LINE_OF_BUSINESS" } '@ | Out-File -FilePath request.json -Encoding utf8
然后,执行以下命令以发送 REST 请求:
$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://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:importRegisteredParties" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "verb": "importRegisteredParties", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
如需详细了解如何获取长时间运行的操作 (LRO) 的结果,请参阅检查结果。
LRO 完成后,响应会指明操作添加、移除或更新的各方数。
响应字段 | 类型 | 说明 |
---|---|---|
partiesAdded | integer |
此操作添加的协议方数量 |
partiesRemoved | integer |
此操作移除的正文数量 |
partiesTotal | integer |
完成更新操作后,在此实例中注册的方总数 |
partiesUptiered | integer |
从小到大增加的商业方总数 |
partiesDowntiered | integer |
按从大到小的顺序排列的商业方总数 |
partiesFailedToDowntier | integer |
未能从大到小的商业方总数 |
partiesFailedToRemove | integer |
此操作未能移除的各方数 |
导出注册方
如需导出已注册方,请使用 projects.locations.instances.exportRegisteredParties
方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID
:IAM 设置中列出的 Google Cloud 项目 IDLOCATION
:实例的位置;请使用某个受支持的区域显示位置us-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
:用户定义的实例标识符BQ_OUTPUT_DATASET_NAME
:一个 BigQuery 数据集,用于导出描述注册方的表PARTY_REGISTRATION_TABLE
:要将已注册方写入其中的表WRITE_DISPOSITION
:目标表已存在时执行的操作;请使用以下值之一:-
WRITE_EMPTY
:仅在 BigQuery 表为空时导出数据。 -
WRITE_TRUNCATE
:在向表写入数据之前,清空 BigQuery 表中的所有现有数据。
-
LINE_OF_BUSINESS
:对于商业银行客户(法律和自然实体),请使用COMMERCIAL
;对于零售银行客户,请使用RETAIL
请求 JSON 正文:
{ "dataset": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE", "writeDisposition": "WRITE_DISPOSITION" }, "lineOfBusiness": "LINE_OF_BUSINESS" }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json
的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
cat > request.json << 'EOF' { "dataset": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE", "writeDisposition": "WRITE_DISPOSITION" }, "lineOfBusiness": "LINE_OF_BUSINESS" } EOF
然后,执行以下命令以发送 REST 请求:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:exportRegisteredParties"
PowerShell
将请求正文保存在名为 request.json
的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:
@' { "dataset": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE", "writeDisposition": "WRITE_DISPOSITION" }, "lineOfBusiness": "LINE_OF_BUSINESS" } '@ | Out-File -FilePath request.json -Encoding utf8
然后,执行以下命令以发送 REST 请求:
$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://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:exportRegisteredParties" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "verb": "exportRegisteredParties", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
如需详细了解如何获取长时间运行的操作 (LRO) 的结果,请参阅检查结果。
此方法会输出具有以下架构的 BigQuery 表:
列 | 类型 | 说明 |
---|---|---|
party_id | STRING | 实例数据集中一方的唯一标识符 |
party_size | STRING |
为商业客户指定层级(大或小)。此字段不适用于零售客户。
所有值都区分大小写。 |
earliest_remove_time | STRING | 可以删除当事方的最早时间 |
party_with_prediction_intent | STRING | 表明自注册以来是否预计会参加该派对的指示符 |
registration_or_uptier_time | STRING | 方注册或升级的时间 |
如需了解详情,请参阅注册客户。
删除一个实例
如需删除实例,请使用 projects.locations.instances.delete
方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID
:IAM 设置中列出的 Google Cloud 项目 IDLOCATION
:实例的位置;请使用某个受支持的区域显示位置us-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
:用户定义的实例标识符
如需发送请求,请选择以下方式之一:
curl
执行以下命令:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID"
PowerShell
执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": CREATE_TIME, "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID", "verb": "delete", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
如需详细了解如何获取长时间运行的操作 (LRO) 的结果,请参阅检查结果。