Registe os seus clientes

Esta página explica os seguintes passos para registar e anular o registo de participantes de forma a criar resultados de previsões:

  1. Certifique-se de que está pronto para registar festas
  2. Prepare as tabelas de registo de partidos
  3. Use o método projects.locations.instances.importRegisteredParties para registar ou anular o registo de partidos
  4. Valide a resposta do método
  5. (Opcional) Exporte uma tabela de partidos registados

Antes de começar

Antes de começar, precisa de uma instância de IA da AML.

Para permitir que um modelo crie previsões de pontuação de risco, primeiro tem de registar as partes. Recomendamos que registe partes quando já tiver o seguinte:

Quando registar partes

Antes de poder criar previsões para uma parte num dos seus conjuntos de dados, tem de registar a parte. Não é necessário registo para a preparação, ajuste ou testes retroativos.

Os resultados da previsão são usados na investigação de clientes por branqueamento de capitais numa fase de produção ou de testes (paralela). Também pode criar os seus próprios processos de análise de modelos e governação com base nos resultados que obtém das previsões.

As partes registadas incorrem em custos mensais adicionais por parte registada (consulte a página de preços para mais informações).

Como preparar tabelas de registo de partidos

Leia a página de preços para obter informações sobre o registo de partes.

Prepare uma tabela para a linha de negócio para a qual quer registar partes. Se já tiver algumas entidades registadas, esta tabela de registo de entidades pode conter um subconjunto das entidades da tabela Entidade que quer usar para os resultados da previsão.

Esquema de partes de retalho

ColunaTipoDescrição
party_idSTRINGIdentificador exclusivo da entidade nos conjuntos de dados da instância
party_sizeSTRINGNULL; o conteúdo é ignorado para registos de festas de retalho

Esquema de partes comerciais

ColunaTipoDescrição
party_idSTRINGIdentificador exclusivo da entidade nos conjuntos de dados da instância
party_sizeSTRING Número de pessoas do grupo pedido. O nível baseia-se no número médio de transações mensais da entidade nos 365 dias anteriores:
  • SMALL para partes comerciais pequenas com uma média mensal de menos de 500 transações
  • LARGE para grandes empresas comerciais com uma média mensal de transações igual ou superior a 500

Todos os valores são sensíveis a maiúsculas e minúsculas.

Como registar festas

As partes são registadas separadamente para cada instância de IA de AML. Tenha em atenção o seguinte:

  • Os retalhistas e as partes comerciais têm de estar registados separadamente. Use chamadas de API separadas e tabelas de registo de terceiros separadas. Se uma parte estiver em ambas as listas, é considerada um registo separado.
  • As previsões requerem que todas as partes estejam registadas na linha de negócio associada à versão do motor usada. Não pode criar resultados de previsão se for usado um conjunto de dados que contenha qualquer parte não registada na mesma linha de negócio.
  • A tabela de registo de entidades fornecida é usada para anexar à lista existente de entidades registadas na instância ou substituir todas as entidades registadas para a linha de negócio fornecida na instância.
  • Após o registo, não é possível anular o registo de uma festa durante algum tempo (consulte a página de preços). Por este motivo, pode definir o campo validateOnly como TRUE. Este campo permite-lhe ver o efeito líquido e a resposta do método sem alterar as partes registadas. Depois de validado, pode executar novamente a operação e definir o parâmetro validateOnly como FALSE.
  • Verifique sempre a resposta de um pedido de registo para garantir que todas as partes foram registadas com êxito, mesmo que um pedido validateOnly anterior tenha sido bem-sucedido.
  • Para registos de partes comerciais, um valor diferente de SMALL ou LARGE no campo party_size na tabela de registo de partes aciona um erro (Invalid party_size present in table). As partes registadas não são atualizadas.
  • Para registos de entidades de retalho, o campo party_size é ignorado e todas as entidades na tabela de registo de entidades fornecida são registadas.

Para importar partes registadas, use o método projects.locations.instances.importRegisteredParties.

(As seguintes informações também estão disponíveis no artigo Crie e faça a gestão de instâncias.)

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto indicado nas definições de IAM
  • LOCATION: a localização da instância; use uma das regiões suportadas
    Mostrar localizações
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: o identificador definido pelo utilizador para a instância
  • BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME: a Conjunto de dados do BigQuery que contém uma tabela que descreve as partes registadas
  • PARTY_REGISTRATION_TABLE: a tabela que indica as partes registadas
  • UPDATE_MODE: use REPLACE para substituir as partes que são removíveis na tabela de partes registadas por novas partes ou use APPEND para adicionar novas partes à tabela de partes registadas
  • LINE_OF_BUSINESS: este campo tem de corresponder ao valor lineOfBusiness no engine version usado pela engine config; use COMMERCIAL para clientes de banca comercial (entidades legais e naturais) ou use RETAIL para clientes de banca de retalho

