Registra i tuoi clienti

Questa pagina illustra i seguenti passaggi per registrare e annullare la registrazione delle parti al fine di creare risultati di previsione:

1. Assicurati di essere pronto a registrare i gruppi
2. Prepara le tabelle per la registrazione dei gruppi
3. Utilizza il metodo projects.locations.instances.importRegisteredParties per registrare o annullare la registrazione dei soggetti
4. Convalida la risposta del metodo
5. (Facoltativo) Esportare una tabella delle parti registrate

Prima di iniziare

Prima di iniziare, è necessaria un'istanza AML AI.

Per abilitare un modello a creare previsioni del punteggio di rischio, devi prima registrare i parti. Ti consigliamo di registrare i partiti quando disponi già di quanto segue:

• Uno o più set di dati
• Un modello ottimizzato, addestrato e testato in modo retroattivo

Quando registrare i partiti

Prima di poter creare previsioni per una parte in uno dei tuoi set di dati, devi registrare la parte. La registrazione non è necessaria per l'addestramento, l'ottimizzazione o il backtest.

I risultati della previsione vengono utilizzati per indagare sui clienti in caso di riciclaggio di denaro in una fase di produzione o di test/parallela.

Le parti registrate comportano costi mensili aggiuntivi per ogni parte registrata (per ulteriori informazioni, consulta la pagina dei prezzi).

Come preparare le tabelle per la registrazione dei gruppi

Leggi la pagina dei prezzi per informazioni sulla registrazione dei partiti.

Prepara una tabella per la line of business per la quale vuoi registrare i gruppi. Questa tabella di registrazione del partito può essere un sottoinsieme della tabella Partito.

Schema per i rivenditori

Colonna	Tipo	Descrizione
party_id	STRINGA	Identificatore univoco della parte nei set di dati dell'istanza
party_size	STRINGA	NULL; i contenuti vengono ignorati per le registrazioni di rivenditori al dettaglio

Schema delle parti commerciali

Colonna	Tipo	Descrizione
party_id	STRINGA	Identificatore univoco della parte nei set di dati dell'istanza
party_size	STRINGA	Numero di persone richieste. Il livello si basa sul numero medio di transazioni mensili della parte negli ultimi 365 giorni: SMALL per piccole attività commerciali con una media di transazioni mensili inferiore a 500 LARGE per grandi aziende commerciali con una media di transazioni mensili superiore o uguale a 500 Tutti i valori fanno distinzione tra maiuscole e minuscole.

Come registrare i partiti

Le parti vengono registrate separatamente per ogni istanza AI AML. Tieni presente quanto segue:

• I soggetti commerciali e di vendita al dettaglio devono essere registrati separatamente. Utilizza chiamate API separate e tabelle di registrazione dei parti separate. Se una parte è presente in entrambi gli elenchi, viene considerata una registrazione separata.
• Le previsioni richiedono che tutte le parti siano registrate presso la line of business associata alla versione del motore utilizzata. Non puoi creare risultati della previsione se viene utilizzato un set di dati contenente una parte non registrata con la stessa linea di attività.
• La tabella di registrazione delle parti fornita viene utilizzata per aggiungere elementi all'elenco esistente delle parti registrate nell'istanza o per sostituire tutte le parti registrate per la linea di business fornita nell'istanza.
• Una volta effettuata la registrazione, un gruppo non può essere annullato per un determinato periodo di tempo (vedi la pagina dei prezzi). Per questo motivo, puoi impostare il campo validateOnly su TRUE. Questo campo consente di visualizzare l'effetto netto e la risposta del metodo senza modificare le parti registrate. Dopo la convalida, puoi eseguire nuovamente l'operazione e impostare il parametro validateOnly su FALSE.
• Controlla sempre la risposta di una richiesta di registrazione per assicurarti che tutte le parti siano state registrate correttamente, anche se una richiesta validateOnly precedente è andata a buon fine.
• Per le registrazioni di parti commerciali, un valore diverso da SMALL o LARGE nel campo party_size nella tabella di registrazione della parte attiva un errore (Invalid party_size present in table). Le parti registrate non vengono aggiornate.
• Per le registrazioni di una parte retail, il campo party_size viene ignorato e tutte le parti nella tabella di registrazione delle parti fornita vengono registrate.

Per importare i soggetti registrati, utilizza il metodo projects.locations.instances.importRegisteredParties.

Le informazioni seguenti sono disponibili anche in Creare e gestire istanze.

Prima di utilizzare qualsiasi dato della richiesta, effettua le seguenti sostituzioni:

• PROJECT_ID: il tuo ID progetto Google Cloud elencato nelle impostazioni IAM
• LOCATION: la località dell'istanza; utilizza una delle regioni supportate:
  • us-central1
  • us-east1
  • europe-west1
  • europe-west2
  • europe-west4
  • southamerica-east1
• INSTANCE_ID: l'identificatore definito dall'utente per l'istanza
• BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME: un set di dati BigQuery contenente una tabella che descrive le parti registrate
• REGISTERED_PARTIES_TABLE: la tabella che elenca le parti registrate
  Nota: puoi fornire più tabelle che elencano le parti registrate. Utilizza il formato "bq://{project}.{bqDatasetID}.{bqTableID}" per ogni tabella nell'array partyTables.
