고객 등록

이 페이지에서는 예측 결과를 만들기 위해 당사자를 등록 및 등록 취소하는 다음 절차를 안내합니다.

1. 당사자 등록 준비 확인
2. 당사자 등록 테이블 준비
3. projects.locations.instances.importRegisteredParties 메서드를 사용하여 당사자 등록 또는 등록 취소
4. 메서드 응답 검증
5. (선택사항) 등록된 당사자 테이블 내보내기

시작하기 전에

시작하기 전에 AML AI 인스턴스가 필요합니다.

모델이 위험 점수 예측을 만들 수 있게 하려면 먼저 당사자를 등록해야 합니다. 다음이 이미 있는 경우 당사자를 등록하는 것이 좋습니다.

• 하나 이상의 데이터 세트
• 튜닝, 학습, 백테스트가 완료된 모델

당사자를 등록해야 하는 경우

데이터 세트 중 하나에서 당사자에 대한 예측을 만들려면 먼저 당사자를 등록해야 합니다. 학습, 튜닝 또는 백테스트에는 등록이 필요하지 않습니다.

예측 결과는 프로덕션 또는 테스트/병렬 단계에서 고객의 자금세탁 여부를 조사하는 데 사용됩니다.

당사자를 등록하면 등록된 당사자당 매월 추가 비용이 발생합니다. 자세한 내용은 가격 책정 페이지를 참조하세요.

당사자 등록 테이블을 준비하는 방법

당사자 등록에 대해서는 가격 책정 페이지를 참조하세요.

당사자를 등록하려는 비즈니스 라인의 테이블을 준비합니다. 이 당사자 등록 테이블은 Party 테이블의 하위 집합일 수 있습니다.

소매업 당사자 스키마

열	유형	설명
party_id	STRING	인스턴스의 데이터 세트에 있는 당사자의 고유한 식별자
party_size	STRING	NULL, 소매업 당사자 등록 시 콘텐츠가 무시됨

상업 당사자 스키마

열	유형	설명
party_id	STRING	인스턴스의 데이터 세트에 있는 당사자의 고유한 식별자
party_size	STRING	요청한 당사자 크기. 등급은 이전 365일 동안 해당 당사자의 평균 월간 트랜잭션 수를 기준으로 합니다. 월간 평균 트랜잭션 수가 500회 미만인 소규모 상업 당사자의 경우 SMALL 월간 평균 트랜잭션 수가 500회 이상인 대규모 상업 당사자의 경우 LARGE 모든 값은 대소문자를 구분합니다.

당사자를 등록하는 방법

당사자는 각 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를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

@'
{
  "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	이 작업으로 삭제하지 못한 당사자 수

당사자 등록을 취소하는 방법

AML AI 인스턴스별로 당사자를 등록 취소하려면 동일한 projects.locations.instances.importRegisteredParties 메서드를 사용하면서 기존 당사자 목록을 대체합니다. mode 필드를 REPLACE로 설정합니다. 이 설정은 제공된 당사자 등록 테이블에 속하지 않는 현재 등록된 당사자(제공된 비즈니스 라인)를 모두 등록 취소합니다.

참고: 당사자를 등록 취소하려면 최소 일수가 경과되어야 합니다. 가격 책정 페이지를 참조하세요. API 응답은 성공적으로 등록 취소된 당사자를 표시합니다.

등록 취소 응답

작업이 완료되면 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

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

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

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

@'
{
  "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 월간 평균 트랜잭션 수가 500회 미만인 소규모 상업 당사자의 경우 SMALL 월간 평균 트랜잭션 수가 500회 이상인 대규모 상업 당사자의 경우 LARGE 모든 값은 대소문자를 구분합니다.
earliest_remove_time	STRING	당사자를 삭제할 수 있는 가장 이른 시간
party_with_prediction_intent	STRING	등록 이후 당사자가 예측되었는지 여부를 나타내는 표시기
registration_or_uptier_time	STRING	당사자가 등록되거나 확대된 시간