ייצוא קובץ CSV

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

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

אתם יכולים לבטל את הייצוא של נתונים מאשכולות של AlloyDB ל-PostgreSQL. איך מבטלים פעולת ייצוא?

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

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

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

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

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

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

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

למידע נוסף על תפקידי IAM, קראו את המאמר ניהול זהויות והרשאות גישה.

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

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

הערה: ב-AlloyDB, תו בריחה (escape) שמוגדר כברירת מחדל הוא מירכאות כפולות (ערך הקסדצימלי 22). זו יכולה להיות בעיה במסדי נתונים שבהם הערכים של NULL מוזנים כמחרוזות מילוליות.

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

gcloud

1. יצירת קטגוריה של Cloud Storage

2. משתמשים ב-gcloud storage buckets add-iam-policy-binding כדי להקצות את התפקיד ב-IAM (storage.objectAdmin) לחשבון השירות של AlloyDB בקטגוריה. הפורמט של חשבון השירות הוא:

   service-PROJECT_NUMBER@gcp-sa-alloydb.

   במאמר שימוש בהרשאות IAM מוסבר איך מגדירים הרשאות IAM.

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

3. מייצאים את מסד הנתונים לקטגוריה של Cloud Storage.

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

   ברשימה הבאה מתוארות האפשרויות לייצוא נתונים בפורמט CSV:

   • --select-query (חובה): שאילתת הבחירה שמשמשת לחילוץ הנתונים.
   הערה: בזמן המעבר, יכול להיות שהשאילתה תעובד במיקומי ביניים שונים מהמיקום של מכונת היעד.
   • ‫--async (אופציונלי): חזרה מיידית, בלי להמתין שהפעולה תסתיים.
   • ‫--field-delimiter (אופציונלי): התו שמפריד בין העמודות בכל שורה בקובץ. ברירת המחדל היא פסיק. הערך של הארגומנט הזה חייב להיות תו בקוד 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

4. אם אתם לא צריכים לשמור את תפקיד ה-IAM שהגדרתם קודם, אתם יכולים לבטל אותו.

REST v1

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

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

2. משתמשים ב-gcloud storage buckets add-iam-policy-binding כדי להקצות את תפקיד ה-IAM storage.objectAdmin לחשבון השירות של AlloyDB בקטגוריה. הפורמט של חשבון השירות הוא:

   service-PROJECT_NUMBER@gcp-sa-alloydb.

   במאמר שימוש בהרשאות IAM מוסבר איך מגדירים הרשאות IAM.

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

3. מייצאים את מסד הנתונים.
   

   משתמשים ב-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 (אופציונלי): התו שצריך להופיע לפני תו נתונים שצריך להוסיף לו תו בריחה (escape). הערך של הארגומנט הזה חייב להיות תו בקוד 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)

הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-Google Cloud CLI באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-ה-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם 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)

הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-Google Cloud CLI באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-ה-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם 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	נכס API בארכיטקטורת REST	תיאור
Escape	ברירת המחדל זהה לערך של QUOTE.	--escape-character	escape_character	תו שמופיע לפני תו נתונים שצריך להוסיף לו תו בריחה (escape).
ציטוט	"22" קוד הקסדצימלי ב-ASCII למירכאות כפולות.	--quote-character	quote_character	מציין את תו המירכאות שבו צריך להשתמש כשערך נתונים מוקף במירכאות.
תו מפריד בין שדות	"2C" קוד הקסדצימלי של ASCII לפסיק.	--field-delimiter	field_delimiter	התו שמפריד בין ערכי העמודות.

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

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

REST v1

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

{
  "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');

המאמרים הבאים

• איך מייצאים קובץ SQL מוכן לשימוש
• ביטול של פעולת ייצוא.