ייצוא קובץ CSV

בדף הזה מוסבר איך לייצא נתונים מאשכולות של AlloyDB ל-PostgreSQL לקטגוריה של Cloud Storage בפורמט CSV, שאפשר להשתמש בו בכלים ובסביבות אחרות.

מידע על העברה של מסד נתונים שלם משרת מסד נתונים נתמך למופע חדש של AlloyDB זמין במאמר העברת מסד נתונים ל-AlloyDB באמצעות Database Migration Service. אם אתם מייצאים כי אתם רוצים ליצור מופע חדש מהקובץ המיוצא, כדאי לשקול שחזור של אשכול מגיבוי מאוחסן.

אתם יכולים לבטל את ייצוא הנתונים מאשכולות של AlloyDB ל-PostgreSQL. מידע נוסף מופיע במאמר ביטול ייצוא נתונים.

לפני שמתחילים

לפני שמתחילים פעולת ייצוא, חשוב לזכור שפעולות ייצוא משתמשות במשאבי מסד נתונים, אבל הן לא מפריעות לפעולות רגילות של מסד נתונים, אלא אם המופע לא הוקצה בצורה מספקת.
השדה SELECT_QUERY יכול להכיל הערות או רווחים לבנים בתחילתו או בסופו. המערכת מתעלמת מהערות ומסירה רווחים לבנים לפני הפעלת שאילתת הייצוא.
חיובים על העברת נתונים בין אזורים חלים כשהקטגוריה של היעד נמצאת באזור שונה מהאזור של אשכול המקור. מידע נוסף זמין במאמר בנושא תמחור של AlloyDB ל-PostgreSQL.
אפשר להריץ כמה פעולות ייצוא במקביל.
הדחיסה מופעלת אם שם האובייקט מסתיים בסיומת .gz. האובייקט מיוצא בפורמט .gz ל-Cloud Storage.
בפרמטרים של קובץ CSV כמו field_delimiter,‏ quote_character ו-escape_character, אפשר להשתמש רק בתווי ASCII בפורמט הקסדצימלי (עם הקידומת 0x או בלעדיה).

תפקידים והרשאות שנדרשים לייצוא מ-AlloyDB

כדי לייצא נתונים מ-AlloyDB ל-Cloud Storage, למשתמש שמפעיל את הייצוא צריך להיות אחד מהתפקידים הבאים בניהול זהויות והרשאות גישה (IAM):

התפקיד Cloud AlloyDB Admin (roles/alloydb.admin)
תפקיד בהתאמה אישית, כולל ההרשאות הבאות:
- alloydb.clusters.get
- alloydb.clusters.export

בנוסף, לחשבון השירות של אשכול AlloyDB צריך להיות אחד מהתפקידים הבאים:

תפקיד IAM‏ storage.objectAdmin
תפקיד בהתאמה אישית, כולל ההרשאות הבאות:
- storage.objects.create

במאמר ניהול זהויות והרשאות גישה מוסבר איך משתמשים בתפקידים ב-IAM.

ייצוא נתונים לקובץ CSV

במהלך ייצוא של קובץ CSV, אפשר לציין את הסכימות לייצוא. אפשר לייצא את כל הסכימות ברמת מסד הנתונים.

אפשר להשתמש ב-CLI של gcloud או ב-API בארכיטקטורת REST כדי להתאים אישית את פורמט קובץ ה-CSV.

gcloud

