导入 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 文件中，必须每行数据占用一行，而且必须使用英文逗号分隔字段。

如需使用 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 方法和网址：

    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（可选）：需转义的数据字符之前必须显示的字符。此参数的值必须是十六进制 ASCII 代码中的字符。例如，22 表示双引号。
    • QUOTE_CHARACTER（可选）：此标志表示包含字符串数据类型列中的值的字符。此参数的值必须是十六进制 ASCII 代码中的字符。例如，22 表示英文双引号。
    • FIELD_DELIMITER（可选）：用于拆分列值的字符。此参数的值必须是十六进制 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 方法和以下网址：

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 实例。

后续步骤