インスタンスを作成、管理する

このページでは、AML AI インスタンスを作成および管理する方法について説明し、クイック リファレンス ガイドとして利用できます。

準備

インスタンスを作成する

一部の API メソッドは長時間実行オペレーション(LRO)を返します。 これらのメソッドは非同期です。このメソッドがレスポンスを返すときにオペレーションが完了していない場合があります。これらのメソッドの場合は、リクエストを送信して結果を確認します。

リクエストを送信する

インスタンスを作成するには、projects.locations.instances.create メソッドを使用します。

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

  • PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
  • LOCATION: キーリングのロケーションとインスタンス。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: インスタンスのユーザー定義の識別子
  • KMS_PROJECT_ID: キーリングを含むプロジェクトの Google Cloud プロジェクト ID
  • KEY_RING_ID: キーリングのユーザー定義の識別子
  • KEY_ID: キーのユーザー定義の識別子

JSON 本文のリクエスト:

{
  "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID"
}

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

次のような 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": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

結果を確認する

インスタンスが作成されたかどうかを確認するには、projects.locations.operations.get メソッドを使用します。レスポンスに "done": false が含まれている場合は、レスポンスに "done": true が含まれるまでコマンドを繰り返します。 このオペレーションには数分かかることがあります。

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

  • PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID
  • LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • OPERATION_ID: オペレーションの ID。

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

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "endTime": END_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.Instance",
    "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "createTime": CREATE_TIME,
    "updateTime": UPDATE_TIME,
    "state": "ACTIVE",
    "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID"
  }
}

インスタンスを取得する

インスタンスを取得するには、projects.locations.instances.get メソッドを使用します。

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

  • PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
  • LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: インスタンスのユーザー定義の識別子

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

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
  "createTime": CREATE_TIME,
  "updateTime": UPDATE_TIME,
  "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID",
  "state": "ACTIVE"
}

インスタンスの更新

インスタンスを更新するには、projects.locations.instances.patch メソッドを使用します。

インスタンス内のすべてのフィールドを更新できるわけではありません。次の例では、インスタンスに関連付けられている Key-Value ペアのユーザーラベルを更新します。

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

  • PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
  • LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: インスタンスのユーザー定義の識別子
  • KEY: インスタンスの整理に使用する Key-Value ペアのキー。詳細については、labels をご覧ください。
  • VALUE: インスタンスの整理に使用する Key-Value ペアの値。詳細については、labels をご覧ください。

JSON 本文のリクエスト:

{
  "labels": {
    "KEY": "VALUE"
  }
}

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

次のような 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": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

長時間実行オペレーション(LRO)の結果を取得する方法の詳細については、結果の確認をご覧ください。

インスタンスを一覧表示する

特定のインスタンスのインスタンスを一覧表示するには、projects.locations.instances.list メソッドを使用します。

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

  • PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
  • LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1

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

次のような JSON レスポンスが返されます。

{
  "instances": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID",
      "state": "ACTIVE"
    }
  ]
}

登録済み当事者をインポートする

登録済み当事者をインポートするには、まず、当事者を登録する事業部門の BigQuery テーブルを準備します。詳細については、顧客を登録するをご覧ください。 次のいずれかのスキーマを使用します。

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

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

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

    タイプ説明
    party_idSTRINGインスタンスのデータセットにある当事者の一意の識別子
    party_sizeSTRING リクエストされた当事者のサイズ。階層は、過去 365 日間の当事者の月間トランザクションの平均数に基づいています。
    • SMALL(月平均トランザクション数が 500 件未満の小規模なコマーシャル当事者の場合)
    • LARGE(月間平均トランザクション数が 500 以上の大規模なコマーシャル当事者の場合)

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

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

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

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

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

次のような 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 が完了すると、オペレーションの追加、削除、更新が行われた当事者の数がレスポンスで示されます。

レスポンスのフィールド種類説明
partiesAddedinteger このオペレーションによって追加された当事者の数
partiesRemovedinteger このオペレーションによって削除された当事者の数
partiesTotalinteger 更新オペレーションが完了した後に、このインスタンスに登録されている当事者の合計数
partiesFailedToRemoveinteger このオペレーションで削除できなかった当事者の数

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

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

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

  • PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
  • LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • europe-west1
    • europe-west2
    • europe-west4
    • 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"
}

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

次のような 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_idSTRINGインスタンスのデータセットにある当事者の一意の識別子
party_sizeSTRING コマーシャルのお客様の階層を指定します(大小)。このフィールドは、リテールのお客様には適用されません。
  • NULL(すべてのリテールのお客様)
  • SMALL(月平均トランザクション数が 500 件未満の小規模なコマーシャル当事者の場合)
  • LARGE(月間平均トランザクション数が 500 以上の大規模なコマーシャル当事者の場合)

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

earliest_remove_timeSTRING当事者を削除できる最も早い時刻

詳細については、顧客を登録するをご覧ください。

インスタンスを削除する

インスタンスを削除するには、projects.locations.instances.delete メソッドを使用します。

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

  • PROJECT_ID: IAM 設定に載っている Google Cloud プロジェクト ID。
  • LOCATION: インスタンスのロケーション。サポートされているリージョンのいずれかを使用します。
    • us-central1
    • us-east1
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: インスタンスのユーザー定義の識別子

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

次のような 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": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

長時間実行オペレーション(LRO)の結果を取得する方法の詳細については、結果の確認をご覧ください。