Registrar seus partidos

Esta página mostra as etapas para registrar e cancelar o registro de partes para criar resultados de previsão:

Verifique se você está pronto para registrar partidos
Preparar as tabelas de registro de partidos
Use o método projects.locations.instances.importRegisteredParties para registrar ou cancelar o registro de partes.
Validar a resposta do método
(Opcional) Exportar uma tabela de partes registradas

Antes de começar

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

Para permitir que um modelo crie previsões de pontuação de risco, primeiro é preciso registrar partes. Recomendamos que você registre partes quando já tiver o seguinte:

Um ou mais conjuntos de dados
Um modelo ajustado, treinado e com backtest

Quando registrar eventos

Antes de criar previsões para uma parte em um dos seus conjuntos de dados, é necessário registrar a parte. Não é necessário fazer inscrição para treinamento, ajuste ou backtesting.

Os resultados da Prediction são usados para investigar clientes por lavagem de dinheiro em uma fase de produção ou de teste (paralela). Também é possível criar seus próprios processos de governança e análise de modelo com base nos resultados das previsões.

O registro de partes gera custos mensais adicionais por parte registrada. Consulte a página de preços para mais informações.

Como preparar tabelas de registro de partidos

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

Prepare uma tabela para a linha de negócios em que você quer registrar as partes. Se você já tiver algumas partes registradas, essa tabela poderá conter um subconjunto das partes da tabela Parte que você quer usar para resultados de previsão.

Esquema de partes de varejo

Coluna	Tipo	Descrição
`party_id`	`STRING`	Identificador exclusivo da parte nos conjuntos de dados da instância.
`party_size`	`STRING`	NULL; o conteúdo é ignorado para registros de partes de varejo

Esquema de partes comerciais

Coluna Tipo Descrição

party_id STRING Identificador exclusivo da parte nos conjuntos de dados da instância.

party_size

STRING

Tamanho do grupo solicitado. O nível é baseado no número médio de transações mensais da parte nos 365 dias anteriores:

SMALL para pequenas empresas comerciais com menos de 500 transações mensais em média
LARGE para grandes empresas comerciais com 500 ou mais transações mensais em média

Todos os valores diferenciam maiúsculas de minúsculas.

Como registrar partidos

As partes são registradas separadamente para cada instância da IA de AML. Observações:

Os varejistas e as partes comerciais precisam ser registrados separadamente. Use chamadas de API e tabelas de registro de terceiros separadas. Se uma parte estiver nas duas listas, elas serão consideradas registros separados.
Para fazer previsões, todas as partes precisam estar registradas na linha de negócios associada à versão do mecanismo usada. Não é possível criar resultados de previsão se um conjunto de dados for usado e contiver uma parte não registrada na mesma linha de negócios.
A tabela de registro de partes fornecida é usada para adicionar ao final à lista atual de partes registradas na instância ou substituir todas as partes registradas na linha de negócios fornecida na instância.
Depois de registrada, uma festa não pode ser cancelada por algum tempo (consulte a página de preços). Por esse motivo, defina o campo validateOnly como TRUE. Esse campo permite conferir o efeito líquido e a resposta do método sem mudar as partes registradas. Depois de validar, é possível executar a operação novamente e definir o parâmetro validateOnly como FALSE.
Sempre verifique a resposta de uma solicitação de registro para garantir que todas as partes foram registradas com sucesso, mesmo que uma solicitação validateOnly anterior tenha sido bem-sucedida.
Para registros de partes comerciais, um valor diferente de SMALL ou LARGE no campo party_size da tabela de registro de partes aciona um erro (Invalid party_size present in table). As partes registradas não são atualizadas.
Para registros de partes de varejo, o campo party_size é ignorado e todas as partes na tabela de registro fornecida são registradas.

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

As informações a seguir também estão disponíveis em Criar e gerenciar instâncias.

Permissões exigidas para a tarefa

Para executar esta tarefa, é necessário ter as seguintes permissões:

Permissões

financialservices.v1instances.importRegisteredParties

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do seu Google Cloud projeto listado nas Configurações do IAM
LOCATION: o local da instância. Use uma das regiões compatíveis
Mostrar locais
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
- australia-southeast1
INSTANCE_ID: o identificador definido pelo usuário para a instância
BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME: um conjunto de dados do BigQuery que contém uma tabela com a descrição das partes registradas.
PARTY_REGISTRATION_TABLE: a tabela que lista as partes registradas.
Observação: é possível fornecer várias tabelas que listam as partes registradas. Use o formato "bq://{project}.{bqDatasetID}.{bqTableID}" para cada tabela na matriz partyTables.
UPDATE_MODE: use REPLACE para substituir partes removíveis na tabela de partes registradas por novas partes ou use APPEND para adicionar novas partes à tabela de partes registradas.
LINE_OF_BUSINESS: esse campo precisa corresponder ao valor lineOfBusiness na versão do mecanismo usada pela configuração do mecanismo. Use COMMERCIAL para clientes de banco comercial (pessoas jurídicas e físicas) ou RETAIL para clientes de banco de varejo.

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você tenha feito login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na gcloud CLI. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo 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

