תבנית של סנכרון שינויים בזרמי נתונים ב-Spanner ל-Pub/Sub

תבנית ה-Spanner סנכרון שינויים בזרמי נתונים ל-Pub/Sub היא פייפליין בסטרימינג שמעביר בסטרימינג רשומות של שינויים בנתוני Spanner וכותב אותן לנושאים ב-Pub/Sub באמצעות Dataflow Portable Runner.

כדי להוציא את הנתונים לנושא חדש ב-Pub/Sub, צריך קודם ליצור את הנושא. אחרי שיוצרים את הנושא, Pub/Sub יוצר ומצרף באופן אוטומטי מינוי לנושא החדש. אם מנסים להוציא נתונים לנושא Pub/Sub שלא קיים, צינור הנתונים של Dataflow זורק חריגה, והצינור נתקע כי הוא מנסה ליצור חיבור באופן רציף.

אם נושא Pub/Sub הנדרש כבר קיים, אפשר להוציא נתונים לנושא הזה.

מידע נוסף זמין במאמרים מידע על סנכרון שינויים בזרמי נתונים, יצירת חיבורים לסנכרון שינויים בזרמי נתונים באמצעות Dataflow ושיטות מומלצות לשימוש בסנכרון שינויים בזרמי נתונים.

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

  • מופע Spanner צריך להתקיים לפני שמריצים את צינור הנתונים.
  • מסד הנתונים של Spanner צריך להתקיים לפני שמריצים את צינור העיבוד.
  • מופע המטא-נתונים של Spanner צריך להתקיים לפני שמריצים את צינור העיבוד.
  • מסד הנתונים של המטא-נתונים של Spanner צריך להתקיים לפני שמריצים את צינור העיבוד.
  • השינוי ב-Spanner צריך להתבצע לפני שמריצים את צינור הנתונים.
  • הנושא ב-Pub/Sub חייב להתקיים לפני שמריצים את צינור הנתונים.

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

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

  • ‫spannerInstanceId: מכונת Spanner שממנה ייקראו נתוני שינויים.
  • ‫spannerDatabase: מסד הנתונים של Spanner שממנו יקראו את סנכרון שינויים בזרמי נתונים.
  • ‫spannerMetadataInstanceId: מופע Spanner לשימוש בטבלת המטא-נתונים של מחבר הנתונים של זרמי השינויים.
  • ‫spannerMetadataDatabase: מסד הנתונים של Spanner שבו יש להשתמש עבור טבלת המטא-נתונים של מחבר הנתונים של שינוי הזרמים.
  • ‫spannerChangeStreamName: השם של שינוי השידור ב-Spanner שממנו ייקראו הנתונים.
  • ‫pubsubTopic: נושא Pub/Sub לפלט של סנכרון שינויים בזרמי נתונים.

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

  • ‫spannerProjectId: הפרויקט שממנו יקראו את נתוני סנכרון שינויים בזרמי נתונים. בפרויקט הזה נוצרת גם טבלת המטא-נתונים של המחבר של זרמי השינויים. ערך ברירת המחדל של הפרמטר הזה הוא הפרויקט שבו צינור Dataflow פועל.
  • ‫spannerDatabaseRole: תפקיד מסד הנתונים ב-Spanner שבו יש להשתמש כשמריצים את התבנית. הפרמטר הזה נדרש רק אם משתמש ה-IAM שמריץ את התבנית הוא משתמש עם בקרת גישה ברמת דיוק גבוהה. לתפקיד במסד הנתונים צריכה להיות הרשאת SELECT בסנכרון שינויים בזרמי נתונים והרשאת EXECUTE בפונקציית הקריאה של סנכרון שינויים בזרמי נתונים. מידע נוסף זמין במאמר בנושא בקרת גישה ברמת גרנולריות גבוהה לסנכרון שינויים בזרמי נתונים (https://cloud.google.com/spanner/docs/fgac-change-streams).
  • ‫spannerMetadataTableName: השם של טבלת המטא-נתונים של מחבר Spanner change streams שבה רוצים להשתמש. אם לא מספקים את המידע הזה, מערכת Spanner יוצרת באופן אוטומטי את טבלת המטא-נתונים של מחבר הזרמים במהלך השינוי של צינור הנתונים. כשמעדכנים צינור קיים, צריך לציין את הפרמטר הזה. אין להשתמש בפרמטר הזה במקרים אחרים.
  • ‫startTimestamp: תאריך ושעת ההתחלה (https://tools.ietf.org/html/rfc3339), כולל, לשימוש בקריאת סנכרון שינויים בזרמי נתונים. לדוגמה, ex- 2021-10-12T07:20:50.52Z. ברירת המחדל היא חותמת הזמן של תחילת הצינור, כלומר השעה הנוכחית.
  • endTimestamp: התאריך והשעה (https://tools.ietf.org/html/rfc3339) של סוף טווח הזמן שרוצים להשתמש בו לקריאת סנכרון שינויים בזרמי נתונים. לדוגמה, ex- 2021-10-12T07:20:50.52Z. ברירת המחדל היא זמן אינסופי בעתיד.
  • ‫spannerHost: נקודת הקצה של Cloud Spanner שאליה מתקשרים בתבנית. משמש רק לבדיקה. לדוגמה, https://spanner.googleapis.com. ברירת המחדל היא: https://spanner.googleapis.com.
  • ‫outputDataFormat: פורמט הפלט. הפלט עטוף בהרבה PubsubMessages ונשלח לנושא Pub/Sub. הפורמטים המותרים הם JSON ו-AVRO. ברירת המחדל היא JSON.
  • ‫pubsubAPI: Pub/Sub API שמשמש להטמעה של צינור עיבוד הנתונים. ממשקי ה-API המותרים הם pubsubio ו-native_client. במספר קטן של שאילתות לשנייה (QPS), זמן האחזור של native_client קצר יותר. אם יש מספר גדול של QPS, pubsubio מספק ביצועים טובים ויציבים יותר. ערך ברירת המחדל הוא pubsubio.
  • ‫pubsubProjectId: הפרויקט של נושא Pub/Sub. ערך ברירת המחדל של הפרמטר הזה הוא הפרויקט שבו צינור Dataflow פועל.
  • ‫rpcPriority: העדיפות של הבקשה לקריאות Spanner. הערכים המותרים הם HIGH,‏ MEDIUM ו-LOW. ברירת המחדל היא: HIGH).
  • includeSpannerSource: האם לכלול את מזהה מסד הנתונים ומזהה המופע של Spanner כדי לקרוא את סנכרון שינויים בזרמי נתונים בהודעת הפלט. ברירת המחדל היא false.
  • ‫outputMessageMetadata: ערך המחרוזת של השדה המותאם אישית outputMessageMetadata בהודעת הפלט של pub/sub. ברירת המחדל היא ריק, והשדה outputMessageMetadata מאוכלס רק אם הערך הזה לא ריק. כשמזינים את הערך כאן, צריך להוסיף תו בריחה (escape) לכל התווים המיוחדים (למשל: מירכאות כפולות).
  • ‫useSpannerEmulatorHost: האם להשתמש במארח Spanner שהוגדר ב-getSpannerHost() כמארח האמולטור. ברירת המחדל היא false.
  • ‫spannerChangeStreamTvfNameList: רשימה של שמות של פונקציות טבלאיות (TVF) של Spanner Change Stream שמופרדים באמצעות נקודה-פסיק, שאותן רוצים לשלוח כשאילתה ולבצע איחוד. ברירת המחדל היא ריקה.
  • ‫spannerDirectedReadOptions: אפשרויות קריאה מכוונות לקריאות של Cloud Spanner Change Stream. הערך צריך להיות בפורמט מחרוזת JSON של DirectedReadOptions (למשל, {"includeReplicas":{"replicaSelections":[{"location":"us-central1","type":"READ_ONLY"}]}}). מידע נוסף זמין במאמר בנושא קריאות מונחות (https://docs.cloud.google.com/spanner/docs/directed-reads). ברירת המחדל היא ריקה.

הרצת התבנית

המסוף

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

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

  5. בתפריט הנפתח Dataflow template (תבנית Dataflow), בוחרים בתבנית Cloud Spanner change streams to Pub/Sub (סנכרון שינויים בזרמי נתונים מ-Cloud Spanner ל-Pub/Sub).
  6. בשדות הפרמטרים שמופיעים, מזינים את ערכי הפרמטרים.
  7. לוחצים על הפעלת העבודה.

gcloud

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

    gcloud dataflow flex-template run JOB_NAME \
        --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Spanner_Change_Streams_to_PubSub \
        --region REGION_NAME \
        --parameters \
    spannerInstanceId=SPANNER_INSTANCE_ID,\
    spannerDatabase=SPANNER_DATABASE,\
    spannerMetadataInstanceId=SPANNER_METADATA_INSTANCE_ID,\
    spannerMetadataDatabase=SPANNER_METADATA_DATABASE,\
    spannerChangeStreamName=SPANNER_CHANGE_STREAM,\
    pubsubTopic=PUBSUB_TOPIC
    

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

  • ‫JOB_NAME: שם ייחודי של המשימה לפי בחירתכם
  • ‫VERSION: הגרסה של התבנית שרוצים להשתמש בה

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

    • latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בדלי – gs://dataflow-templates/latest/
    • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית. אפשר למצוא את הגרסה הזו בתיקיית ההורה המתאימה עם התאריך בדלי – gs://dataflow-templates/
  • ‫REGION_NAME: האזור שבו רוצים לפרוס את עבודת Dataflow, לדוגמה: us-central1
  • ‫SPANNER_INSTANCE_ID: מזהה מכונת Spanner
  • ‫SPANNER_DATABASE: מסד נתונים של Spanner
  • ‫SPANNER_METADATA_INSTANCE_ID: מזהה מופע של מטא-נתונים של Spanner
  • ‫SPANNER_METADATA_DATABASE: מסד נתונים של מטא-נתונים ב-Spanner
  • ‫SPANNER_CHANGE_STREAM: Spanner change stream
  • ‫PUBSUB_TOPIC: נושא ה-Pub/Sub לפלט של סנכרון שינויים בזרמי נתונים

API

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

  POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
  {
    "launch_parameter": {
        "jobName": "JOB_NAME",
        "parameters": {
            "spannerInstanceId": "SPANNER_INSTANCE_ID",
            "spannerDatabase": "SPANNER_DATABASE",
            "spannerMetadataInstanceId": "SPANNER_METADATA_INSTANCE_ID",
            "spannerMetadataDatabase": "SPANNER_METADATA_DATABASE",
            "spannerChangeStreamName": "SPANNER_CHANGE_STREAM",
            "pubsubTopic": "PUBSUB_TOPIC"
        },
        "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Spanner_Change_Streams_to_PubSub",
    }
  }
  

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

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

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

    • latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בדלי – gs://dataflow-templates/latest/
    • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית. אפשר למצוא את הגרסה הזו בתיקיית ההורה המתאימה עם התאריך בדלי – gs://dataflow-templates/
  • ‫LOCATION: האזור שבו רוצים לפרוס את עבודת Dataflow, לדוגמה: us-central1
  • ‫SPANNER_INSTANCE_ID: מזהה מכונת Spanner
  • ‫SPANNER_DATABASE: מסד נתונים של Spanner
  • ‫SPANNER_METADATA_INSTANCE_ID: מזהה מופע של מטא-נתונים של Spanner
  • ‫SPANNER_METADATA_DATABASE: מסד נתונים של מטא-נתונים ב-Spanner
  • ‫SPANNER_CHANGE_STREAM: Spanner change stream
  • ‫PUBSUB_TOPIC: נושא ה-Pub/Sub לפלט של סנכרון שינויים בזרמי נתונים

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