お客様を登録する

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

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

準備

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

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

1 つ以上のデータセット
調整、トレーニング、バックテストされたモデル

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

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

予測結果は、本番環境またはテスト / 並行フェーズのいずれかでマネーロンダリングの調査に使用されます。

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

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

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

当事者を登録する事業部門用のテーブルを準備します。この当事者登録テーブルは、Party テーブルのサブセットにできます。

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

列	型	説明
`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 メソッドを使用します。

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

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

PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: インスタンスのユーザー定義の識別子
BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME: 登録済み当事者を記述するテーブルを含む BigQuery データセット
REGISTERED_PARTIES_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.REGISTERED_PARTIES_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.REGISTERED_PARTIES_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.REGISTERED_PARTIES_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": CREATE_TIME,
    "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 メソッドを使用します。

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

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

PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: インスタンスのユーザー定義の識別子
BQ_OUTPUT_DATASET_NAME: 登録済み当事者を記述するテーブルをエクスポートする BigQuery データセット
REGISTERED_PARTIES_TABLE: 登録済み当事者を書き込むテーブル
WRITE_DISPOSITION: 宛先テーブルがすでに存在する場合に発生するアクション。次の値のいずれかを使用できます。
- WRITE_EMPTY: BigQuery テーブルが空の場合にのみデータをエクスポートします。
- WRITE_TRUNCATE: テーブルに書き込む前に、BigQuery テーブル内の既存のデータをすべて削除します。
LINE_OF_BUSINESS: コマーシャルバンキングのお客様（法人と自然人）には COMMERCIAL を使用し、リテールバンキングのお客様には RETAIL を使用します。

JSON 本文のリクエスト:

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

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

cat > request.json << 'EOF'
{
  "dataset": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.REGISTERED_PARTIES_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.REGISTERED_PARTIES_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": CREATE_TIME,
    "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`	当事者が登録またはアップティアされた時刻