CSV-Datei importieren

Wenn Sie tabellarische Daten in eine vorhandene Datenbanktabelle laden möchten, können Sie eine in einem Cloud Storage-Bucket gespeicherte CSV-Datei in einen AlloyDB for PostgreSQL-Cluster importieren.

Hinweis: Wenn Sie eine gesamte Datenbank von einem unterstützten Datenbankserver (lokal, in AWS oder in AlloyDB) zu einem neuen AlloyDB-Cluster migrieren, können Sie den Database Migration Service verwenden, anstatt Dateien zu exportieren und zu importieren. Wenn Sie aus der exportierten Datei einen neuen Cluster erstellen möchten, können Sie stattdessen auch eine Wiederherstellung aus einer gespeicherten Sicherung durchführen.

Sie können den Datenimport in AlloyDB-Cluster abbrechen. Weitere Informationen finden Sie unter Importvorgang abbrechen.

Hinweis

Für einen Importvorgang ist Folgendes zu beachten:

• Sorgen Sie dafür, dass in Ihrer Datenbank ausreichend freier Speicherplatz vorhanden ist.
• Importvorgänge verwenden Datenbankressourcen, stören den normalen Datenbankbetrieb jedoch nicht, wenn der Cluster nicht unterdimensioniert ist.

Wichtig: Achten Sie vor dem Starten eines großen Importvorgangs darauf, dass mindestens 25 % des Laufwerks auf dem Cluster verfügbar sind. So lassen sich Probleme mit aggressiver automatischer Vergrößerung verhindern, die die Verfügbarkeit des Clusters beeinträchtigen können. Prüfen Sie, ob die CSV-Datei die erwarteten Daten enthält und ob es sich um eine gültige CSV-Datei handelt.

Erforderliche Rollen und Berechtigungen für den Import in AlloyDB-Cluster

Wenn Sie Daten aus Cloud Storage in AlloyDB importieren möchten, muss der Nutzer, der den Import initiiert, eine der folgenden Rollen haben:

• Die Rolle AlloyDB Admin
• Eine benutzerdefinierte Rolle mit folgenden Berechtigungen:
  • alloydb.clusters.get
  • alloydb.clusters.import

Darüber hinaus muss das Dienstkonto für den AlloyDB-Cluster eine der folgenden Rollen haben:

• storage.objectViewer IAM-Rolle.
• Eine benutzerdefinierte Rolle mit folgenden Berechtigungen:
  • storage.objects.get

Informationen zu IAM-Rollen finden Sie unter Identity and Access Management.

Hinweis: Es kann einige Minuten dauern, bis die Änderungen in den IAM-Berechtigungen und -Rollen wirksam werden. Weitere Informationen finden Sie unter Zugriffsänderungsverteilung.

Daten aus einer CSV-Datei in AlloyDB-Cluster importieren

• Die Datenbank und die Tabelle, in die importiert werden sollen, müssen in der AlloyDB-Cluster vorhanden sein. Informationen zum Erstellen einer Datenbank finden Sie unter Datenbank erstellen.
• Die CSV-Dateien müssen eine Zeile pro Datensatz und kommagetrennte Felder haben.
• CSV-Dateien dürfen keine Kopfzeile enthalten. Wenn Ihre CSV-Datei eine Kopfzeile hat, entfernen Sie sie vor dem Import.

Hinweis: Das Standardverhalten für AlloyDB ist das Importieren von Spalten in Ihrer CSV-Datei in der gleichen Reihenfolge wie das Tabellenschema. Wenn sich die Reihenfolge in der CSV-Datei unterscheidet oder einige Spalten übersprungen werden, verwenden Sie die CSV-Importoptionen, um Daten aus der CSV-Datei in die erforderlichen Spalten zu importieren.

So importieren Sie Daten aus einer CSV-Datei in einen AlloyDB-Cluster:

Console

1. Rufen Sie in der Google Cloud Console die Seite Cluster auf.

   Zu den Clustern

2. Klicken Sie auf einen Clusternamen, um die Seite Übersicht für diesen Cluster zu öffnen.

3. Klicken Sie auf Importieren.

4. Wählen Sie unter Dateiformat die Option CSV aus.

