Questa pagina è stata tradotta dall'API Cloud Translation.

Esportare un file CSV

Questa pagina descrive come esportare i dati dai cluster AlloyDB per PostgreSQL in un bucket Cloud Storage in formato CSV, utilizzabile da altri strumenti e ambienti.

Per informazioni sulla migrazione di un intero database da un server di database supportato a una nuova istanza AlloyDB, consulta Eseguire la migrazione di un database ad AlloyDB utilizzando Database Migration Service. Se esegui l'esportazione perché vuoi creare una nuova istanza dal file esportato, valuta la possibilità di ripristinare un cluster da un backup archiviato.

Puoi annullare l'esportazione dei dati dai cluster AlloyDB per PostgreSQL. Per ulteriori informazioni, vedi Annullare l'esportazione dei dati.

Prima di iniziare

Prima di iniziare un'operazione di esportazione, tieni presente che le operazioni di esportazione utilizzano le risorse del database, ma non interferiscono con le operazioni standard del database, a meno che il provisioning dell'istanza non sia insufficiente.
SELECT_QUERY può contenere commenti o spazi vuoti iniziali e finali. I commenti vengono ignorati e gli spazi bianchi vengono eliminati prima di eseguire la query di esportazione.
I costi di trasferimento dei dati tra regioni si applicano quando il bucket di destinazione si trova in una regione diversa rispetto al cluster di origine. Per saperne di più, consulta la pagina Prezzi di AlloyDB per PostgreSQL.
È possibile eseguire più operazioni di esportazione in parallelo.
La compressione è abilitata se il nome dell'oggetto termina con l'estensione .gz. L'oggetto viene quindi esportato in formato .gz in Cloud Storage.
Per i valori dei caratteri nelle opzioni CSV come field_delimiter, quote_character e escape_character, sono consentiti solo caratteri ASCII nel codice esadecimale (con o senza il prefisso 0x).

Ruoli e autorizzazioni richiesti per l'esportazione da AlloyDB

Per esportare i dati da AlloyDB in Cloud Storage, l'utente che avvia l'esportazione deve disporre di uno dei seguenti ruoli Identity and Access Management (IAM):

Ruolo Cloud AlloyDB Admin (roles/alloydb.admin)
Un ruolo personalizzato, incluse le seguenti autorizzazioni:
- alloydb.clusters.get
- alloydb.clusters.export

Inoltre, il account di servizio per il cluster AlloyDB deve avere uno dei seguenti ruoli:

Ruolo IAM storage.objectAdmin
Un ruolo personalizzato, incluse le seguenti autorizzazioni:
- storage.objects.create

Per assistenza con i ruoli IAM, consulta Identity and Access Management.

Esportazione di dati in un file CSV

Durante l'esportazione di un file CSV, puoi specificare gli schemi da esportare. Tutti gli schemi a livello di database sono idonei per l'esportazione.

Puoi utilizzare gcloud CLI o l'API REST per personalizzare il formato del file CSV.

gcloud

