CSV ファイルをインポートする

このページでは、Cloud Storage バケットに保存されている CSV ファイルから AlloyDB for PostgreSQL クラスタにデータをインポートする方法について説明します。

AlloyDB クラスタへのデータのインポートをキャンセルできます。詳細については、インポート オペレーションをキャンセルするをご覧ください。

始める前に

インポート オペレーションを開始する前に、次のことを行います。

  • データベースに十分な空き容量があることを確認します。
  • インポート オペレーションではデータベース リソースが使用されますが、クラスタがプロビジョニングされていない限り、インポートによって通常のデータベース オペレーションが妨げられることはありません。

AlloyDB クラスタへのインポートに必要なロールと権限

Cloud Storage から AlloyDB にデータをインポートするには、インポートを開始するユーザーに次のいずれかのロールが必要です。

また、AlloyDB クラスタのサービス アカウントには、次のいずれかのロールが必要です。

  • storage.objectViewer IAM ロール
  • 次の権限を含むカスタムロール:
    • storage.objects.get

IAM ロールについては、Identity and Access Management をご覧ください。

CSV ファイルから AlloyDB クラスタにデータをインポートする

  • インポート先のデータベースとテーブルが AlloyDB クラスタ上に存在している必要があります。データベースの作成方法については、データベースを作成するをご覧ください。
  • CSV ファイルは、データの行ごとに 1 行を使用し、カンマ区切りのフィールドが含まれている必要があります。

CSV ファイルを使用して AlloyDB クラスタにデータをインポートする手順は次のとおりです。

gcloud

  1. Cloud Storage バケットを作成する。
  2. CSV ファイルをバケットにアップロードします。ファイルをバケットにアップロードする方法については、オブジェクトのアップロードをご覧ください。

  3. gcloud storage buckets add-iam-policy-binding を使用して、バケットの AlloyDB サービス アカウントに storage.objectViewer IAM ロールを付与します。

     service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com

    IAM 権限の設定については、IAM 権限の使用をご覧ください。

  4. ファイルをインポートします。

    gcloud alloydb clusters import CLUSTER_NAME --region=REGION --gcs-uri=gs://BUCKET_NAME/FILE_NAME --database=DATABASE_NAME --user=USER --csv --table=TABLE_NAME

    次のように置き換えます。

    • CLUSTER_NAME: クラスタの名前。
    • REGION: AlloyDB クラスタがデプロイされているリージョン。
    • BUCKET_NAME: Cloud Storage バケット名。
    • FILE_NAME: CSV ファイルの名前。
    • DATABASE_NAME: クラスタ内のデータベースの名前。
    • USER: インポート オペレーションのユーザー。
    • TABLE_NAME: データベース内のテーブル。

    import コマンドの使用方法については、alloydb import コマンドのリファレンス ページをご覧ください。

  5. 以前に設定した IAM 権限を保持する必要がない場合は、gcloud storage buckets remove-iam-policy-binding を使用して削除します。