Corpo JSON do pedido: 

{
  "partyTables": [
     "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE"
  ],
  "mode": "UPDATE_MODE",
  "lineOfBusiness": "LINE_OF_BUSINESS"
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

@'
{
  "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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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
}

Para obter informações sobre como receber o resultado da operação de longa duração (LRO), consulte o artigo Faça a gestão de operações de longa duração.

Resposta de registo

Quando a LRO estiver concluída, a resposta indica o número de partes que foram adicionadas, removidas ou atualizadas pela operação.

Campo de respostaTipoDescrição
partiesAddedinteger Número de participantes adicionados por esta operação
partiesRemovedinteger Número de partes removidas por esta operação
partiesTotalinteger Número total de partes registadas nesta instância após a conclusão da operação de atualização
partiesUptieredinteger Número total de partes comerciais que são promovidas de pequenas a grandes
partiesDowntieredinteger Número total de partes comerciais que são rebaixadas de grandes para pequenas
partiesFailedToDowntierinteger Número total de partes comerciais que não conseguiram descer de nível de grande para pequeno
partiesFailedToRemoveinteger Número de participantes que não foram removidos por esta operação

Como anular o registo de partes

As partes são anuladas por instância da IA de AML através do mesmo método projects.locations.instances.importRegisteredParties e substituindo a lista de partes existente. Defina o campo mode como REPLACE. Esta definição anula o registo de todas as partes atualmente registadas (para a linha de negócio fornecida) que não façam parte da tabela de registo de partes fornecida.

Respostas de anulação do registo

Após a conclusão da operação, verifique a resposta da API para verificar se a operação produziu o resultado pretendido em termos do número de partes adicionadas ou removidas e o número total de partes registadas.

A resposta da API também devolve o número de partes que não foi possível remover devido a restrições. Por exemplo, não é possível anular o registo de um cliente até ter decorrido um número mínimo de dias.

Exporte partes registadas

Para exportar partes registadas, use o método projects.locations.instances.exportRegisteredParties.

(As seguintes informações também estão disponíveis no artigo Crie e faça a gestão de instâncias.)

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto indicado nas definições de IAM
  • LOCATION: a localização da instância; use uma das regiões suportadas
    Mostrar localizações
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: o identificador definido pelo utilizador para a instância
  • BQ_OUTPUT_DATASET_NAME: um conjunto de dados do BigQuery no qual exportar uma tabela que descreve as partes registadas
  • PARTY_REGISTRATION_TABLE: a tabela para escrever as partes registadas
  • WRITE_DISPOSITION: a ação que ocorre se a tabela de destino já existir; use um dos seguintes valores:
    • WRITE_EMPTY: exporte dados apenas se a tabela do BigQuery estiver vazia.
    • WRITE_TRUNCATE: apaga todos os dados existentes na tabela do BigQuery antes de escrever na tabela.
  • LINE_OF_BUSINESS: use COMMERCIAL para clientes de banca comercial (entidades legais e naturais) ou use RETAIL para clientes de banca de retalho

Corpo JSON do pedido: 

{
  "dataset": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  },
  "lineOfBusiness": "LINE_OF_BUSINESS"
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

cat > request.json << 'EOF'
{
  "dataset": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  },
  "lineOfBusiness": "LINE_OF_BUSINESS"
}
EOF

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

@'
{
  "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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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
}

Para obter informações sobre como receber o resultado da operação de longa duração (LRO), consulte o artigo Faça a gestão de operações de longa duração.

Este método gera uma tabela do BigQuery com o seguinte esquema:

ColunaTipoDescrição
party_idSTRINGIdentificador exclusivo da entidade nos conjuntos de dados da instância
party_sizeSTRING Especifica o nível para clientes comerciais (grandes ou pequenos). Este campo não se aplica a clientes de retalho.
  • NULL para todos os clientes de retalho
  • SMALL para partes comerciais pequenas com uma média mensal de menos de 500 transações
  • LARGE para grandes empresas comerciais com uma média mensal de transações igual ou superior a 500

Todos os valores são sensíveis a maiúsculas e minúsculas.

earliest_remove_timeSTRINGA hora mais antiga em que a parte pode ser removida
party_with_prediction_intentSTRINGO indicador que sugere se uma festa foi prevista desde o registo
registration_or_uptier_timeSTRINGA hora em que a parte foi registada ou atualizada