‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

תבנית Cloud Storage Text to Spanner

התבנית Cloud Storage Text to Spanner היא צינור להעברת נתונים באצווה שקורא קובצי טקסט בפורמט CSV מ-Cloud Storage ומייבא אותם למסד נתונים של Spanner.

הדרישות לגבי צינורות עיבוד נתונים

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

קובץ המניפסט, בקידוד ASCII או UTF-8, חייב להיות בפורמט הבא:

פורמט המניפסט ודוגמה

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

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each Column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each Column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

בדוגמה הבאה מוצג קובץ מניפסט לייבוא טבלאות בשם Albums ו-Singers למסד נתונים בניב GoogleSQL. הטבלה Albums משתמשת בסכימת העמודות שהמשימה מאחזרת ממסד הנתונים, והטבלה Singers משתמשת בסכימה שצוינה בקובץ המניפסט:

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

קובצי הטקסט שרוצים לייבא צריכים להיות בפורמט CSV, עם קידוד ASCII או UTF-8. מומלץ לא להשתמש בסימן סדר הבייטים (BOM) בקבצים בקידוד UTF-8.

הנתונים צריכים להתאים לאחד מהסוגים הבאים:

GoogleSQL

    BOOL
    INT64
    FLOAT64
    NUMERIC
    STRING
    DATE
    TIMESTAMP
    BYTES
    JSON

PostgreSQL

    boolean
    bigint
    double precision
    numeric
    character varying, text
    date
    timestamp with time zone
    bytea

פרמטרים של תבניות

פרמטרים נדרשים

‫instanceId: מזהה המכונה של מסד הנתונים של Spanner.
‫databaseId: מזהה מסד הנתונים של Spanner.
‫importManifest: הנתיב ב-Cloud Storage שבו יש להשתמש כשמייבאים קובצי מניפסט. לדוגמה, gs://your-bucket/your-folder/your-manifest.json.

פרמטרים אופציונליים

‫spannerHost: נקודת הקצה של Cloud Spanner שאליה מתקשרים בתבנית. משמש רק לבדיקה. לדוגמה, https://batch-spanner.googleapis.com. ברירת המחדל היא: https://batch-spanner.googleapis.com.
‫columnDelimiter: התו שמפריד בין העמודות בקובץ המקור. ערך ברירת המחדל הוא ,. לדוגמה, ,.
‫fieldQualifier: התו שחייב להקיף כל ערך בקובץ המקור שמכיל את columnDelimiter. ערך ברירת המחדל הוא מירכאות כפולות.
‫trailingDelimiter: מציין אם בשורות בקובצי המקור יש תווי הפרדה בסוף השורה, כלומר אם התו columnDelimiter מופיע בסוף כל שורה, אחרי הערך של העמודה האחרונה. ערך ברירת המחדל הוא true.
escape: תו הבריחה שבו נעשה שימוש בקובץ המקור. כברירת מחדל, הפרמטר הזה לא מוגדר והתבנית לא משתמשת בתו בריחה.
‫nullString: המחרוזת שמייצגת ערך NULL. כברירת מחדל, הפרמטר הזה לא מוגדר והתבנית לא משתמשת במחרוזת null.
‫dateFormat: הפורמט שמשמש לניתוח עמודות של תאריכים. כברירת מחדל, צינור עיבוד הנתונים מנסה לנתח את עמודות התאריכים בפורמט yyyy-M-d[' 00:00:00'], למשל 2019-01-31 או 2019-1-1 00:00:00. אם פורמט התאריך שונה, צריך לציין את הפורמט באמצעות התבניות של java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
‫timestampFormat: הפורמט שמשמש לניתוח של עמודות חותמת הזמן. אם חותמת הזמן היא מספר שלם ארוך, היא מנותחת כזמן ראשית זמן יוניקס. אחרת, הוא מנותח כמחרוזת באמצעות הפורמט java.time.format.DateTimeFormatter.ISO_INSTANT (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT). במקרים אחרים, אפשר לציין מחרוזת תבנית משלכם, למשל, באמצעות MMM dd yyyy HH:mm:ss.SSSVV לחותמות זמן בפורמט Jan 21 1998 01:02:03.456+08:00.
‫spannerProjectId: המזהה של הפרויקט בענן של Google שמכיל את מסד הנתונים של Spanner. אם לא מגדירים את המדיניות, המערכת משתמשת במזהה הפרויקט של פרויקט ברירת המחדל ב-Google Cloud.
‫spannerPriority: העדיפות של הבקשה לשיחות עם Spanner. הערכים האפשריים הם HIGH,‏ MEDIUM ו-LOW. ערך ברירת המחדל הוא MEDIUM.
‫handleNewLine: אם הערך הוא true, נתוני הקלט יכולים להכיל תווי שורה חדשה. אחרת, תווי מעבר לשורה חדשה יגרמו לשגיאה. ערך ברירת המחדל הוא false. הפעלת האפשרות 'טיפול בשורות חדשות' עלולה להפחית את הביצועים.
‫invalidOutputPath: הנתיב ב-Cloud Storage שבו ייכתבו השורות שלא ניתן לייבא. לדוגמה, gs://your-bucket/your-path. ברירת המחדל היא ריקה.
‫maxNumRows: מספר השורות המקסימלי לכתיבה ב-Spanner. ערך ברירת המחדל הוא 500.