Depois execute o comando a seguir para enviar a solicitação 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

Observação: o comando a seguir pressupõe que você fez login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo 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

Depois execute o comando a seguir para enviar a solicitação 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

Você receberá uma resposta JSON semelhante a esta:

{
  "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 informações sobre como receber o resultado da operação de longa duração (LRO), consulte Gerenciar operações de longa duração.

Resposta de registro

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

Campo de resposta	Tipo	Descrição
`partiesAdded`	`integer`	Número de partes adicionadas por esta operação
`partiesRemoved`	`integer`	Número de partes removidas por esta operação
`partiesTotal`	`integer`	Número total de partes registradas nesta instância após a conclusão da operação de atualização.
`partiesUptiered`	`integer`	Número total de partes comerciais que são promovidas de pequenas para grandes
`partiesDowntiered`	`integer`	Número total de partes comerciais que são rebaixadas de grandes para pequenas
`partiesFailedToDowntier`	`integer`	Número total de partes comerciais que não puderam ser rebaixadas de grande para pequena
`partiesFailedToRemove`	`integer`	Número de partes que não foram removidas por esta operação

Como cancelar o registro de partes

As partes são canceladas por instância de IA de AML usando o mesmo método projects.locations.instances.importRegisteredParties e substituindo a lista de partes atual. Defina o campo mode como REPLACE. Essa configuração cancela o registro de todas as partes registradas (para a linha de negócios fornecida) que não fazem parte da tabela de registro de partes fornecida.

Respostas de cancelamento de registro

Depois que a operação for concluída, verifique a resposta da API para saber se ela gerou o resultado esperado em termos de número de partes adicionadas ou removidas e o número total de partes registradas.

A resposta da API também retorna o número de partes que não puderam ser removidas devido a restrições. Por exemplo, um cliente não pode ser cancelado até que um número mínimo de dias tenha passado.

Exportar partes registradas

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

As informações a seguir também estão disponíveis em Criar e gerenciar instâncias.

Permissões exigidas para a tarefa

Para executar esta tarefa, é necessário ter as seguintes permissões:

Permissões

financialservices.v1instances.exportRegisteredParties

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do seu Google Cloud projeto listado nas Configurações do IAM
LOCATION: o local da instância. Use uma das regiões compatíveis
Mostrar locais
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
- australia-southeast1
INSTANCE_ID: o identificador definido pelo usuário para a instância
BQ_OUTPUT_DATASET_NAME: um conjunto de dados do BigQuery em que exportar uma tabela que descreve as partes registradas
PARTY_REGISTRATION_TABLE: a tabela em que as partes registradas serão gravadas.
WRITE_DISPOSITION: a ação que ocorre se a tabela de destino já existir. Use um dos seguintes valores:
- WRITE_EMPTY: só exporta dados se a tabela do BigQuery estiver vazia.
- WRITE_TRUNCATE: apague todos os dados atuais na tabela do BigQuery antes de gravar nela.
LINE_OF_BUSINESS: use COMMERCIAL para clientes de serviços bancários comerciais (pessoas jurídicas e físicas) ou RETAIL para clientes de serviços bancários de varejo

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo 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

Depois execute o comando a seguir para enviar a solicitação 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

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo 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

Depois execute o comando a seguir para enviar a solicitação 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

Você receberá uma resposta JSON semelhante a esta:

{
  "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 informações sobre como receber o resultado da operação de longa duração (LRO), consulte Gerenciar operações de longa duração.

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

Coluna	Tipo	Descrição
`party_id`	`STRING`	Identificador exclusivo da parte nos conjuntos de dados da instância.
`party_size`	`STRING`	Especifica o nível para clientes comerciais (grandes ou pequenos). Esse campo não se aplica a clientes de varejo. `NULL` para todos os clientes do varejo `SMALL` para pequenas empresas comerciais com menos de 500 transações mensais em média `LARGE` para grandes empresas comerciais com 500 ou mais transações mensais em média Todos os valores diferenciam maiúsculas de minúsculas.
`earliest_remove_time`	`STRING`	A primeira data e hora em que a parte pode ser removida
`party_with_prediction_intent`	`STRING`	O indicador que sugere se um partido foi previsto desde o registro
`registration_or_uptier_time`	`STRING`	O horário em que a parte foi registrada ou fez upgrade

Registrar seus partidos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Quando registrar eventos

Como preparar tabelas de registro de partidos

Esquema de partes de varejo

Esquema de partes comerciais

Como registrar partidos

Permissões exigidas para a tarefa

curl

PowerShell

Resposta de registro

Como cancelar o registro de partes

Respostas de cancelamento de registro

Exportar partes registradas

Permissões exigidas para a tarefa

curl

PowerShell

Registrar seus partidos