Esta página descreve como importar dados de um arquivo CSV armazenado em um bucket do Cloud Storage para um cluster do AlloyDB para PostgreSQL.
É possível cancelar a importação de dados para clusters do AlloyDB. Para mais informações, consulte Cancelar uma operação de importação.
Antes de começar
Antes de iniciar uma operação de importação:
- Verifique se o banco de dados tem espaço livre adequado.
- As operações de importação usam recursos do banco de dados, mas não interferem nas operações normais do banco de dados, a menos que o cluster tenha um provisionamento insuficiente.
Permissões e papéis necessários para importar para clusters do AlloyDB
Para importar dados do Cloud Storage para o AlloyDB, o usuário que inicia a importação precisa ter um dos seguintes papéis:
- O papel de Administrador do AlloyDB
- Um papel personalizado,
incluindo as seguintes permissões:
alloydb.clusters.get
alloydb.clusters.import
Além disso, a conta de serviço do cluster do AlloyDB precisa ter um dos seguintes papéis:
- O papel
storage.objectViewer
do IAM - Um papel personalizado, incluindo as seguintes permissões:
storage.objects.get
Para receber ajuda com os papéis do IAM, consulte Gerenciamento de identidade e acesso.
Importar dados de um arquivo CSV para clusters do AlloyDB
- O banco de dados e a tabela em que você está importando precisam existir no seu cluster do AlloyDB. Para receber ajuda sobre a criação de um banco de dados, consulte Criar um banco de dados.
- Os arquivos CSV precisam ter uma linha para cada linha de dados e usar campos separados por vírgula.
Para importar dados para um cluster do AlloyDB usando um arquivo CSV, siga estas etapas:
- Crie um bucket do Cloud Storage.
- Faça upload do arquivo CSV para o bucket. Para receber ajuda com o upload de arquivos para buckets, consulte Como fazer upload de objetos.
Use gcloud storage buckets add-iam-policy-binding para conceder o
storage.objectViewer
papel do IAM à conta de serviço do AlloyDB para o bucket.service-
PROJECT_NUMBER @gcp-sa-alloydb.iam.gserviceaccount.comPara receber ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do IAM.
Importe o arquivo:
gcloud alloydb clusters import
CLUSTER_NAME --region=REGION --gcs-uri=gs://BUCKET_NAME /FILE_NAME --database=DATABASE_NAME --user=USER --csv --table=TABLE_NAME Faça as seguintes substituições:
- CLUSTER_NAME: o nome do cluster.
- REGION: a região em que o cluster do AlloyDB é implantado.
- BUCKET_NAME: o nome do bucket do Cloud Storage.
- FILE_NAME: o nome do arquivo CSV.
- DATABASE_NAME: o nome de um banco de dados dentro do cluster.
- USER: o usuário da operação de importação.
- TABLE_NAME: a tabela no banco de dados.
Para mais informações sobre como usar o comando
import
, consulte a página de referência do comandoalloydb import
.Se você não precisar manter as permissões do IAM definidas anteriormente, remova-as usando
gcloud storage buckets remove-iam-policy-binding
.
- Crie um bucket do Cloud Storage.
- Faça upload do arquivo CSV para o bucket. Para receber ajuda com o upload de arquivos para buckets, consulte Como fazer upload de objetos.
Conceda permissões da conta de serviço ao bucket do Cloud Storage para a operação de importação. Use o formato da conta de serviço para identificar a conta de serviço do projeto para o qual você está importando. O formato da conta de serviço é o seguinte:
service-
PROJECT_NUMBER @gcp-sa-alloydb.iam.gserviceaccount.comUse gcloud storage buckets add-iam-policy-binding para conceder o papel do IAM
storage.objectViewer
à conta de serviço do cluster AlloyDB para o bucket. Para ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do IAM.Importe o arquivo.
Use o método HTTP e o URL a seguir:
POST https://alloydb.googleapis.com/v1/projects/
PROJECT_ID /locations/REGION /clusters/CLUSTER_ID :importAntes de usar os dados da solicitação, faça as seguintes substituições:
- PROJECT_ID: o ID do projeto;
- LOCATION_ID: a região em que o cluster do AlloyDB é implantado.
- CLUSTER_ID: o ID do cluster.
- BUCKET_NAME: o nome do bucket do Cloud Storage.
- PATH_TO_CSV_FILE: o caminho para o arquivo CSV.
- USER: o usuário da operação de importação.
- DATABASE_NAME: o nome de um banco de dados dentro do cluster do AlloyDB.
- TABLE_NAME: a tabela no banco de dados.
- COLUMNS (opcional): as colunas a serem importadas.
- ESCAPE_CHARACTER (opcional): o caractere que precisa
aparecer antes de um caractere de dados que precisa de escape. O valor
desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo,
22
representa aspas duplas. - QUOTE_CHARACTER (opcional): o caractere
que inclui valores de colunas com um tipo de dados de string.
O valor desse argumento precisa ser um caractere no código ASCII hexadecimal.
Por exemplo,
22
representa aspas duplas. - FIELD_DELIMITER (opcional): o caractere
que divide os valores da coluna. O valor desse argumento precisa ser um
caractere no código ASCII hexadecimal. Por exemplo,
2C
representa uma vírgula.
Solicitar corpo 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 " } }Para enviar a solicitação, expanda uma destas opções:
curl (Linux, macOS ou Cloud Shell)
Salve o corpo da solicitação em um arquivo chamado
request.json
e execute o comando a seguir: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)
Salve o corpo da solicitação em um arquivo chamado
request.json
e execute o comando a seguir:$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 ContentVocê recebe uma resposta JSON semelhante a esta:
Resposta
{ "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 }
Se você não precisar manter as permissões do IAM definidas anteriormente, remova-as agora.
Para conferir a lista completa de parâmetros da solicitação, consulte
clusters:import
.
Personalizar o formato CSV e importar o arquivo
É possível personalizar o formato CSV e importar o arquivo quando ele contém delimitador de campo não padrão ou caracteres de aspas ou de escape. Para importar um arquivo CSV com um formato diferente do padrão, forneça as mesmas opções de formatação na solicitação.
Use os exemplos de CLI gcloud e API REST abaixo para personalizar o formato do arquivo CSV.
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
O corpo da solicitação da API REST equivalente é semelhante a este:
{
"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",
}
}
Para ver como a solicitação da API REST de base é criada nesta tarefa, consulte o APIs Explorer na página clusters:import
.
Se você receber um erro como INVALID_ARGUMENT
, verifique se a tabela existe. Se
a tabela existir, confirme se você tem as permissões corretas no bucket.
Para receber ajuda para configurar o controle de acesso no Cloud Storage, consulte
Criar e gerenciar listas de controle de acesso.
Verificar o status de uma operação de importação
Para verificar o status de uma operação de importação, siga estas etapas:
Execute o seguinte usando o comando gcloud alloydb operations describe:
gcloud alloydb operations describe OPERATION_ID --region=REGION
O status dessas operações está no campo STATUS
.
Você também pode listar detalhes de uma operação específica ou cancelá-la. Para mais informações sobre esse comando, consulte a
página de referência do comando
gcloud alloydb operations
.
Use o método GET
e o seguinte URL:
GET https://alloydb.googleapis.com/v1/projects/PROJECT_ID /locations/REGION /operations/OPERATION_ID
Para ver mais informações, consulte get
.
Antes de usar os dados da solicitação, faça as seguintes substituições:
- REGION: a região em que o cluster do AlloyDB é implantado.
- PROJECT_ID: o ID do projeto;
- OPERATION_ID: o ID da operação de importação. Para mais informações, consulte Antes de começar.
Para enviar a solicitação, expanda uma destas opções:
curl (Linux, macOS ou Cloud Shell)
Execute o seguinte comando:
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)
Execute o seguinte comando:
$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
Você recebe uma resposta JSON semelhante a esta:
Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de Operation.
A seguir
- Saiba como importar um arquivo SQL.
- Saiba como cancelar uma operação de importação.
- Verificar o status de uma operação de importação.