Esta página foi traduzida pela API Cloud Translation.

Exportar um arquivo CSV

Esta página descreve como exportar dados de clusters do AlloyDB para PostgreSQL para um bucket do Cloud Storage no formato CSV, que pode ser usado por outras ferramentas e ambientes.

Para informações sobre como migrar um banco de dados inteiro de um servidor de banco de dados com suporte para uma nova instância do AlloyDB, consulte Migrar um banco de dados para o AlloyDB usando o Database Migration Service. Se você estiver exportando porque quer criar uma nova instância a partir do arquivo exportado, considere restaurar um cluster de um backup armazenado.

É possível cancelar a exportação de dados dos clusters do AlloyDB para PostgreSQL. Para mais informações, consulte Cancelar a exportação de dados.

Antes de começar

Antes de iniciar uma operação de exportação, lembre-se de que as operações de exportação usam recursos do banco de dados, mas não interferem nas operações padrão do banco de dados, a menos que a instância tenha um provisionamento menor do que deveria ser.
SELECT_QUERY pode conter comentários ou espaços em branco no início e no final. Os comentários são ignorados e os espaços em branco são removidos antes da execução da consulta de exportação.
As cobranças por transferência de dados entre regiões são aplicadas quando o bucket de destino está em uma região diferente do cluster de origem. Para mais informações, consulte Preços do AlloyDB para PostgreSQL.
Várias operações de exportação podem ser executadas em paralelo.
A compactação será ativada se o nome do objeto terminar com a extensão .gz. O objeto é exportado no formato .gz para o Cloud Storage.
Somente caracteres ASCII em código hexadecimal (com ou sem o prefixo 0x) são permitidos para valores de caracteres em opções CSV, como field_delimiter, quote_character e escape_character.

Permissões e papéis necessários para exportar do AlloyDB

Para exportar dados do AlloyDB para o Cloud Storage, o usuário que inicia a exportação precisa ter um dos seguintes papéis do Identity and Access Management (IAM):

O papel de Administrador do Cloud AlloyDB (roles/alloydb.admin)
Um papel personalizado, incluindo as seguintes permissões:
- alloydb.clusters.get
- alloydb.clusters.export

Além disso, a conta de serviço do cluster do AlloyDB precisa ter um dos seguintes papéis:

O papel storage.objectAdmin do IAM
Um papel personalizado, incluindo as seguintes permissões:
- storage.objects.create

Para receber ajuda com os papéis do IAM, consulte Identity and Access Management.

Exportar dados para um arquivo CSV

Durante uma exportação de CSV, é possível especificar os esquemas que serão exportados. Todos os esquemas no nível do banco de dados estão qualificados para exportação.

É possível usar a CLI gcloud ou a API REST para personalizar o formato do arquivo CSV.

gcloud

Crie um bucket do Cloud Storage.
Conceda permissões à conta de serviço para o bucket do Cloud Storage para a operação de exportação. Use o formato da conta de serviço para identificar a conta de serviço do projeto que você está exportando. O formato da conta de serviço é o seguinte:
```
service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
Use gcloud storage buckets add-iam-policy-binding para conceder o papel do IAM storage.objectAdmin à conta de serviço. Para receber ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do IAM.

Observação: se um objeto atual tiver o mesmo nome do que está sendo exportado para o bucket do Cloud Storage, a concessão do papel objectAdmin à conta de serviço vai resultar na substituição do objeto mais antigo. Para evitar isso, conceda à conta de serviço a permissão storage.objectCreator, que tem menos privilégios e não pode substituir objetos existentes.
Exporte o banco de dados para seu bucket do Cloud Storage.

Execute o comando de exportação CSV: TODOgcloud alloydb clusters export.

A tabela a seguir lista as opções para exportar dados em formato CSV:
- --select-query (obrigatório): a consulta de seleção usada para extrair os dados.
Observação: durante o trânsito, a consulta pode ser processada em locais intermediários diferentes do local da instância de destino.
- --async (opcional): retorna imediatamente, sem aguardar a conclusão da operação em andamento.
- --field-delimiter (opcional): especifica o caractere que separa as colunas em cada linha do arquivo. O padrão é uma vírgula. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal.
- --quote-character (opcional): especifica o caractere de aspas a ser usado quando um valor de dados é citado. O padrão é uma aspa dupla. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal.
- --escape-character (opcional): especifica o caractere que precisa aparecer antes de um caractere de dados que precisa de escape. O padrão é igual a --quote-character. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal.
Para usar esses recursos, inclua essas opções no comando da CLI gcloud.

Caso contrário, remova esses parâmetros do comando:
```
gcloud alloydb clusters export CLUSTER_NAME
  --region=REGION
  --database=DATABASE_NAME
  --gcs-uri="gs://BUCKET_NAME/OBJECT_NAME"
  --select-query=SELECT_QUERY
  --field-delimiter=FIELD_DELIMITER
  --quote-character=QUOTE_CHARACTER
  --escape-character=ESCAPE_CHARACTER
  --csv
