תבנית 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

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

SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME =
      TABLE_NAME ORDER BY ORDINAL_POSITION

אזהרה: אם מסד הנתונים של Spanner ביעד לא ריק, יכול להיות שנתונים חדשים ידחפו נתונים קיימים.

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

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

• ‫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: הפורמט שמשמש לניתוח של עמודות חותמת הזמן. אם חותמת הזמן היא מספר שלם ארוך, היא מנותחת כזמן ראשית זמן יוניקס (Unix epoch). אחרת, הוא מנותח כמחרוזת באמצעות הפורמט 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 Cloud שמכיל את מסד הנתונים של Spanner. אם לא מגדירים את המדיניות, המערכת משתמשת במזהה הפרויקט של פרויקט ברירת המחדל ב-Google Cloud.
• ‫spannerPriority: העדיפות של הבקשה לקריאות Spanner. הערכים האפשריים הם HIGH,‏ MEDIUM ו-LOW. ערך ברירת המחדל הוא MEDIUM.
• ‫handleNewLine: אם הערך הוא true, נתוני הקלט יכולים להכיל תווי שורה חדשה. אחרת, תווי מעבר לשורה יגרמו לשגיאה. ערך ברירת המחדל הוא false. הפעלת האפשרות 'טיפול בשורות חדשות' עלולה לפגוע בביצועים.
• ‫invalidOutputPath: הנתיב ב-Cloud Storage שבו ייכתבו שורות שלא ניתן לייבא. לדוגמה, gs://your-bucket/your-path. ברירת המחדל היא ריק.

אם אתם צריכים להשתמש בפורמטים מותאמים אישית של תאריכים או חותמות זמן, ודאו שהם תואמים לתבניות תקפות של 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.

הפעלת התבנית

המסוף

1. עוברים לדף Dataflow Create job from template (יצירת משימה מתבנית).
כניסה לדף Create job from template
2. בשדה שם המשימה, מזינים שם ייחודי למשימה.
3. אופציונלי: בשדה Regional endpoint (נקודת קצה אזורית), בוחרים ערך מהתפריט הנפתח. אזור ברירת המחדל הוא us-central1.

   רשימת האזורים שבהם אפשר להריץ משימת Dataflow מופיעה במאמר מיקומי Dataflow.

4. בתפריט הנפתח Dataflow template (תבנית של העברת נתונים), בוחרים באפשרות the Text Files on Cloud Storage to Cloud Spanner template.
5. בשדות הפרמטרים שמופיעים, מזינים את ערכי הפרמטרים.
6. לוחצים על הפעלת העבודה.

gcloud

הערה: כדי להשתמש ב-Google Cloud CLI להפעלת תבניות classic, צריך להתקין את Google Cloud CLI בגרסה 138.0.0, או בגרסה מאוחרת יותר.

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

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/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-REGION_NAME/latest/
  • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית, שאפשר למצוא אותה בתיקיית האב המתאימה עם התאריך בדלי – gs://dataflow-templates-REGION_NAME/
  זהירות: יכול להיות שגרסת התבניות העדכנית תתעדכן עם שינויים שעלולים לשבור את התאימות לאחור. כדי למנוע מהשינויים האלה לשבש את תהליכי העבודה בסביבת הייצור, צריך להשתמש בתבניות שנשמרות בתיקייה הראשית עם תאריך העדכנית ביותר בסביבות הייצור.
• ‫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-LOCATION/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"
   }
}

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

• ‫PROJECT_ID: מזהה הפרויקט שבו רוצים להריץ את משימת Dataflow Google Cloud
• ‫JOB_NAME: שם ייחודי של המשימה לפי בחירתכם
• ‫VERSION: הגרסה של התבנית שבה רוצים להשתמש

  אפשר להשתמש בערכים הבאים:

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

קוד המקור של התבנית

Java

קוד המקור של התבנית הזו נמצא במאגר GoogleCloudPlatform/DataflowTemplates ב-GitHub.

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

• מידע נוסף על תבניות Dataflow
• רשימת התבניות ש-Google סיפקה