创建和管理实例

本页面介绍了如何创建和管理 AML AI 实例 可用作快速参考指南。

准备工作

创建实例

有些 API 方法会返回 长时间运行的操作 (LRO)。 这些方法是异步的,并返回 Operation 对象;有关详情,请参阅 REST 参考文档。通过 操作可能尚未完成。对于这些方法,请将 然后查看结果一般来说,所有 POST、PUT、UPDATE 和 DELETE 操作 长期运行

发送请求

如需创建实例,请使用 projects.locations.instances.create 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_IDIAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION密钥环的位置 以及实例请使用 支持的区域
    显示位置
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID:用户定义的实例标识符
  • KMS_PROJECT_ID:Google Cloud 项目 包含密钥环的项目的 ID
  • KEY_RING_ID:用户定义的 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": "2023-03-14T15:52:55.358979323Z",
    "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:列出的 Google Cloud 项目 ID 在 IAM 设置
  • LOCATION:实例的位置;使用以下任一 该 支持的区域
    显示位置
    • 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": "2023-03-14T15:52:55.358979323Z",
    "endTime": "2023-03-14T16:52:55.358979323Z",
    "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_IDIAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION:实例的位置;使用以下任一 该 支持的区域
    显示位置
    • 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": "2023-03-14T15:52:55.358979323Z",
  "updateTime": "2023-03-15T15:52:55.358979323Z",
  "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID",
  "state": "ACTIVE"
}

更新实例

如需更新实例,请使用 projects.locations.instances.patch 方法。

并非所有实例中的字段都可以更新。以下示例将更新 键值对 用户标签 实例关联的资源

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_IDIAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION:实例的位置;使用以下任一 该 支持的区域
    显示位置
    • 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": "2023-03-14T15:52:55.358979323Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

如需详细了解如何获取长时间运行的操作 (LRO) 的结果,请参阅 检查结果

列出实例

要列出给定实例的实例,请使用 projects.locations.instances.list 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_IDIAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION:实例的位置;使用以下任一 该 支持的区域
    显示位置
    • 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": "2023-03-14T15:52:55.358979323Z",
      "updateTime": "2023-03-15T15:52:55.358979323Z",
      "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID",
      "state": "ACTIVE"
    }
  ]
}

导入注册方

要导入注册方,请先为以下对象准备一个 BigQuery 表: 您要注册合作方的业务范围。如需了解详情,请参阅 注册客户。 使用以下架构之一:

  • 零售方架构

    类型说明
    party_idSTRING实例数据集中一方的唯一标识符
    party_sizeSTRINGNULL;内容会被忽略,供零售方注册使用

  • 商业方架构

    类型说明
    party_idSTRING实例数据集中一方的唯一标识符
    party_sizeSTRING 请求的就餐人数。该层级根据 在过去 365 天内的用户: <ph type="x-smartling-placeholder">
      </ph>
    • 对于平均每月交易次数低于 500 笔的小型商业交易方,SMALL
    • LARGE(适用于平均每月交易次数大于或等于 500 笔)的大型商业方

    所有值都区分大小写。

要导入注册方,请使用 projects.locations.instances.importRegisteredParties 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_IDIAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION:实例的位置;使用以下任一 该 支持的区域
    显示位置
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID:用户定义的实例标识符
  • BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME:a 包含描述注册方的表的 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": "2023-03-14T15:52:55.358979323Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "importRegisteredParties",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

如需详细了解如何获取长时间运行的操作 (LRO) 的结果,请参阅 检查结果

LRO 完成后,响应会显示 操作的添加、移除或更新操作。

响应字段类型说明
partiesAddedinteger 此操作添加的参与方数量
partiesRemovedinteger 此操作移除的正文数量
partiesTotalinteger 更新操作完成后,在此实例中注册的方总数 已完成
partiesUptieredinteger 从小到大增加的商业方总数
partiesDowntieredinteger 按照从大到小的顺序排列的商业方总数
partiesFailedToDowntierinteger 未能从大到小的商业方总数
partiesFailedToRemoveinteger 此操作未能移除的各方数

导出注册方

如需导出注册方,请使用 projects.locations.instances.exportRegisteredParties 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_IDIAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION:实例的位置;使用以下任一 该 支持的区域
    显示位置
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID:用户定义的实例标识符
  • BQ_OUTPUT_DATASET_NAME:a 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": "2023-03-14T15:52:55.358979323Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "exportRegisteredParties",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

如需详细了解如何获取长时间运行的操作 (LRO) 的结果,请参阅 检查结果

此方法会输出具有以下架构的 BigQuery 表:

类型说明
party_idSTRING实例数据集中一方的唯一标识符
party_sizeSTRING 为商业客户指定层级(大或小)。此字段不适用 零售客户。
  • 所有零售客户均可享受 NULL 优惠
  • 对于平均每月交易次数低于 500 笔的小型商业交易方,SMALL
  • LARGE(适用于平均每月交易次数大于或等于 500 笔)的大型商业方

所有值都区分大小写。

earliest_remove_timeSTRING可以删除当事方的最早时间
party_with_prediction_intentSTRING表明自注册以来是否预计会参加该派对的指示符
registration_or_uptier_timeSTRING方注册或升级的时间

如需了解详情,请参阅 注册客户

删除实例

如需删除实例,请使用 projects.locations.instances.delete 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_IDIAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION:实例的位置;使用以下任一 该 支持的区域
    显示位置
    • 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": "2023-03-14T15:52:55.358979323Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

如需详细了解如何获取长时间运行的操作 (LRO) 的结果,请参阅 检查结果