ייבוא של קובץ CSV

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

אפשר לבטל את הייבוא של נתונים לאשכולות AlloyDB. איך מבטלים פעולת ייבוא

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

לפני שמתחילים בפעולת ייבוא:

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

תפקידים והרשאות שנדרשים לייבוא לאשכולות AlloyDB

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

התפקיד AlloyDB Admin
תפקיד בהתאמה אישית, כולל ההרשאות הבאות:
- alloydb.clusters.get
- alloydb.clusters.import

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

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

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

ייבוא נתונים מקובץ CSV לאשכולות AlloyDB

מסד הנתונים והטבלה שאליהם אתם מייבאים צריכים להיות קיימים באשכול AlloyDB. למידע נוסף על יצירת מסד נתונים, אפשר לקרוא את המאמר יצירת מסד נתונים.
בקובצי CSV צריכה להיות שורה אחת לכל שורת נתונים, והשדות צריכים להיות מופרדים בפסיקים.

כדי לייבא נתונים לאשכול AlloyDB באמצעות קובץ CSV, פועלים לפי השלבים הבאים:

המסוף

עוברים לדף Clusters.

כניסה לדף Clusters
לוחצים על שם האשכול כדי לפתוח את הדף סקירה כללית של האשכול.
לוחצים על Import.
בקטע פורמט קובץ, בוחרים באפשרות CSV.
בקטע בחירת קובץ מקור, בוחרים אם להעלות קבצים מהמחשב או לבחור קובץ ממיקום באחסון בענן.
1. כדי להעלות קובץ מהמחשב:
  1. בוחרים באפשרות העלאת קבצים מהמחשב.
  2. לוחצים על עיון לצד בחירת קובץ מקומי כדי לבחור קובץ CSV מהמחשב.
  3. לוחצים על Browse (עיון) לצד Select Cloud Storage location (בחירת מיקום ב-Cloud Storage) כדי לבחור מיקום ב-Cloud Storage לאחסון הקובץ המקומי שהועלה.
  4. לוחצים על העלאה כדי להעלות את הקובץ.
2. כדי לבחור קובץ CSV שקיים בקטגוריה של Cloud Storage:
  1. בוחרים באפשרות בחירת קובץ מ-Google Cloud Storage.
  2. לוחצים על Browse לצד bucket-name/file-name כדי לבחור קובץ CSV ממאגר Cloud Storage.
בתפריט הנפתח מסד נתונים, בוחרים את מסד הנתונים שאליו רוצים לייבא את הנתונים.
בתפריט הנפתח טבלה, בוחרים את הטבלה במסד הנתונים.
זה שינוי אופציונלי. כדי לציין משתמש לפעולת הייבוא, לוחצים על הצגת אפשרויות משתמש ומזינים את שם המשתמש בשדה משתמש.
כדי להתחיל את פעולת הייבוא, לוחצים על ייבוא.

gcloud

יצירת קטגוריה של Cloud Storage
מעלים את קובץ ה-CSV לקטגוריה. לקבלת עזרה בהעלאת קבצים למאגרי מידע, ראו העלאת אובייקטים.
משתמשים בפקודה gcloud storage buckets add-iam-policy-binding כדי להעניק את תפקיד ה-IAM‏ storage.objectViewer לחשבון השירות של AlloyDB עבור הדלי.
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
במאמר שימוש בהרשאות IAM מוסבר איך מגדירים הרשאות IAM.
מייבאים את הקובץ:
```
gcloud alloydb clusters import CLUSTER_NAME --region=REGION --gcs-uri=gs://BUCKET_NAME/FILE_NAME --database=DATABASE_NAME --user=USER --csv --table=TABLE_NAME
```
הערה: אפשר לייבא קובץ דחוס (.gz) או קובץ לא דחוס (.csv).