• UPDATE_MODE: utilizza REPLACE per sostituire i parti rimovibili nella tabella dei parti registrati con nuovi parti oppure utilizza APPEND per aggiungere nuovi parti alla tabella dei parti registrati
• LINE_OF_BUSINESS: questo campo deve corrispondere al valore lineOfBusiness nella versione motore utilizzato dalla configurazione motore; utilizza COMMERCIAL per i clienti bancari commerciali (entità legali e naturali) oppure utilizza RETAIL per i clienti di retail banking

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando di gcloud con il tuo account utente, eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:

cat > request.json << 'EOF'
{
  "partyTables": [
     "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.REGISTERED_PARTIES_TABLE"
  ],
  "mode": "UPDATE_MODE",
  "lineOfBusiness": "LINE_OF_BUSINESS"
}
EOF

Quindi esegui questo comando per inviare la richiesta 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 (Windows)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando di gcloud con il tuo account utente, eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:

@'
{
  "partyTables": [
     "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.REGISTERED_PARTIES_TABLE"
  ],
  "mode": "UPDATE_MODE",
  "lineOfBusiness": "LINE_OF_BUSINESS"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta 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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per informazioni su come ottenere il risultato dell'operazione a lunga esecuzione (LRO), consulta Gestire le operazioni a lunga esecuzione.

Risposta all'iscrizione

Quando l'LRO viene completato, la risposta indica il numero di parti che sono state aggiunte, rimosse o aggiornate dall'operazione.

Campo di risposta	Tipo	Descrizione
partiesAdded	integer	Numero di parti aggiunte da questa operazione
partiesRemoved	integer	Numero di parti rimosse da questa operazione
partiesTotal	integer	Numero totale di parti registrate in questa istanza dopo il completamento dell'operazione di aggiornamento
partiesFailedToRemove	integer	Numero di parti che non è stato possibile rimuovere con questa operazione

Come annullare la registrazione delle parti

La registrazione delle parti viene annullata per istanza AI AML utilizzando lo stesso metodo projects.locations.instances.importRegisteredParties e sostituendo l'elenco esistente di parti. Imposta il campo mode su REPLACE. Questa impostazione annulla la registrazione di tutte le parti attualmente registrate (per la linea di business fornita) che non fanno parte della tabella di registrazione delle parti fornita.

Nota: potrebbe essere applicato un numero minimo di giorni prima che sia possibile annullare la registrazione di un gruppo; consulta la pagina Prezzi. La risposta dell'API indica per quali parti è stata annullata la registrazione.

Risposte relative all'annullamento della registrazione

Al termine dell'operazione, controlla la risposta dell'API per verificare se l'operazione ha portato al risultato previsto in termini di numero di parti aggiunte o rimosse e il numero totale di parti registrate.

La risposta API restituisce anche il numero di parti che non è stato possibile rimuovere a causa di vincoli (ad esempio, a causa del numero minimo di giorni prima che è possibile annullare la registrazione di una parte).

Esporta parti registrate

Per esportare le parti registrate, utilizza il metodo projects.locations.instances.exportRegisteredParties.

Le informazioni seguenti sono disponibili anche in Creare e gestire istanze.

Prima di utilizzare qualsiasi dato della richiesta, effettua le seguenti sostituzioni:

• PROJECT_ID: il tuo ID progetto Google Cloud elencato nelle impostazioni IAM
• LOCATION: la località dell'istanza; utilizza una delle regioni supportate:
  • us-central1
  • us-east1
  • europe-west1
  • europe-west2
  • europe-west4
  • southamerica-east1
• INSTANCE_ID: l'identificatore definito dall'utente per l'istanza
• BQ_OUTPUT_DATASET_NAME: un set di dati BigQuery in cui esportare una tabella che descrive le parti registrate
• REGISTERED_PARTIES_TABLE: la tabella in cui scrivere le parti registrate
• WRITE_DISPOSITION: l'azione che si verifica se la tabella di destinazione esiste già; utilizza uno dei seguenti valori:
  • WRITE_EMPTY: esporta i dati solo se la tabella BigQuery è vuota.
  • WRITE_TRUNCATE: cancella tutti i dati esistenti nella tabella BigQuery prima di scrivere nella tabella.
• LINE_OF_BUSINESS: utilizza COMMERCIAL per i clienti di servizi bancari commerciali (entità legali e naturali) oppure utilizza RETAIL per i clienti di servizi bancari retail

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando di gcloud con il tuo account utente, eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:

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

Quindi esegui questo comando per inviare la richiesta 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 (Windows)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando di gcloud con il tuo account utente, eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:

@'
{
  "dataset": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.REGISTERED_PARTIES_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  },
  "lineOfBusiness": "LINE_OF_BUSINESS"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta 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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per informazioni su come ottenere il risultato dell'operazione a lunga esecuzione (LRO), consulta Gestire le operazioni a lunga esecuzione.

Questo metodo restituisce una tabella BigQuery con lo schema seguente:

Colonna	Tipo	Descrizione
party_id	STRINGA	Identificatore univoco della parte nei set di dati dell'istanza
party_size	STRINGA	Specifica il livello per i clienti commerciali (grandi o piccoli). Questo campo non si applica ai clienti retail. NULL per tutti i clienti retail SMALL per piccole attività commerciali con una media di transazioni mensili inferiore a 500 LARGE per grandi aziende commerciali con una media di transazioni mensili superiore o uguale a 500 Tutti i valori fanno distinzione tra maiuscole e minuscole.
earliest_remove_time	STRINGA	La prima data in cui è possibile rimuovere il gruppo