Esta página foi traduzida pela API Cloud Translation.

Exporte um ficheiro CSV

Esta página descreve como exportar dados de clusters do AlloyDB for PostgreSQL para um contentor do Cloud Storage no formato CSV, que é utilizável por outras ferramentas e ambientes.

Para informações sobre a migração de uma base de dados completa de um servidor de base de dados suportado para uma nova instância do AlloyDB, consulte o artigo Migre uma base de dados para o AlloyDB através do Database Migration Service. Se estiver a exportar porque quer criar uma nova instância a partir do ficheiro exportado, considere restaurar um cluster a partir de uma cópia de segurança armazenada.

Pode cancelar a exportação de dados de clusters do AlloyDB for PostgreSQL. Para mais informações, consulte Cancele a exportação de dados.

Antes de começar

Antes de iniciar uma operação de exportação, tenha em atenção que as operações de exportação usam recursos da base de dados, mas não interferem com as operações padrão da base de dados, a menos que a instância tenha um aprovisionamento insuficiente.
SELECT_QUERY pode conter comentários ou espaços em branco à esquerda e à direita. Os comentários são ignorados e os espaços em branco são compactados antes de executar a consulta de exportação.
Aplicam-se custos de transferência de dados entre regiões quando o contentor de destino está numa região diferente do cluster de origem. Para mais informações, consulte os preços do AlloyDB para PostgreSQL.
É possível executar várias operações de exportação em paralelo.
A compressão é ativada se o nome do objeto terminar com a extensão .gz. O objeto é, em seguida, exportado no formato .gz para o Cloud Storage.
Apenas são permitidos carateres ASCII no código hexadecimal (com ou sem o prefixo 0x) para valores de carateres em opções CSV, como field_delimiter, quote_character e escape_character.

Funções e autorizações necessárias para exportar a partir do AlloyDB

Para exportar dados do AlloyDB para o Cloud Storage, o utilizador que inicia a exportação tem de ter uma das seguintes funções de gestão de identidades e acessos (IAM):

A função Administrador do Cloud AlloyDB (roles/alloydb.admin)
Uma função personalizada, incluindo as seguintes autorizações:
- alloydb.clusters.get
- alloydb.clusters.export

Além disso, a conta de serviço do cluster do AlloyDB tem de ter uma das seguintes funções:

A função de IAM storage.objectAdmin
Uma função personalizada, incluindo as seguintes autorizações:
- storage.objects.create

Para obter ajuda com as funções de IAM, consulte o artigo Gestão de identidade e de acesso.

Exporte dados para um ficheiro CSV

Durante uma exportação CSV, pode especificar os esquemas a exportar. Todos os esquemas ao nível da base de dados são elegíveis para exportação.

Pode usar a CLI gcloud ou a API REST para personalizar o formato do ficheiro CSV.

gcloud

Crie um contentor do Cloud Storage.
Conceda autorizações da conta de serviço ao contentor do Cloud Storage para a operação de exportação. Use o formato de conta de serviço para identificar a conta de serviço do projeto a partir do qual está a exportar. 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 a storage.objectAdmin função do IAM à conta de serviço. Para obter ajuda na definição das autorizações de IAM, consulte o artigo Usar autorizações de IAM.

Nota: se um objeto existente tiver o mesmo nome que o objeto que está a ser exportado para o contentor do Cloud Storage, a atribuição da função objectAdmin à conta de serviço resulta na substituição do objeto mais antigo. Para evitar esta situação, pode conceder à conta de serviço a autorização menos privilegiada storage.objectCreator, que não pode substituir objetos existentes.
Exporte a base de dados para o seu contentor do Cloud Storage.

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

A tabela seguinte apresenta as opções de exportação de dados num formato CSV:
- --select-query (Obrigatório): a consulta de seleção usada para extrair os dados.
Nota: durante o trânsito, a consulta pode ser processada em localizações intermédias que não a localização da instância de destino.
- --async (Opcional): devolve imediatamente, sem esperar que a operação em curso seja concluída.
- --field-delimiter (Opcional): especifica o caráter que separa as colunas em cada linha do ficheiro. A predefinição é uma vírgula. O valor deste argumento tem de ser um carater no código ASCII hexadecimal.
- --quote-character (Opcional): especifica o caráter de aspas a usar quando um valor de dados está entre aspas. A predefinição é um sinal de aspas duplas. O valor deste argumento tem de ser um carater no código ASCII hexadecimal.
- --escape-character (Opcional): especifica o caráter que tem de aparecer antes de um caráter de dados que tem de ser escapado. A predefinição é igual a --quote-character. O valor deste argumento tem de ser um caráter no código ASCII hexadecimal.
Para usar estas funcionalidades, inclua estas opções no comando da CLI gcloud.