5. Wählen Sie unter Quelldatei auswählen aus, ob Sie Dateien von Ihrem Computer hochladen oder eine Datei aus einem Cloud Storage-Speicherort auswählen möchten.

   1. So laden Sie eine Datei von Ihrem Computer hoch:

      1. Wählen Sie Dateien von Ihrem Computer hochladen aus.
      2. Klicken Sie neben Lokale Datei auswählen auf Durchsuchen, um eine CSV-Datei auf Ihrem lokalen Computer auszuwählen.
      3. Klicken Sie neben Cloud Storage-Speicherort auswählen auf Durchsuchen, um einen Cloud Storage-Speicherort für die hochgeladene lokale Datei auszuwählen.
      4. Klicken Sie auf Hochladen, um die Datei hochzuladen.

   2. So wählen Sie eine CSV-Datei aus, die sich in einem Cloud Storage-Bucket befindet:

      1. Wählen Sie Datei aus Google Cloud Storage auswählen aus.
      2. Klicken Sie neben bucket-name/file-name auf Durchsuchen, um eine CSV-Datei aus einem Cloud Storage-Bucket auszuwählen.

6. Wählen Sie im Drop-down-Menü Datenbank die Datenbank aus, in die die Daten importiert werden sollen.

7. Wählen Sie im Drop-down-Menü Tabelle die Tabelle in der Datenbank aus.

8. Optional: Wenn Sie einen Nutzer für den Importvorgang angeben möchten, klicken Sie auf Nutzeroptionen einblenden und geben Sie den Nutzernamen in das Feld Nutzer ein.

9. Klicken Sie auf Importieren, um den Importvorgang zu starten.

Hinweis: Sie können eine komprimierte .gz- oder eine unkomprimierte .csv-Datei importieren.

gcloud

1. Cloud Storage-Bucket erstellen
2. Laden Sie die CSV-Datei in den Bucket hoch. Informationen zum Hochladen von Dateien in Buckets finden Sie unter Objekte hochladen.

3. Weisen Sie mit gcloud storage buckets add-iam-policy-binding dem AlloyDB-Dienstkonto für den Bucket die IAM-Rolle storage.objectViewer zu:

    [e-mail]

   Weitere Informationen zum Festlegen von IAM-Berechtigungen finden Sie unter IAM-Berechtigungen verwenden.

4. Importieren Sie die Datei:

   gcloud alloydb clusters import CLUSTER_NAME \
     --region=REGION \
     --gcs-uri=gs://BUCKET_NAME/FILE_NAME \
     --database=DATABASE_NAME \
     --user=USER \
     --csv \
     --table=TABLE_NAME

   Hinweis: Sie können eine komprimierte Datei (.gz) oder eine unkomprimierte Datei (.csv) importieren.

   Ersetzen Sie Folgendes:

   • CLUSTER_NAME ist der Name des Clusters.
   • REGION: die Region, in der der AlloyDB-Cluster bereitgestellt wird.
   • BUCKET_NAME: der Name des Cloud Storage-Buckets.
   • FILE_NAME: der Name der CSV-Datei.
   • DATABASE_NAME: Der Name einer Datenbank im Cluster.
   • USER: der Nutzer für den Importvorgang.
   • TABLE_NAME: die Tabelle in der Datenbank.

   Weitere Informationen zur Verwendung des Befehls import finden Sie auf der Referenzseite des Befehls gcloud alloydb clusters import.

5. Wenn Sie die zuvor festgelegten IAM-Berechtigungen nicht beibehalten müssen, entfernen Sie sie mit gcloud storage buckets remove-iam-policy-binding.

REST Version 1

1. Cloud Storage-Bucket erstellen
2. Laden Sie die CSV-Datei in den Bucket hoch. Informationen zum Hochladen von Dateien in Buckets finden Sie unter Objekte hochladen.

3. Weisen Sie mit gcloud storage buckets add-iam-policy-binding dem AlloyDB-Clusterdienstkonto für den Bucket die IAM-Rolle storage.objectViewer zu. Das Format für das Dienstkonto sieht so aus:

   [e-mail]

   Weitere Informationen zum Festlegen von IAM-Berechtigungen finden Sie unter IAM-Berechtigungen verwenden.