REST v1

  1. Cloud Storage バケットを作成する。
  2. CSV ファイルをバケットにアップロードします。ファイルをバケットにアップロードする方法については、オブジェクトのアップロードをご覧ください。

  3. インポート オペレーション用の Cloud Storage バケットに対する権限をサービス アカウントに付与します。サービス アカウントの形式を使用して、インポート先のプロジェクトのサービス アカウントを特定します。サービス アカウントの形式は次のとおりです。

    service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com

  4. gcloud storage buckets add-iam-policy-binding を使用して、バケットの AlloyDB クラスタのサービス アカウントに storage.objectViewer IAM ロールを付与します。IAM 権限の設定については、IAM 権限の使用をご覧ください。

  5. ファイルをインポートします。

    次の HTTP メソッドと URL を使用します。

    POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:import

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

    • PROJECT_ID: プロジェクト ID。
    • LOCATION_ID: AlloyDB クラスタがデプロイされているリージョン。
    • CLUSTER_ID: クラスタ ID。
    • BUCKET_NAME: Cloud Storage バケット名。
    • PATH_TO_CSV_FILE: CSV ファイルのパス。
    • USER: インポート オペレーションのユーザー。
    • DATABASE_NAME: AlloyDB クラスタ内のデータベースの名前。
    • TABLE_NAME: データベース内のテーブル。
    • COLUMNS（省略可）: インポートする列。
    • ESCAPE_CHARACTER（省略可）: エスケープが必要なデータ文字の前に表示する文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、22 は二重引用符を表します。
    • QUOTE_CHARACTER（省略可）: 文字列データ型を持つ列の値を囲む文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、22 は二重引用符を表します。
    • FIELD_DELIMITER（省略可）: 列の値を分割する文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、2C はカンマを表します。

    JSON 本文のリクエスト:

    {
  "gcsUri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE",
  "database": "DATABASE_NAME",
  "user": "USER",
  "csvImportOptions": {
    "table": "TABLE_NAME",
    "columns": ["COLUMN1", "COLUMN2"],
    "fieldDelimiter": "FIELD_DELIMITER",
    "quoteCharacter": "QUOTE_CHARACTER",
    "escapeCharacter": "ESCAPE_CHARACTER"
  }
}

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

    curl（Linux、macOS、Cloud Shell）

    リクエスト本文を request.json という名前のファイルに保存し、次のコマンドを実行します。

       curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID:import"

    PowerShell（Windows）

    リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

    $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://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID:import"| Select-Object -Expand Content

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

    レスポンス

    {
 "name": "projects/PROJECT_ID/locations/LOCATION_ID/operations/OPERATION_ID",
 "metadata": {
  "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
  "createTime": "2024-09-17T06:05:31.244428646Z",
  "target": "projects/project-id/locations/location-id/clusters/target-cluster",
  "verb": "import",
  "requestedCancellation": false,
  "apiVersion": "v1"
 },
 "done": false
}

  6. 以前に設定した IAM 権限を保持する必要がない場合は、今すぐ削除してください。

    リクエストのパラメータの一覧については、clusters:import をご覧ください。

CSV 形式をカスタマイズしてファイルをインポートする

CSV ファイルにデフォルト以外のフィールド区切り文字、引用符、エスケープ文字が含まれている場合は、CSV 形式をカスタマイズしてファイルをインポートできます。デフォルト以外の形式の CSV ファイルをインポートするには、リクエストで同じ形式オプションを指定する必要があります。

次の gcloud CLI と REST API の例を使用して、CSV ファイル形式をカスタマイズします。

gcloud

gcloud alloydb clusters import CLUSTER_NAME --region=REGION --database=DATABASE_NAME --gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' --user=USERNAME --table=TABLE_NAME --columns=COLUMNS --field-delimiter='2C' --quote-character='22' --escape-character='5C' --csv

REST v1

同等の REST API リクエストの本文は次のようになります。

{
 "gcsUri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE",
 "database": "DATABASE_NAME",
 "user": "USER",
 "csvImportOptions": {
     "table": "TABLE_NAME",
     "columns": ["COLUMN1", "COLUMN2"],
     "escapeCharacter": "5C",
     "quoteCharacter": "22",
     "fieldDelimiter": "2C",
 }
}

このタスクで基盤となる REST API リクエストがどのように作成されるかについては、clusters:import ページの API Explorer をご覧ください。

INVALID_ARGUMENT などのエラーが発生した場合は、テーブルが存在することを確認してください。テーブルが存在する場合は、バケットに対して適切な権限があることを確認します。Cloud Storage のアクセス制御の構成について詳しくは、アクセス制御リストの作成と管理をご覧ください。

インポート オペレーションのステータスを確認する

インポート オペレーションのステータスを確認する手順は次のとおりです。

gcloud

gcloud alloydb operations describe コマンドを使用して、次のコマンドを実行します。

gcloud alloydb operations describe OPERATION_ID --region=REGION

これらのオペレーションのステータスは STATUS フィールドに格納されます。

特定のオペレーションの詳細を一覧表示したり、特定のオペレーションをキャンセルしたりすることもできます。このコマンドの詳細については、gcloud alloydb operations コマンドのリファレンス ページをご覧ください。

REST v1

GET メソッドと次の URL を使用します。

GET https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID

詳細については、get をご覧ください。

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

  • REGION: AlloyDB クラスタがデプロイされているリージョン。
  • PROJECT_ID: プロジェクト ID。
  • OPERATION_ID: インポート オペレーションの ID。詳細については、始める前にをご覧ください。

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

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

  curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID | Select-Object -Expand Content

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

成功した場合、レスポンスの本文には Operation のインスタンスが含まれます。

次のステップ