Caso contrário, remova estes parâmetros do seguinte 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 não precisar de manter a função do IAM que definiu anteriormente, revogue-a agora.

REST v1

Crie um contentor para a exportação:

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

Use o formato de conta de serviço para identificar a conta de serviço do projeto a partir do qual está a exportar.

O formato da conta de serviço é o seguinte:
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
É necessário conceder autorizações a este para o contentor do Cloud Storage para a operação de exportação.
Use gcloud storage buckets add-iam-policy-binding para conceder a storage.objectAdmin função do IAM à conta de serviço. Para obter ajuda na definição das autorizações de IAM, consulte o artigo Usar autorizações de IAM.

Nota: no caso de já existir um objeto com o mesmo nome que o objeto a ser exportado no contentor do Cloud Storage, a concessão da função objectAdmin à conta de serviço resulta na substituição do objeto mais antigo. Para evitar esta situação, pode conceder a autorização com menos privilégios storage.objectCreator à conta de serviço, que não pode substituir objetos já existentes.
Exporte a sua base de dados.

Use o seguinte método HTTP e URL:
```
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export
```
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
- PROJECT_ID: o ID do projeto.
- REGION: a região na qual o cluster do AlloyDB está implementado.
- CLUSTER_ID: o ID do cluster.
- BUCKET_NAME: o nome do contentor do Cloud Storage.
- PATH_TO_CSV_FILE: o caminho para o ficheiro CSV.
- DATABASE_NAME: o nome de uma base de dados no cluster do AlloyDB.
- SELECT_QUERY: a consulta SQL para a exportação.
  
  Nota: durante o trânsito, a consulta pode ser processada em localizações intermédias que não a localização da instância de destino.
- ESCAPE_CHARACTER (Opcional): o caráter que tem de aparecer antes de um caráter de dados que tem de ser ignorado. O valor deste argumento tem de ser um caráter no código ASCII hexadecimal. Por exemplo, 22 representa uma aspa dupla.
- QUOTE_CHARACTER (Opcional): o caráter que inclui valores de colunas com um tipo de dados de string. O valor deste argumento tem de ser um carater no código ASCII hexadecimal. Por exemplo, 22 representa uma marca de aspas duplas.
- FIELD_DELIMITER (Opcional): o caráter que divide os valores das colunas. O valor deste argumento tem de ser um caráter no código ASCII hexadecimal. Por exemplo, 2C representa uma vírgula.
Corpo JSON do pedido:
```
{
  "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 o seu pedido, use uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Guarde o corpo do pedido num ficheiro com o nome request.json e execute o seguinte comando:

       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)

Guarde o corpo do pedido num ficheiro com o nome request.json e execute o seguinte comando:

    $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

Recebe uma resposta JSON semelhante à seguinte:

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 não precisar de manter as autorizações de IAM que definiu anteriormente, remova-as agora.

Para ver a lista completa de parâmetros do pedido, consulte clusters:export.

Personalize o formato de um ficheiro de exportação CSV

Pode usar a CLI gcloud ou a API REST para personalizar o formato do ficheiro CSV. Quando faz uma exportação, pode especificar as seguintes opções de formatação:

Opção CSV	Valor predefinido	Sinalizador gcloud	Propriedade da API REST	Descrição
Escape	A predefinição é igual ao valor de `QUOTE`.	`--escape-character`	`escape_character`	Caráter que aparece antes de um caráter de dados que tem de ser escapado.
Estimativa do custo	`"22"` Código hexadecimal ASCII para aspas.	`--quote-character`	`quote_character`	Especifica o caráter de aspas a usar quando um valor de dados é citado.
Delimitador de campo	`"2C"` Código hexadecimal ASCII para vírgula.	`--field-delimiter`	`field_delimiter`	Caráter que divide os valores das colunas.

Por exemplo, um comando da CLI gcloud que use todos estes argumentos pode ser semelhante ao seguinte:

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 do pedido da API REST equivalente é semelhante ao seguinte:

{
 "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 predefinição, a exportação CSV cria um resultado CSV padrão. Se precisar de mais opções do que as fornecidas pelo AlloyDB, pode usar a seguinte declaração num 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');

O que se segue?

Saiba como exportar um ficheiro de captura SQL.
Cancele uma operação de exportação.