מחליפים את הפרטים הבאים:
- ‫CLUSTER_NAME: שם האשכול.
- ‫REGION: האזור שבו נפרס אשכול AlloyDB.
- ‫BUCKET_NAME: שם הקטגוריה ב-Cloud Storage.
- ‫FILE_NAME: השם של קובץ ה-CSV.
- ‫DATABASE_NAME: השם של מסד נתונים בתוך האשכול.
- ‫USER: המשתמש של פעולת הייבוא.
- ‫TABLE_NAME: הטבלה בתוך מסד הנתונים.
מידע נוסף על השימוש בפקודה import זמין בדף העזרה של הפקודה alloydb import.
אם אין לכם צורך בהרשאות ה-IAM שהגדרתם קודם, אתם יכולים להסיר אותן באמצעות gcloud storage buckets remove-iam-policy-binding.

REST v1

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

הערה: אפשר לייבא קובץ דחוס (.gz) או קובץ לא דחוס (.csv).

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

הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של Google Cloud באמצעות חשבון המשתמש שלכם, על ידי הרצת 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/LOCATION_ID/clusters/CLUSTER_ID:import"
```
‎PowerShell (Windows)

הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של Google Cloud באמצעות חשבון המשתמש שלכם, על ידי הרצת 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/LOCATION_ID/clusters/CLUSTER_ID:import"| Select-Object -Expand Content
```
מקבלים תגובת JSON שדומה לזו:
תשובה
```
{
 "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/target-cluster",
  "verb": "import",
  "requestedCancellation": false,
  "apiVersion": "v1"
 },
 "done": false
}
```
אם אין לכם צורך לשמור את הרשאות ה-IAM שהגדרתם קודם, אתם יכולים להסיר אותן עכשיו.

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

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

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

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

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 v1

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

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

כדי לראות איך בנויה בקשת API בארכיטקטורת REST הבסיסית למשימה הזו, אפשר לעיין ב-APIs Explorer בדף clusters:import.

אם מופיעה שגיאה כמו INVALID_ARGUMENT, צריך לוודא שהטבלה קיימת. אם הטבלה קיימת, צריך לוודא שיש לכם את ההרשאות הנכונות בדלי. במאמר יצירה וניהול של רשימות של בקרת גישה מוסבר איך מגדירים בקרת גישה ב-Cloud Storage.

בדיקת הסטטוס של פעולת ייבוא

כדי לבדוק את הסטטוס של פעולת ייבוא:

gcloud

מריצים את הפקודה הבאה באמצעות הפקודה gcloud alloydb operations describe:

gcloud alloydb operations describe OPERATION_ID --region=REGION

הסטטוס של הפעולות האלה מופיע בשדה STATUS.

אפשר גם לראות את הפרטים של פעולה ספציפית או לבטל פעולה ספציפית. מידע נוסף על הפקודה הזו מופיע בדף העזרה של הפקודה gcloud alloydb operations.

REST v1

משתמשים בשיטת GET ובכתובת ה-URL הבאה:

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

מידע נוסף זמין במאמר get.

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

‫REGION: האזור שבו נפרס אשכול AlloyDB.
‫PROJECT_ID: מזהה הפרויקט.
‫OPERATION_ID: המזהה של פעולת הייבוא. מידע נוסף מופיע במאמר בנושא לפני שמתחילים.

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫curl‏ (Linux,‏ macOS או Cloud Shell)

מריצים את הפקודה הבאה:

  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)

מריצים את הפקודה הבאה:

$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

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

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של Operation.

ייבוא של קובץ CSV קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

תפקידים והרשאות שנדרשים לייבוא לאשכולות AlloyDB

ייבוא נתונים מקובץ CSV לאשכולות AlloyDB

המסוף

gcloud

REST v1

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

‎PowerShell (Windows)

תשובה

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

gcloud

REST v1

בדיקת הסטטוס של פעולת ייבוא

gcloud

REST v1

‫curl‏ (Linux,‏ macOS או Cloud Shell)

PowerShell (Windows)

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

ייבוא של קובץ CSV