お客様を登録する

このページでは、予測結果を作成するために当事者の登録と登録解除を行う手順について説明します。

当事者の登録準備ができていることを確認する
当事者登録テーブルを準備する
projects.locations.instances.importRegisteredParties メソッドを使用して、当事者の登録または登録解除を行う
メソッドレスポンスを検証する
（省略可）登録済み当事者のテーブルをエクスポートする

準備

始める前に、AML AI インスタンスが必要です。

モデルでリスクスコアの予測を作成できるようにするには、まず当事者を登録する必要があります。次のものがすでにある場合は、当事者を登録することをおすすめします。

当事者を登録するタイミング

データセットのいずれかで当事者の予測を作成する前に、当事者を登録する必要があります。トレーニング、調整、バックテストには登録は必要ありません。

予測結果は、本番環境またはテスト / 並行フェーズのいずれかでマネーロンダリングの調査に使用されます。予測から得られた結果に基づいて、独自のガバナンスとモデル分析プロセスを構築することもできます。

当事者を登録すると、登録される当事者ごとに追加の月額費用が発生します（詳しくは、料金ページをご覧ください）。

当事者登録テーブルの準備方法

当事者の登録については、料金ページをご覧ください。

当事者を登録する事業部門用のテーブルを準備します。すでに当事者が登録されている場合は、この当事者登録テーブルに、予測結果に使用する当事者テーブルの当事者のサブセットが含まれている可能性があります。

リテール当事者のスキーマ

列	タイプ	説明
`party_id`	`STRING`	インスタンスのデータセットに含まれる当事者の一意の識別子
`party_size`	`STRING`	NULL、リテール当事者の登録の場合コンテンツは無視されます

コマーシャル当事者のスキーマ

列タイプ説明

party_id STRING インスタンスのデータセット内の当事者の一意の識別子

party_size

STRING

リクエストされた当事者のサイズ。階層は、過去 365 日間の当事者の月間トランザクションの平均数に基づいています。

SMALL（月平均トランザクション数が 500 件未満の小規模なコマーシャル当事者の場合）
LARGE（月間平均トランザクション数が 500 以上の大規模なコマーシャル当事者の場合）

値はすべて大文字と小文字が区別されます。

当事者を登録する方法

当事者は、AML AI インスタンスごとに個別に登録されます。次の点にご注意ください。

リテールとコマーシャルの当事者は、個別に登録する必要があります。個別の API 呼び出しと個別の当事者登録テーブルを使用します。当事者が両方のリストにある場合、別々の登録と見なされます。
予測には、使用するエンジンバージョンに関連付けられた事業部門にすべての当事者を登録する必要があります。同じ事業部門に登録されていない当事者が含まれているデータセットを使用している場合、予測結果を作成できません。
提供された当事者登録テーブルは、インスタンスに登録されている既存の当事者のリストに追加するか、インスタンスで指定された事業部門に登録済みのすべての当事者を置き換えるために使用されます。
事業者を登録すると、しばらくの間その登録を解除できません（料金ページをご覧ください）。このため、validateOnly フィールドを TRUE に設定できます。このフィールドを使用することで、登録済みの当事者を変更せずに、メソッドの正味の影響とレスポンスを確認できます。検証が完了したら、オペレーションを再実行し、validateOnly パラメータを FALSE に設定できます。
以前の validateOnly リクエストが成功した場合でも、登録リクエストのレスポンスを確認して、すべての当事者が正常に登録されていることを確認してください。
コマーシャル当事者の登録の場合、当事者登録テーブルの party_size フィールドの値が SMALL または LARGE 以外の場合は、エラー（Invalid party_size present in table）が発生します。登録済みの当事者は更新されません。
リテール当事者の登録の場合、party_size フィールドは無視され、提供された当事者登録テーブル内のすべての当事者が登録されます。

登録済みの当事者をインポートするには、projects.locations.instances.importRegisteredParties メソッドを使用します。

（次の情報は、インスタンスの作成と管理でも確認できます）。

このタスクに必要な権限

このタスクを実行するには、次の権限が必要です。

権限

financialservices.v1instances.importRegisteredParties

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
ロケーションを表示
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
- australia-southeast1
INSTANCE_ID: インスタンスのユーザー定義の識別子
BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME: 登録済み当事者を記述するテーブルを含む BigQuery データセット
PARTY_REGISTRATION_TABLE: 登録済み当事者を表示するテーブル
注: 登録済み当事者を表示するテーブルを複数指定できます。partyTables 配列の各テーブルには、"bq://{project}.{bqDatasetID}.{bqTableID}" の形式を使用します。
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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

@'
{
  "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 が完了すると、オペレーションによって追加、削除、更新された当事者の数がレスポンスに表示されます。

レスポンスのフィールド	タイプ	説明
`partiesAdded`	`integer`	このオペレーションによって追加された当事者の数
`partiesRemoved`	`integer`	このオペレーションによって削除された当事者の数
`partiesTotal`	`integer`	更新オペレーションが完了した後に、このインスタンスに登録されている当事者の合計数
`partiesUptiered`	`integer`	小規模から大規模にアップグレードされたコマーシャルパーティの総数
`partiesDowntiered`	`integer`	大規模から小規模にダウン階層されたコマーシャル当事者の合計数
`partiesFailedToDowntier`	`integer`	大規模から小規模にダウン階層できなかったコマーシャル当事者の合計数
`partiesFailedToRemove`	`integer`	このオペレーションで削除できなかった当事者の数

当事者の登録を解除する方法

同じ projects.locations.instances.importRegisteredParties メソッドを使用して、既存の当事者のリストを置き換えることで、AML AI インスタンスごとに当事者が登録解除されます。mode フィールドを REPLACE に設定します。この設定では、指定した当事者の登録テーブルの一部ではない、現時点で登録されている当事者（該当する事業部門のもの）の登録が解除されます。

登録解除のレスポンス

オペレーションが完了したら、API レスポンスを確認し、オペレーションによって、追加または削除された当事者の数と登録当事者の総数が意図した結果になっているかどうかを確認します。

また、API レスポンスは、制約のために削除できなかった当事者の数も返します（たとえば、最小日数が経過するまでお客様を登録解除できない場合など）。

登録済み当事者をエクスポートする

登録済み当事者をエクスポートするには、projects.locations.instances.exportRegisteredParties メソッドを使用します。

（次の情報は、インスタンスの作成と管理でも確認できます）。

このタスクに必要な権限

このタスクを実行するには、次の権限が必要です。

権限

financialservices.v1instances.exportRegisteredParties

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
ロケーションを表示
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
- australia-southeast1
INSTANCE_ID: インスタンスのユーザー定義の識別子
BQ_OUTPUT_DATASET_NAME: 登録済み当事者を記述するテーブルをエクスポートする 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

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

@'
{
  "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_id`	`STRING`	インスタンスのデータセット内の当事者の一意の識別子
`party_size`	`STRING`	コマーシャルのお客様の階層を指定します（大小）。このフィールドは、リテールのお客様には適用されません。 `NULL`（すべてのリテールのお客様） `SMALL`（月平均トランザクション数が 500 件未満の小規模なコマーシャル当事者の場合） `LARGE`（月間平均トランザクション数が 500 以上の大規模なコマーシャル当事者の場合）値はすべて大文字と小文字が区別されます。
`earliest_remove_time`	`STRING`	当事者を削除できる最も早い時刻
`party_with_prediction_intent`	`STRING`	登録後に当事者が予測されたかどうかを示すインジケーター
`registration_or_uptier_time`	`STRING`	当事者が登録または昇格した時刻