תבנית Spanner ל-Cloud Storage Avro

התבנית Spanner to Avro Files on Cloud Storage היא צינור עיבוד נתונים באצווה שמייצא מסד נתונים שלם של Spanner ל-Cloud Storage בפורמט Avro. כשמייצאים מסד נתונים של Spanner, נוצרת תיקייה בדלי שבוחרים. התיקייה מכילה:

  • קובץ spanner-export.json.
  • קובץ TableName-manifest.json לכל טבלה במסד הנתונים שייצאתם.
  • קובץ TableName.avro-#####-of-##### אחד או יותר.

לדוגמה, ייצוא של מסד נתונים עם שתי טבלאות, Singers ו-Albums, יוצר את קבוצת הקבצים הבאה:

  • Albums-manifest.json
  • Albums.avro-00000-of-00002
  • Albums.avro-00001-of-00002
  • Singers-manifest.json
  • Singers.avro-00000-of-00003
  • Singers.avro-00001-of-00003
  • Singers.avro-00002-of-00003
  • spanner-export.json

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

  • מסד הנתונים של Spanner חייב להתקיים.
  • קטגוריית הפלט של Cloud Storage חייבת להתקיים.
  • בנוסף לתפקידים של ניהול זהויות והרשאות גישה (IAM) שנדרשים להפעלת משימות Dataflow, אתם צריכים גם תפקידי IAM מתאימים כדי לקרוא את נתוני Spanner ולכתוב לקטגוריה של Cloud Storage.

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

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

  • ‫instanceId: מזהה המכונה של מסד הנתונים ב-Spanner שרוצים לייצא.
  • ‫databaseId: המזהה של מסד הנתונים ב-Spanner שרוצים לייצא.
  • ‫outputDir: הנתיב ב-Cloud Storage לייצוא קובצי Avro. משימת הייצוא יוצרת ספרייה חדשה בנתיב הזה, שמכילה את הקבצים שיוצאו. לדוגמה, gs://your-bucket/your-path.

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

  • ‫avroTempDirectory: הנתיב ב-Cloud Storage שבו נכתבים קובצי Avro זמניים.
  • ‫spannerHost: נקודת הקצה של Cloud Spanner שאליה תתבצע הקריאה בתבנית. משמש לבדיקה בלבד. לדוגמה, https://batch-spanner.googleapis.com. ברירת המחדל: https://batch-spanner.googleapis.com.
  • ‫snapshotTime: חותמת הזמן שתואמת לגרסה של מסד הנתונים ב-Spanner שרוצים לקרוא. חותמת הזמן צריכה להיות בפורמט Zulu RFC 3339 UTC. חותמת הזמן חייבת להיות בעבר, ויש מגבלה על משך הזמן שחלף מאז חותמת הזמן. לדוגמה, 1990-12-31T23:59:60Z. ברירת המחדל היא ריק.
  • ‫spannerProjectId: המזהה של הפרויקט ב-Google Cloud שמכיל את מסד הנתונים ב-Spanner שרוצים לקרוא ממנו נתונים.
  • ‫shouldExportTimestampAsLogicalType: אם הערך הוא true, חותמות הזמן מיוצאות כסוג long עם סוג לוגי timestamp-micros. כברירת מחדל, הפרמטר הזה מוגדר כ-false וחותמות הזמן מיוצאות כמחרוזות ISO-8601 ברמת דיוק של ננו-שניות.
  • ‫tableNames: רשימה מופרדת בפסיקים של טבלאות שמציינות את קבוצת המשנה של מסד הנתונים ב-Spanner שרוצים לייצא. אם מגדירים את הפרמטר הזה, צריך לכלול את כל הטבלאות הקשורות (טבלאות הורה וטבלאות עם הפניה למפתח זר) או להגדיר את הפרמטר shouldExportRelatedTables לערך true.אם הטבלה נמצאת בסכימה עם שם, צריך להשתמש בשם המלא. לדוגמה: sch1.foo, כאשר sch1 הוא שם הסכימה ו-foo הוא שם הטבלה. ברירת המחדל היא ריק.
  • ‫shouldExportRelatedTables: אם לכלול טבלאות קשורות. הפרמטר הזה משמש בשילוב עם הפרמטר tableNames. ברירת המחדל: false.
  • ‫spannerPriority: העדיפות של הבקשה לקריאות ל-Spanner. הערכים האפשריים הם HIGH,‏ MEDIUM ו-LOW. ערך ברירת המחדל הוא MEDIUM.
  • ‫dataBoostEnabled: מגדירים את הערך true כדי להשתמש במשאבי המחשוב של Spanner Data Boost להרצת המשימה, עם השפעה כמעט אפסית על תהליכי העבודה של Spanner OLTP. כשמגדירים את הערך true, צריך גם את הרשאת ה-IAM‏ spanner.databases.useDataBoost. מידע נוסף זמין בסקירה הכללית של Data Boost‏ (https://cloud.google.com/spanner/docs/databoost/databoost-overview). ברירת המחדל: false.
  • ‫checksumAlgorithm: אלגוריתם סיכום הביקורת שבו משתמשים בקבצים שמייצאים. הערכים האפשריים הם MD5 ו-CRC32C. ערך ברירת המחדל הוא MD5.
  • ‫maxDataBoostParallelism: המספר המקסימלי של בקשות Data Boost בו-זמניות שמותרות למשימה הזו. אם לא מגדירים את הפרמטר, התבנית שולחת שאילתה למכסת Cloud Spanner Data Boost של הפרויקט והאזור, וחוזרת ל-400 אם אי אפשר לאחזר את המכסה.

הפעלת התבנית

המסוף

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

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

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

gcloud

בדוגמה הזו משתמשים בפקודה gcloud dataflow jobs run.

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

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates/VERSION/Cloud_Spanner_to_GCS_Avro \
    --region REGION_NAME \
    --staging-location GCS_STAGING_LOCATION \
    --parameters 'instanceId=INSTANCE_ID,databaseId=DATABASE_ID,outputDir=GCS_DIRECTORY'

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

  • ‫JOB_NAME: שם ייחודי של המשימה לפי בחירתכם

    כדי שהמשימה תופיע בקטע של Spanner במסוף Google Cloud , שם המשימה צריך להיות בפורמט cloud-spanner--INSTANCE_ID-DATABASE_ID.

  • ‫VERSION: גרסת התבנית שבה רוצים להשתמש

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

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

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/Cloud_Spanner_to_GCS_Avro
{
   "jobName": "JOB_NAME",
   "parameters": {
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "outputDir": "gs://GCS_DIRECTORY"
   }
}

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

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

    כדי שהמשימה תוצג בחלק של Spanner ב Google Cloud מסוף, שם המשימה צריך להיות בפורמט cloud-spanner--INSTANCE_ID-DATABASE_ID.

  • ‫VERSION: גרסת התבנית שבה רוצים להשתמש

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

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

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