4. Importieren Sie die Datei.

   Hinweis: Sie können eine komprimierte Datei (.gz) oder eine unkomprimierte Datei (.csv) importieren.

   Verwenden Sie die folgende HTTP-Methode und URL:

   POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID:import

   Ersetzen Sie folgende Werte in den Anfragedaten:

   • PROJECT_ID: Projekt-ID.
   • LOCATION_ID: die Region, in der der AlloyDB-Cluster bereitgestellt wird.
   • CLUSTER_ID: die Cluster-ID.
   • BUCKET_NAME: der Name des Cloud Storage-Buckets.
   • PATH_TO_CSV_FILE: der Pfad zur CSV-Datei.
   • USER: der Nutzer für den Importvorgang.
   • DATABASE_NAME: Der Name einer Datenbank im AlloyDB-Cluster.
   • TABLE_NAME: die Tabelle in der Datenbank.
   • COLUMNS (optional): die zu importierenden Spalten.
   • ESCAPE_CHARACTER (optional): das Zeichen, das vor einem Datenzeichen stehen muss, das maskiert werden soll. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden. Beispiel: 22 steht für ein doppeltes Anführungszeichen.
   • QUOTE_CHARACTER (optional): das Zeichen, das Werte aus Spalten mit dem Datentyp „String“ umschließt. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden. 22 steht beispielsweise für ein doppeltes Anführungszeichen.
   • FIELD_DELIMITER (optional): das Zeichen, das die Spaltenwerte aufteilt. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden. 2C steht beispielsweise für ein Komma.

   JSON-Text der Anfrage:

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

   Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

   curl (Linux, macOS oder Cloud Shell)

   Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der Google Cloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch in der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

   Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

      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)

   Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der Google Cloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch in der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

   Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

   $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 Content
   

   Sie erhalten eine JSON-Antwort ähnlich wie diese:

   Antwort

   {
    "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/CLUSTER_ID",
     "verb": "import",
     "requestedCancellation": false,
     "apiVersion": "v1"
    },
    "done": false
   }
   

5. Wenn Sie die zuvor festgelegten IAM-Berechtigungen nicht beibehalten möchten, entfernen Sie diese.

   Die vollständige Liste der Parameter für die Anfrage finden Sie unter clusters.import.

CSV-Format anpassen und Datei importieren

Sie können das CSV-Format anpassen und die Datei importieren, wenn die CSV-Datei nicht standardmäßige Feldtrennzeichen, Anführungszeichen oder Escape-Zeichen enthält. Wenn Sie eine CSV-Datei mit einem nicht standardmäßigen Format importieren möchten, müssen Sie in der Anfrage dieselben Formatierungsoptionen angeben.

Die folgenden gcloud CLI- und REST API-Beispiele können Ihnen beim Anpassen des CSV-Dateiformats helfen.

gcloud

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

REST Version 1

Der entsprechende REST API-Anfragetext sieht in etwa so aus:

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

Informationen zum Aufbau der zugrunde liegenden REST API-Anfrage für diese Aufgabe finden Sie im APIs Explorer auf der Seite clusters.import.

Hinweis: Wenn Sie in Ihren Importbefehlen benutzerdefinierte Formatoptionen verwenden, müssen Sie darauf achten, dass die exportierte Datei mit den gleichen Optionen erstellt wurde.

Wenn ein Fehler wie INVALID_ARGUMENT angezeigt wird, prüfen Sie, ob die Tabelle vorhanden ist. Ist die Tabelle vorhanden, sollten Sie ermitteln, ob Sie die richtigen Berechtigungen für den Bucket haben. Hilfe zum Konfigurieren der Zugriffssteuerung in Cloud Storage finden Sie unter Access Control Lists (ACLs) erstellen und verwalten.

Status eines Importvorgangs prüfen

So prüfen Sie den Status eines Importvorgangs:

gcloud

Führen Sie den folgenden Befehl mit gcloud alloydb operations describe aus:

gcloud alloydb operations describe OPERATION_ID --region=REGION

Der Status dieser Vorgänge wird im Feld STATUS angezeigt.

Sie können auch Details zu einem bestimmten Vorgang auflisten oder einen bestimmten Vorgang abbrechen. Weitere Informationen zu diesem Befehl finden Sie auf der Referenzseite für den Befehl gcloud alloydb operations.

REST Version 1

Verwenden Sie die Methode GET und die folgende URL:

GET https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID

Weitere Informationen finden Sie unter get.

Ersetzen Sie folgende Werte in den Anfragedaten:

• REGION: die Region, in der der AlloyDB-Cluster bereitgestellt wird.
• PROJECT_ID: Projekt-ID.
• OPERATION_ID: die ID des Importvorgangs. Weitere Informationen finden Sie unter Vorbereitung.

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch in der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie den folgenden Befehl aus:

  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)

Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud CLI angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie den folgenden Befehl aus:

$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

Wenn der Vorgang erfolgreich abgeschlossen wurde, enthält der Antworttext eine Instanz von Operation.

Nächste Schritte

• SQL-Datei importieren
• Importvorgang abbrechen