```
Se você não precisar manter o papel do IAM definido anteriormente, revogue-o agora.

REST v1

Crie um bucket para a exportação:

gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME>

Use o formato da conta de serviço para identificar a conta de serviço do projeto que você está exportando.

O formato da conta de serviço é o seguinte:
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
É necessário conceder permissões ao bucket do Cloud Storage para a operação de exportação.
Use gcloud storage buckets add-iam-policy-binding para conceder o storage.objectAdmin papel do IAM à conta de serviço. Para receber ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do IAM.

Observação: se já houver um objeto com o mesmo nome que o que está sendo exportado no bucket do Cloud Storage, a concessão do papel objectAdmin à conta de serviço vai resultar na substituição do objeto mais antigo. Para evitar isso, conceda a permissão menos privilegiada storage.objectCreator à conta de serviço, que não pode substituir objetos já existentes.
Exporte seu banco de dados.

Use o método HTTP e o URL a seguir:
```
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export
```
Antes de usar os dados da solicitação, faça as seguintes substituições:
- PROJECT_ID: o ID do projeto;
- REGION: 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.
- DATABASE_NAME: o nome de um banco de dados dentro do cluster do AlloyDB.
- SELECT_QUERY: a consulta SQL para a exportação.
  
  Observação: durante o trânsito, a consulta pode ser processada em locais intermediários diferentes do local da instância de destino.
- 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:
```
{
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
  },
  "database": "DATABASE_NAME",
  "csv_export_options": {
    "select_query": "SELECT_QUERY",
    "escape_character": "ESCAPE_CHARACTER",
    "quote_character": "QUOTE_CHARACTER",
    "field_delimiter": "FIELD_DELIMITER"
  }
}
```
Para enviar a solicitação, use 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/REGION/clusters/CLUSTER_ID:export"

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/REGION/clusters/CLUSTER_ID:export"| Select-Object -Expand Content

Você recebe uma resposta JSON semelhante a esta:

Resposta

    {
     "name": "projects/PROJECT_ID/locations/REGION/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/REGION/clusters/TARGET_CLUSTER",
      "verb": "export",
      "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:export.

Personalizar o formato de um arquivo de exportação CSV

É possível usar a CLI gcloud ou a API REST para personalizar o formato do arquivo CSV. Ao realizar uma exportação, você pode especificar as seguintes opções de formatação:

Opção CSV	Valor padrão	gcloud flag	Propriedade da API REST	Descrição
Escape	O padrão é igual ao valor `QUOTE`.	`--escape-character`	`escape_character`	Caractere que aparece antes de um caractere de dados que precisa ser escapado.
Cotação	`"22"` Código hexadecimal ASCII para aspas duplas.	`--quote-character`	`quote_character`	Especifica o caractere de aspas a ser usado quando um valor de dados é citado.
Delimitador de campo	`"2C"` Código hexadecimal ASCII para vírgula.	`--field-delimiter`	`field_delimiter`	Caractere que divide os valores da coluna.

Por exemplo, um comando da CLI gcloud que usa todos esses argumentos pode ser parecido com este:

gcloud alloydb clusters export CLUSTER_NAME \
--region=REGION \
--database=DATABASE_NAME \
--gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' \
--select-query=SELECT_QUERY \
--field-delimiter='2C' \
--quote-character='22' \
--escape-character='5C'
--csv

O corpo da solicitação da API REST equivalente é semelhante a este:

{
 "exportContext":
   {
      "gcs_destination": {
        "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE",
      },
      "database": "DATABASE_NAME",
      "csv_export_options":
       {
           "select_query": "SELECT_QUERY",
           "escape_character": "5C",
           "quote_character": "22",
           "field_delimiter": "2C",
       }
   }
}

Por padrão, a exportação de CSV cria uma saída CSV padrão. Se você precisar de mais opções do que as fornecidas pelo AlloyDB, use a seguinte instrução em um cliente psql:

     \copy `TABLE_NAME` TO `CSV_FILE_NAME.csv' WITH
          (FORMAT csv, ESCAPE 'ESCAPE_CHARACTER', QUOTE 'QUOTE_CHARACTER',
          DELIMITER 'DELIMITER_CHARACTER', ENCODING 'UTF8', NULL 'NULL_MARKER_STRING');

A seguir

Saiba como exportar um arquivo dump SQL.
Cancelar uma operação de exportação.