יצירת קטגוריה של Cloud Storage
נותנים לחשבון השירות הרשאות לקטגוריה של Cloud Storage עבור פעולת הייצוא. משתמשים בפורמט של חשבון השירות כדי לזהות את חשבון השירות של הפרויקט שממנו מייצאים. הפורמט של חשבון השירות הוא:
```
service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
משתמשים ב-gcloud storage buckets add-iam-policy-binding כדי להקצות את התפקיד ב-IAM‏ storage.objectAdmin לחשבון השירות. במאמר שימוש בהרשאות IAM מוסבר איך מגדירים הרשאות IAM.

הערה: אם אובייקט קיים נושא את אותו שם כמו האובייקט שמיוצא לקטגוריה של Cloud Storage, הקצאת התפקיד objectAdmin לחשבון השירות תגרום להחלפת האובייקט הישן יותר. כדי להימנע מכך, אפשר לתת לחשבון השירות את ההרשאה עם פחות הרשאות storage.objectCreator, שלא יכולה להחליף אובייקטים קיימים.
מייצאים את מסד הנתונים לקטגוריה של Cloud Storage.

מריצים את הפקודה לייצוא קובץ CSV: gcloud alloydb clusters export.

בטבלה הבאה מפורטות האפשרויות לייצוא נתונים בפורמט CSV:
- ‫--select-query (חובה): שאילתת הבחירה שמשמשת לחילוץ הנתונים.
הערה: במהלך ההעברה, יכול להיות שהשאילתה תעבור עיבוד במיקומי ביניים שונים, ולא במיקום של מופע היעד.
- ‫--async (אופציונלי): חזרה מיידית, בלי להמתין שהפעולה תסתיים.
- ‫--field-delimiter (אופציונלי): מציין את התו שמפריד בין העמודות בכל שורה (line) בקובץ. ברירת המחדל היא פסיק. הערך של הארגומנט הזה חייב להיות תו בקוד ASCII הקסדצימלי.
- ‫--quote-character (אופציונלי): מציין את תו המירכאות שבו יש להשתמש כשערך נתונים מוקף במירכאות. ברירת המחדל היא מרכאות כפולות. הערך של הארגומנט הזה חייב להיות תו בקוד ASCII הקסדצימלי.
- ‫--escape-character (אופציונלי): מציין את התו שצריך להופיע לפני תו נתונים שצריך להוסיף לו תו בריחה. ערך ברירת המחדל זהה לערך של --quote-character. הערך של הארגומנט הזה חייב להיות תו בקוד ASCII הקסדצימלי.
כדי להשתמש בתכונות האלה, צריך לכלול את האפשרויות האלה בפקודה של ה-CLI של gcloud.

אחרת, מסירים את הפרמטרים האלה מהפקודה הבאה:
```
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
```
אם אין צורך לשמור את תפקיד ה-IAM שהגדרתם קודם, בטלו אותו עכשיו.

REST v1

יוצרים קטגוריה לייצוא:

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

משתמשים בפורמט של חשבון השירות כדי לזהות את חשבון השירות של הפרויקט שממנו מייצאים.

הפורמט של חשבון השירות הוא:
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
צריך לתת לו הרשאות לקטגוריה של Cloud Storage כדי לבצע את פעולת הייצוא.
משתמשים בפקודה gcloud storage buckets add-iam-policy-binding כדי להקצות לחשבון השירות את storage.objectAdmin תפקיד ה-IAM. במאמר שימוש בהרשאות IAM מוסבר איך מגדירים הרשאות IAM.

הערה: אם כבר קיים אובייקט באותו שם של האובייקט שמיוצא בקטגוריה של Cloud Storage, הענקת התפקיד objectAdmin לחשבון השירות תגרום להחלפת האובייקט הישן יותר. כדי להימנע מכך, אפשר להעניק לחשבון השירות את ההרשאה עם פחות הרשאות storage.objectCreator, שלא מאפשרת להחליף אובייקטים שכבר קיימים.
מייצאים את מסד הנתונים.

משתמשים ב-method הבא ב-HTTP ובכתובת ה-URL:
```
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export
```
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- ‫PROJECT_ID: מזהה הפרויקט.
- ‫REGION: האזור שבו נפרס אשכול AlloyDB.
- ‫CLUSTER_ID: מזהה האשכול.
- ‫BUCKET_NAME: שם הקטגוריה ב-Cloud Storage.
- ‫PATH_TO_CSV_FILE: הנתיב לקובץ ה-CSV.
- ‫DATABASE_NAME: השם של מסד נתונים בתוך אשכול AlloyDB.
- ‫SELECT_QUERY: שאילתת ה-SQL לייצוא.
  
  הערה: במהלך ההעברה, יכול להיות שהשאילתה תעובד במיקומי ביניים שונים, ולא במיקום של מופע היעד.
- ‫ESCAPE_CHARACTER (אופציונלי): התו שצריך להופיע לפני תו נתונים שצריך להוסיף לו תו בריחה. הערך של הארגומנט הזה חייב להיות תו בקוד ASCII הקסדצימלי. לדוגמה, ‫22 מייצג מרכאות כפולות.
- ‫QUOTE_CHARACTER (אופציונלי): התו שמקיף ערכים מעמודות עם סוג נתונים של מחרוזת. הערך של הארגומנט הזה חייב להיות תו בקוד ASCII הקסדצימלי. לדוגמה, 22 מייצג מרכאות כפולות.
- ‫FIELD_DELIMITER (אופציונלי): התו שמפצל את ערכי העמודות. הערך של הארגומנט הזה חייב להיות תו בקוד ASCII הקסדצימלי. לדוגמה, 2C מייצג פסיק.
תוכן בקשת 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"
  }
}
```
כדי לשלוח את הבקשה, אפשר לבחור באחת מהאפשרויות הבאות:

‏Curl (Linux,‏ macOS או Cloud Shell)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

       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)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

    $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

מקבלים תגובת JSON שדומה לזו:

תשובה

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

אם אין לכם צורך לשמור את הרשאות ה-IAM שהגדרתם קודם, אתם יכולים להסיר אותן עכשיו.

רשימה מלאה של הפרמטרים של הבקשה מופיעה במאמר בנושא clusters:export.

התאמה אישית של הפורמט של קובץ CSV לייצוא

אפשר להשתמש ב-CLI של gcloud או ב-API בארכיטקטורת REST כדי להתאים אישית את פורמט קובץ ה-CSV. כשמבצעים ייצוא, אפשר לציין את אפשרויות הפורמט הבאות:

אפשרות CSV	ערך ברירת המחדל	gcloud flag	מאפיין API בארכיטקטורת REST	תיאור
Escape	ערך ברירת המחדל זהה לערך `QUOTE`.	`--escape-character`	`escape_character`	התו שמופיע לפני תו נתונים שצריך להוסיף לו תו בריחה.
ציטוט	`"22"` קוד הקסדצימלי של ASCII למירכאות כפולות.	`--quote-character`	`quote_character`	מציין את תו המירכאות שבו צריך להשתמש כשערך נתונים מופיע במירכאות.
תו מפריד בין שדות	`"2C"` קוד הקסדצימלי של פסיק ב-ASCII.	`--field-delimiter`	`field_delimiter`	התו שמפריד בין ערכי העמודות.

לדוגמה, פקודה ב-CLI של gcloud שמשתמשת בכל הארגומנטים האלה יכולה להיראות כך:

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

גוף בקשת ה-API המקבילה בארכיטקטורת REST נראה כך:

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

כברירת מחדל, הייצוא לקובץ CSV יוצר פלט CSV רגיל. אם אתם צריכים אפשרויות נוספות מעבר לאלה שמסופקות על ידי AlloyDB, אתם יכולים להשתמש בהצהרה הבאה בלקוח 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');