Questa pagina è stata tradotta dall'API Cloud Translation.

Esportare un file CSV

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

Per informazioni su come eseguire la migrazione di un intero database da un 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, ti consigliamo di ripristinare un cluster da un backup archiviato.

Puoi annullare l'esportazione dei dati dai cluster AlloyDB per PostgreSQL. Per ulteriori informazioni, consulta 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 di database standard, a meno che l'istanza non sia sottodimensionata.
SELECT_QUERY può contenere commenti o spazi iniziali e finali. I commenti vengono ignorati e gli spazi bianchi vengono eliminati prima di eseguire la query di esportazione.
I costi di trasferimento dati tra regioni si applicano quando il bucket di destinazione si trova in una regione diversa rispetto al cluster di origine. Per ulteriori informazioni, consulta Prezzi di AlloyDB per PostgreSQL.
È possibile eseguire più operazioni di esportazione in parallelo.
La compressione è attivata se il nome dell'oggetto termina con l'estensione .gz. L'oggetto viene poi esportato in formato .gz in Cloud Storage.
Per i valori carattere nelle opzioni CSV come field_delimiter, quote_character e escape_character sono consentiti solo caratteri ASCII in 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 IAM (Identity and Access Management):

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

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

Il ruolo IAM storage.objectAdmin
Un ruolo personalizzato, che include le seguenti autorizzazioni:
- storage.objects.create

Per assistenza sui ruoli IAM, consulta Identity and Access Management.

Esportazione di dati in un file CSV

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

Puoi utilizzare l'interfaccia a riga di comando gcloud o l'API REST per personalizzare il formato del file CSV.

gcloud

Crea un bucket Cloud Storage.
Concedi le autorizzazioni dell'account di servizio al bucket Cloud Storage per l'operazione di esportazione. Utilizza il formato dell'account di servizio per identificare l'account di servizio del progetto da cui stai eseguendo l'esportazione. Il formato dell'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 all'account di servizio. Per assistenza sull'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 all'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 tuo bucket Cloud Storage.

Esegui il comando di esportazione CSV: TODOgcloud 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 località dell'istanza di destinazione.
- --async (Facoltativo): torna immediatamente senza attendere il completamento dell'operazione in corso.
- --field-delimiter (facoltativo): specifica il carattere che separa le colonne in ogni riga del file. Il valore predefinito è una virgola. Il valore di questo argomento deve essere un carattere in codice ASCII esadecimale.
- --quote-character (facoltativo): specifica il carattere di virgolette da utilizzare quando un valore di dato è tra virgolette. Il valore predefinito è una virgoletta doppia. Il valore di questo argomento deve essere un carattere in codice ASCII esadecimale.
- --escape-character (facoltativo): specifica il carattere che deve comparire prima di un carattere di dati che deve essere sottoposto a evocazione. Il valore predefinito è uguale a --quote-character. Il valore di questo argomento deve essere un carattere in 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 impostato in precedenza, revocarlo 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 dell'account di servizio per identificare l'account di servizio del progetto da cui stai eseguendo l'esportazione.

Il formato dell'account di servizio è il seguente:
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
A questo servizio 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 all'account di servizio. Per assistenza sull'impostazione delle autorizzazioni IAM, consulta Utilizzare le autorizzazioni IAM.

Nota: se esiste 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 all'account di servizio l'autorizzazione meno privilegiatastorage.objectCreator, che non può sostituire gli oggetti esistenti.
Esporta il database.

Utilizza il seguente metodo e URL HTTP:
```
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export
```
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: l'ID progetto.
- REGION: la regione in cui è dipiegato il 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 località dell'istanza di destinazione.
- ESCAPE_CHARACTER (facoltativo): il carattere che deve comparire prima di un carattere di dati che deve essere eseguito l'escape. Il valore di questo argomento deve essere un carattere in codice ASCII esadecimale. Ad esempio, 22 rappresenta un apice.
- 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 in codice ASCII esadecimale. Ad esempio, 22 rappresenta un apice.
- FIELD_DELIMITER (facoltativo): il carattere che suddivide i valori delle colonne. Il valore di questo argomento deve essere un carattere in 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 delle seguenti opzioni:

curl (Linux, macOS o Cloud Shell)

Salva il corpo della richiesta in un file denominato request.json quindi esegui il comando seguente:

       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 esegui il seguente 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

Riceverai 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 impostate in precedenza, rimuovile ora.

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

Personalizzare il formato di un file di esportazione CSV

Puoi utilizzare l'interfaccia a riga di comando gcloud 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
Fuga	Il valore predefinito è uguale al valore `QUOTE`.	`--escape-character`	`escape_character`	Carattere visualizzato prima di un carattere di dati che deve essere sottoposto a sfuggita.
Preventivo	`"22"` Codice esadecimale ASCII per le virgolette doppie.	`--quote-character`	`quote_character`	Specifica il carattere di virgolette da utilizzare quando un valore di dato è tra virgolette.
Delimitatore di campo	`"2C"` Codice esadecimale ASCII per la virgola.	`--field-delimiter`	`field_delimiter`	Carattere che suddivide i valori della colonna.

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 dell'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 in formato CSV crea un output CSV standard. Se hai bisogno di più opzioni rispetto a quelle fornite da AlloyDB, puoi utilizzare la seguente dichiarazione 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.