אם אתם צריכים להשתמש בפורמטים מותאמים אישית של תאריכים או חותמות זמן, ודאו שהם תואמים לתבניות תקפות של java.time.format.DateTimeFormatter. בטבלה הבאה מוצגות דוגמאות נוספות לפורמטים מותאמים אישית של עמודות תאריך וחותמת זמן:

סוג	ערך קלט	פורמט	הערה
`DATE`	2011-3-31		כברירת מחדל, התבנית יכולה לנתח את הפורמט הזה. אין צורך לציין את הפרמטר `dateFormat`.
`DATE`	2011-3-31 00:00:00		כברירת מחדל, התבנית יכולה לנתח את הפורמט הזה. אין צורך לציין את הפורמט. אם רוצים, אפשר להשתמש ב-`yyyy-M-d' 00:00:00'`.
`DATE`	‫1 באפריל 2018	dd MMM, yy
`DATE`	יום רביעי, 3 באפריל 2019 לספירה	EEEE, LLLL d, yyyy G
`TIMESTAMP`	‫2019-01-02T11:22:33Z ‫2019-01-02T11:22:33.123Z ‫2019-01-02T11:22:33.12356789Z		פורמט ברירת המחדל `ISO_INSTANT` יכול לנתח את סוג חותמת הזמן הזה. אין צורך לספק את הפרמטר `timestampFormat`.
`TIMESTAMP`	1568402363		כברירת מחדל, התבנית יכולה לנתח את סוג חותמת הזמן הזה ולהתייחס אליו כאל זמן ראשית יוניקס (Unix epoch).
`TIMESTAMP`	‫Tue, 3 Jun 2008 11:05:30 GMT	EEE, d MMM yyyy HH:mm:ss VV
`TIMESTAMP`	‪2018/12/31 110530.123PST	yyyy/MM/dd HHmmss.SSSz
`TIMESTAMP`	2019-01-02T11:22:33Z או 2019-01-02T11:22:33.123Z	yyyy-MM-dd'T'HH:mm:ss[.SSS]VV	אם עמודת הקלט היא שילוב של 2019-01-02T11:22:33Z ו-2019-01-02T11:22:33.123Z, הפורמט שמוגדר כברירת מחדל יכול לנתח את סוג חותמת הזמן הזה. לא צריך לספק פרמטר משלכם של פורמט. אפשר להשתמש ב-`yyyy-MM-dd'T'HH:mm:ss[.SSS]VV` כדי לטפל בשני המקרים. אי אפשר להשתמש ב-`yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'` כי הסיומת Z חייבת להיות מנותחת כמזהה אזור זמן, ולא כתווים מילוליים. באופן פנימי, עמודת חותמת הזמן מומרת ל-`java.time.Instant`. לכן, צריך לציין אותו לפי שעון UTC או לשייך אליו מידע על אזור הזמן. אי אפשר לנתח את התאריך והשעה המקומיים, כמו 2019-01-02 11:22:33, כערך תקין של `java.time.Instant`.
`TIMESTAMP`	‫2023-03-22 19:04:05 2023-03-22 19:04:05.3 2023-03-22 19:04:05.34 2023-03-22 19:04:05.345	`yyyy-MM-dd HH:mm:ss[.[SSS][SS][S]]`	אם עמודת הקלט מכילה חותמות זמן עם רמת דיוק שונה של שבריר השנייה, אפשר להשתמש בסוגריים כדי לציין מספר ספרות אופציונלי. בדוגמה הזו, אפשר להשתמש ב-0, 1, 2 או 3 ספרות אחרי הנקודה העשרונית.

