This page shows you how to create and manage AML AI instances and can be used as a quick reference guide.
Before you begin
-
To get the permissions that you need to create and manage instances, ask your administrator to grant you the Financial Services Admin (
financialservices.admin
) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.You might also be able to get the required permissions through custom roles or other predefined roles.
- Create an encryption key and grant access to the key
Create an instance
Some API methods return a long-running operation (LRO). These methods are asynchronous and return an Operation object; for details, see REST Reference. The operation might not be completed when the method returns a response. For these methods, send the request and then check for the result. In general, all POST, PUT, UPDATE, and DELETE operations are long-running.
Send the request
To create an instance, use the
projects.locations.instances.create
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1instances.create
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the key ring and the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: a user-defined identifier for the instanceINSTANCE_ID
: the Google Cloud project ID for the project containing the key ringKMS_PROJECT_ID
: the user-defined identifier for the key ringKEY_RING_ID
: the user-defined identifier for the keyKEY_ID
Request JSON body:
{ "kmsKey": "projects/KMS_PROJECT_ID /locations/LOCATION /keyRings/KEY_RING_ID /cryptoKeys/KEY_ID " }
To send your request, choose one of these options:
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "kmsKey": "projects/KMS_PROJECT_ID /locations/LOCATION /keyRings/KEY_RING_ID /cryptoKeys/KEY_ID " } EOF
Then execute the following command to send your REST request:
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 "
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "kmsKey": "projects/KMS_PROJECT_ID /locations/LOCATION /keyRings/KEY_RING_ID /cryptoKeys/KEY_ID " } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$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
You should receive a JSON response similar to the following:
{ "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 }
Check for the result
Use the
projects.locations.operations.get
method to check if the instance has been created. If the response contains
"done": false
, repeat the command until the response contains "done": true
.
This operation can take a few minutes to complete.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.operations.get
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the identifier for the operationOPERATION_ID
To send your request, choose one of these options:
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /operations/OPERATION_ID "
Execute the following command:
$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
You should receive a JSON response similar to the following:
{ "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 " } }
Get an instance
To get an instance, use the
projects.locations.instances.get
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1instances.get
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
To send your request, choose one of these options:
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID "
Execute the following command:
$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
You should receive a JSON response similar to the following:
{ "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" }
Update an instance
To update an instance, use the
projects.locations.instances.patch
method.
Not all fields in an instance can be updated. The following example updates the key-value pair user labels associated with the instance.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1instances.update
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
: The key in a key-value pair used to organize instances. SeeKEY labels
for more information.
: The value in a key-value pair used to organize instances. SeeVALUE labels
for more information.
Request JSON body:
{ "labels": { "KEY ": "VALUE " } }
To send your request, choose one of these options:
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "labels": { "KEY ": "VALUE " } } EOF
Then execute the following command to send your REST request:
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"
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "labels": { "KEY ": "VALUE " } } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$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
You should receive a JSON response similar to the following:
{ "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 }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.
List the instances
To list the instances for a given instance, use the
projects.locations.instances.list
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1instances.list
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instances; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
To send your request, choose one of these options:
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances"
Execute the following command:
$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
You should receive a JSON response similar to the following:
{ "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" } ] }
Import registered parties
To import registered parties, first prepare a BigQuery table for the line of business you want to register parties for. For more information, see Register your customers. Use one of the following schemas:
Retail parties schema
Commercial parties schema
Column Type Description party_id
STRING
Unique identifier of the party in the instance's datasets party_size
STRING
Requested party size. The tier is based on the average number of monthly transactions for the party over the preceding 365 days: SMALL
for small commercial parties with less than 500 average monthly transactionsLARGE
for large commercial parties with greater than or equal to 500 average monthly transactions
All values are case sensitive.
To import registered parties, use the
projects.locations.instances.importRegisteredParties
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1instances.importRegisteredParties
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
: a BigQuery dataset that contains a table that describes the registered partiesBQ_INPUT_REGISTERED_PARTIES_DATASET_NAME
: the table that lists the registered partiesPARTY_REGISTRATION_TABLE
: useUPDATE_MODE REPLACE
to replace parties that are removable in the registered parties table with new parties, or useAPPEND
to add new parties to the registered parties table
: this field must match theLINE_OF_BUSINESS lineOfBusiness
value in the engine version used by the engine config; useCOMMERCIAL
for commercial banking customers (legal and natural entities), or useRETAIL
for retail banking customers
Request JSON body:
{ "partyTables": [ "bq://PROJECT_ID .BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME .PARTY_REGISTRATION_TABLE " ], "mode": "UPDATE_MODE ", "lineOfBusiness": "LINE_OF_BUSINESS " }
To send your request, choose one of these options:
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
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
Then execute the following command to send your REST request:
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"
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "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
Then execute the following command to send your REST request:
$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
You should receive a JSON response similar to the following:
{ "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 }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.
When the LRO completes, the response indicates the number of parties that the operation added, removed, or updated.
Response field | Type | Description |
---|---|---|
partiesAdded | integer |
Number of parties added by this operation |
partiesRemoved | integer |
Number of parties removed by this operation |
partiesTotal | integer |
Total number of parties that are registered in this instance, after the update operation was completed |
partiesUptiered | integer |
Total number of commercial parties that are uptiered from small to large |
partiesDowntiered | integer |
Total number of commercial parties that are downtiered from large to small |
partiesFailedToDowntier | integer |
Total number of commercial parties that failed to downtier from large to small |
partiesFailedToRemove | integer |
Number of parties that failed to be removed by this operation |
Export registered parties
To export registered parties, use the
projects.locations.instances.exportRegisteredParties
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1instances.exportRegisteredParties
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
: a BigQuery dataset in which to export a table that describes the registered partiesBQ_OUTPUT_DATASET_NAME
: the table to write the registered parties toPARTY_REGISTRATION_TABLE
: the action that occurs if the destination table already exists; use one of the following values:WRITE_DISPOSITION -
WRITE_EMPTY
: Only export data if the BigQuery table is empty. -
WRITE_TRUNCATE
: Erase all existing data in the BigQuery table before writing to the table.
-
: useLINE_OF_BUSINESS COMMERCIAL
for commercial banking customers (legal and natural entities), or useRETAIL
for retail banking customers
Request JSON body:
{ "dataset": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .PARTY_REGISTRATION_TABLE ", "writeDisposition": "WRITE_DISPOSITION " }, "lineOfBusiness": "LINE_OF_BUSINESS " }
To send your request, choose one of these options:
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "dataset": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .PARTY_REGISTRATION_TABLE ", "writeDisposition": "WRITE_DISPOSITION " }, "lineOfBusiness": "LINE_OF_BUSINESS " } EOF
Then execute the following command to send your REST request:
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"
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "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
Then execute the following command to send your REST request:
$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
You should receive a JSON response similar to the following:
{ "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 }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.
This method outputs a BigQuery table with the following schema:
Column | Type | Description |
---|---|---|
party_id | STRING | Unique identifier of the party in the instance's datasets |
party_size | STRING |
Specifies the tier for commercial customers (large versus small). This field does not apply
to retail customers.
All values are case sensitive. |
earliest_remove_time | STRING | The earliest time at which the party can be removed |
party_with_prediction_intent | STRING | The indicator that suggests if a party has been predicted on since the registration |
registration_or_uptier_time | STRING | The time at which the party was registered or uptiered |
For more information, see Register your customers.
Delete an instance
To delete an instance, use the
projects.locations.instances.delete
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1instances.delete
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
To send your request, choose one of these options:
Execute the following command:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID "
Execute the following command:
$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
You should receive a JSON response similar to the following:
{ "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 }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.