Crea un bucket Cloud Storage.
Concedi al account di servizio le autorizzazioni per il bucket Cloud Storage per l'operazione di esportazione. Utilizza il formato del account di servizio per identificare ilaccount di serviziot per il progetto da cui stai esportando. Il formato del account di servizio è il seguente:
```
service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
Utilizza gcloud storage buckets add-iam-policy-binding per concedere il storage.objectAdmin ruolo IAM al account di servizio. Per assistenza con l'impostazione delle autorizzazioni IAM, consulta Utilizzare le autorizzazioni IAM.

Nota :se un oggetto esistente ha lo stesso nome di quello che viene esportato nel bucket Cloud Storage, la concessione del ruolo objectAdmin al account di servizio comporta la sostituzione dell'oggetto precedente. Per evitare questo problema, puoi concedere all'account di servizio l'autorizzazione meno privilegiata storage.objectCreator, che non può sostituire gli oggetti esistenti.
Esporta il database nel bucket Cloud Storage.

Esegui il comando di esportazione CSV: gcloud alloydb clusters export.

La tabella seguente elenca le opzioni per l'esportazione dei dati in formato CSV:
- --select-query (obbligatorio): la query di selezione utilizzata per estrarre i dati.
Nota: durante il transito, la query potrebbe essere elaborata in località intermedie diverse dalla posizione dell'istanza di destinazione.
- --async (facoltativo): restituisce immediatamente il risultato, senza attendere il completamento dell'operazione in corso.
- --field-delimiter (facoltativo): specifica il carattere che separa le colonne in ogni riga (linea) del file. Il valore predefinito è una virgola. Il valore di questo argomento deve essere un carattere nel codice ASCII esadecimale.
- --quote-character (facoltativo): specifica il carattere di citazione da utilizzare quando un valore di dati è citato. Il valore predefinito sono le virgolette doppie. Il valore di questo argomento deve essere un carattere nel codice ASCII esadecimale.
- --escape-character (facoltativo): specifica il carattere che deve precedere un carattere di dati che deve essere sottoposto a escape. Il valore predefinito è lo stesso di --quote-character. Il valore di questo argomento deve essere un carattere nel codice ASCII esadecimale.
Per utilizzare queste funzionalità, includi queste opzioni nel comando gcloud CLI.

In caso contrario, rimuovi questi parametri dal seguente 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 non devi conservare il ruolo IAM che hai impostato in precedenza, revocalo ora.

REST v1

Crea un bucket per l'esportazione:

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

Utilizza il formato del account di servizio per identificare il account di servizio del progetto da cui stai esportando.

Il formato del account di servizio è il seguente:
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
A questo account devono essere concesse le autorizzazioni per il bucket Cloud Storage per l'operazione di esportazione.
Utilizza gcloud storage buckets add-iam-policy-binding per concedere il storage.objectAdmin ruolo IAM al account di servizio. Per assistenza con l'impostazione delle autorizzazioni IAM, consulta Utilizzare le autorizzazioni IAM.

Nota :nel caso in cui esista già un oggetto con lo stesso nome di quello esportato nel bucket Cloud Storage, la concessione del ruolo objectAdmin all'account di servizio comporterà la sostituzione dell'oggetto precedente. Per evitare questo problema, puoi concedere l'autorizzazione meno privilegiata storage.objectCreator al account di servizio, che non può sostituire gli oggetti già esistenti.
Esporta il database.

Utilizza il seguente metodo HTTP e URL:
```
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export
```
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: l'ID progetto
- REGION: la regione in cui è stato eseguito il deployment del cluster AlloyDB.
- CLUSTER_ID: l'ID cluster.
- BUCKET_NAME: il nome del bucket Cloud Storage.
- PATH_TO_CSV_FILE: il percorso del file CSV.
- DATABASE_NAME: il nome di un database all'interno del cluster AlloyDB.
- SELECT_QUERY: la query SQL per l'esportazione.
  
  Nota: durante il transito, la query potrebbe essere elaborata in località intermedie diverse dalla posizione dell'istanza di destinazione.
- ESCAPE_CHARACTER (facoltativo): il carattere che deve precedere un carattere di dati che deve essere sottoposto a escape. Il valore di questo argomento deve essere un carattere nel codice ASCII esadecimale. Ad esempio, 22 rappresenta le virgolette doppie.
- QUOTE_CHARACTER (facoltativo): il carattere che racchiude i valori delle colonne con un tipo di dati stringa. Il valore di questo argomento deve essere un carattere nel codice ASCII esadecimale. Ad esempio, 22 rappresenta le virgolette doppie.
- FIELD_DELIMITER (facoltativo): il carattere che divide i valori delle colonne. Il valore di questo argomento deve essere un carattere nel codice ASCII esadecimale. Ad esempio, 2C rappresenta una virgola.
Corpo JSON della richiesta:
```
{
  "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"
  }
}
```
Per inviare la richiesta, utilizza una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Salva il corpo della richiesta in un file denominato request.json ed esegui questo 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)

Salva il corpo della richiesta in un file denominato request.json ed esegui questo 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

Ricevi una risposta JSON simile alla seguente:

Risposta

    {
     "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 non devi conservare le autorizzazioni IAM che hai impostato in precedenza, rimuovile ora.

Per l'elenco completo dei parametri per la richiesta, vedi clusters:export.

Personalizzare il formato di un file di esportazione CSV

Puoi utilizzare gcloud CLI o l'API REST per personalizzare il formato del file CSV. Quando esegui un'esportazione, puoi specificare le seguenti opzioni di formattazione:

Opzione CSV	Valore predefinito	Flag gcloud	Proprietà API REST	Descrizione
Escape	Il valore predefinito è uguale al valore `QUOTE`.	`--escape-character`	`escape_character`	Carattere che appare prima di un carattere di dati che deve essere inserito come sequenza di escape.
Preventivo	`"22"` Codice esadecimale ASCII per le virgolette doppie.	`--quote-character`	`quote_character`	Specifica il carattere di citazione da utilizzare quando un valore di dati è citato.
Delimitatore di campo	`"2C"` Codice esadecimale ASCII per la virgola.	`--field-delimiter`	`field_delimiter`	Carattere che divide i valori delle colonne.

Ad esempio, un comando gcloud CLI che utilizza tutti questi argomenti potrebbe essere simile al seguente:

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

Il corpo della richiesta API REST equivalente è simile al seguente:

{
 "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",
       }
   }
}

Per impostazione predefinita, l'esportazione CSV crea un output CSV standard. Se hai bisogno di più opzioni di quelle fornite da AlloyDB, puoi utilizzare la seguente istruzione in un client 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');

Passaggi successivi

Scopri come esportare un file di dump SQL.
Annullare un'operazione di esportazione.