הרצת התבנית

המסוף

עוברים לדף Create job from template (יצירת משימה מתבנית) ב-Dataflow.

כניסה לדף Create job from template

בשדה שם המשימה, מזינים שם ייחודי למשימה.
אופציונלי: בשדה Regional endpoint (נקודת קצה אזורית), בוחרים ערך מהתפריט הנפתח. אזור ברירת המחדל הוא us-central1.
רשימה של אזורים שבהם אפשר להריץ משימת Dataflow מופיעה במאמר מיקומי Dataflow.
בתפריט הנפתח Dataflow template (תבנית Dataflow), בוחרים את התבנית Text Files on Cloud Storage to Cloud Spanner (קובצי טקסט ב-Cloud Storage ל-Cloud Spanner).
בשדות הפרמטרים שמופיעים, מזינים את ערכי הפרמטרים.
לוחצים על הפעלת העבודה.

gcloud

במעטפת או בטרמינל, מריצים את התבנית:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates/VERSION/GCS_Text_to_Cloud_Spanner \
    --region REGION_NAME \
    --parameters \
instanceId=INSTANCE_ID,\
databaseId=DATABASE_ID,\
importManifest=GCS_PATH_TO_IMPORT_MANIFEST

מחליפים את מה שכתוב בשדות הבאים:

‫JOB_NAME: שם ייחודי של המשימה לפי בחירתכם
‫VERSION: הגרסה של התבנית שרוצים להשתמש בה
אפשר להשתמש בערכים הבאים:
- ‫latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בדלי – gs://dataflow-templates/latest/
- שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית. אפשר למצוא את הגרסה הזו בתיקיית ההורה המתאימה עם התאריך בדלי – gs://dataflow-templates/
זהירות: יכול להיות שעדכונים בגרסה העדכנית של התבניות יגרמו לשינויים שישברו את התאימות לאחור. כדי שהשינויים האלה לא ישפיעו על תהליכי העבודה שלכם בסביבת הייצור, בסביבות הייצור צריך להשתמש בתבניות שנשמרות בתיקייה הראשית עם תאריך העדכנית ביותר.
‫REGION_NAME: האזור שבו רוצים לפרוס את עבודת Dataflow, לדוגמה: us-central1
‫INSTANCE_ID: מזהה מכונת Spanner
‫DATABASE_ID: מזהה מסד הנתונים של Spanner
‫GCS_PATH_TO_IMPORT_MANIFEST: הנתיב ב-Cloud Storage לקובץ המניפסט של הייבוא

API

כדי להפעיל את התבנית באמצעות API בארכיטקטורת REST, שולחים בקשת HTTP POST. מידע נוסף על ה-API ועל היקפי ההרשאות שלו זמין במאמר projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates/VERSION/GCS_Text_to_Cloud_Spanner
{
   "jobName": "JOB_NAME",
   "parameters": {
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "importManifest": "GCS_PATH_TO_IMPORT_MANIFEST"
   },
   "environment": {
       "machineType": "n1-standard-2"
   }
}