פרסום אירועים בטבלה ב-BigQuery

פרסום אירועים בטבלה ב-BigQuery

מתקדם

במדריך למתחילים הזה נסביר איך לפרסם ולקבל הודעות על אירועים באמצעות יצירה של Eventarc Advanced bus והרשמה לפרויקט Google Cloud.

• אוטובוס פועל כנתב מרכזי שמקבל הודעות ממקורות אירועים או שספקים מפרסמים.

• הרשמה מנתבת הודעות שהאפיק מקבל ליעד אחד או יותר דרך פייפליין עיבוד.

במדריך למתחילים הזה:

1. יוצרים טבלה ב-BigQuery.

2. יוצרים אוטובוס מתקדם של Eventarc.

3. יוצרים הרשמה ל-Eventarc Advanced.

4. פרסום הודעת אירוע באוטובוס.

5. צופים בנתוני האירועים בטבלה ב-BigQuery.

אפשר להשלים את המדריך למתחילים הזה באמצעות ה-CLI של gcloud וכלי שורת הפקודה bq.

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

יכול להיות שהגבלות אבטחה שהוגדרו בארגון שלכם ימנעו מכם להשלים את השלבים הבאים. מידע לפתרון בעיות זמין במאמר פיתוח אפליקציות בסביבה Google Cloud מוגבלת.

נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

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

• יוצרים Google Cloud פרויקט:

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

• בוחרים את הפרויקט שיצרתם: Google Cloud

  gcloud config set project PROJECT_ID

  מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

אם אחד מהממשקים הבאים לא מופעל, מפעילים את BigQuery API ואת Eventarc API:

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

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

• יוצרים Google Cloud פרויקט:

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

• בוחרים את הפרויקט שיצרתם: Google Cloud

  gcloud config set project PROJECT_ID

  מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

אם אחד מהממשקים הבאים לא מופעל, מפעילים את BigQuery API ואת Eventarc API:

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

1. עדכון רכיבים של gcloud:

   gcloud components update

2. נכנסים באמצעות החשבון:

   gcloud auth login

3. מגדירים את משתנה ההגדרה שמשמש במדריך הזה להתחלה מהירה:

   REGION=REGION

   מחליפים את REGION במיקום נתמך של האוטובוס, לדוגמה us-central1.

4. אם אתם יוצרי הפרויקט, מוקצה לכם תפקיד הבעלים הבסיסי (roles/owner). כברירת מחדל, תפקיד ניהול הזהויות והרשאות הגישה (IAM) הזה כולל את ההרשאות שנדרשות לגישה מלאה לרוב המשאבים Google Cloud, ואפשר לדלג על השלב הזה.

   אם אתם לא יוצרי הפרויקט, צריך להעניק את ההרשאות הנדרשות בחשבון המשתמש המתאים בפרויקט. לדוגמה, חשבון משתמש יכול להיות חשבון Google (למשתמשי קצה) או חשבון שירות (לאפליקציות ולעומסי עבודה ממוחשבים).

   ההרשאות הנדרשות

   כדי לקבל את ההרשאות שדרושות לביצוע ההפעלה המהירה הזו, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

   • עריכה של נתוני BigQuery (roles/bigquery.dataEditor)
   • מפתח Eventarc (roles/eventarc.developer)
   • אדמין באוטובוס ההודעות של Eventarc (roles/eventarc.messageBusAdmin)
   • גישה לצפייה ביומנים (roles/logging.viewAccessor)
   • אדמין IAM בפרויקט (roles/resourcemanager.projectIamAdmin)
   • אדמין בחשבון שירות (roles/iam.serviceAccountAdmin)
   • משתמש בחשבון שירות (roles/iam.serviceAccountUser)
   • אדמין Service Usage (roles/serviceusage.serviceUsageAdmin)

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

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

5. כדי לתת ל-Eventarc Advanced את ההרשאות הנדרשות לעדכון מאפייני טבלה ב-BigQuery, צריך לבקש מהאדמין להקצות לחשבון שירות את תפקיד BigQuery Data Editor (roles/bigquery.dataEditor) ב-IAM בפרויקט Google Cloud :
   1. יוצרים חשבון שירות. לצורך בדיקה, תצרפו את חשבון השירות הזה לצינור מתקדם של Eventarc כדי לייצג את הזהות של הצינור.
      ‫

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      מחליפים את SERVICE_ACCOUNT_NAME בשם שרוצים לתת לחשבון השירות.
   2. מקצים לחשבון השירות את התפקיד roles/bigquery.dataEditor ב-IAM:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/bigquery.dataEditor

יצירת טבלה ב-BigQuery

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

לפני שיוצרים טבלה ב-BigQuery, צריך ליצור מערך נתונים שמשמש כמאגר ברמה העליונה של הטבלה, וסכימת טבלה.

1. כדי ליצור מערך נתונים חדש, משתמשים בפקודה bq mk עם הדגל --dataset.

   bq --location=$REGION mk --dataset DATASET_ID

   מחליפים את DATASET_ID בשם ייחודי של מערך הנתונים ב-BigQuery, למשל my_dataset.

2. בטרמינל, יוצרים קובץ חדש בשם my-schema.json.

3. מעתיקים ומדביקים את הסכימה הבאה בקובץ החדש, ואז שומרים את הקובץ.

   [
       {
           "name": "name",
           "type": "STRING",
           "mode": "REQUIRED"
       },
       {
           "name": "age",
           "type": "INTEGER",
           "mode": "NULLABLE"
       }
   ]

4. כדי ליצור טבלה, משתמשים בפקודה bq mk עם הדגל --table.

   bq mk --table PROJECT_ID:DATASET_ID.TABLE_ID my-schema.json

   מחליפים את TABLE_ID בשם ייחודי לטבלה ב-BigQuery, למשל my-table.

יצירת אפיק Eventarc Advanced

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

מידע נוסף זמין במאמר יצירת אפיק (bus) להעברת הודעות.

הערה: אפשר ליצור אוטובוס אחד לכל Google Cloud פרויקט לכל אזור נתמך.

יוצרים אוטובוס מתקדם של Eventarc בפרויקט באמצעות הפקודה gcloud eventarc message-buses create:

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

מחליפים את BUS_NAME במזהה של האוטובוס או בשם מלא, לדוגמה, my-bus.

יצירת הרשמה ל-Eventarc Advanced

ההרשמה קובעת אילו הודעות ינותבו ליעד, ומציינת את צינור הנתונים שמשמש להגדרת יעד להודעות האירועים. במקרה הזה, יעד היצוא הוא נקודת קצה של BigQuery API.

מידע נוסף מופיע במאמר בנושא יצירת רישום לקבלת אירועים.

הערה: יכול להיות שיצירת צינור עיבוד נתונים תימשך יותר מ-10 דקות.

כשמשתמשים ב-CLI של gcloud, קודם יוצרים צינור, ואז יוצרים הרשמה:

1. יוצרים פייפליין באמצעות הפקודה gcloud eventarc pipelines create:

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID/insertAll',http_endpoint_message_binding_template='{"headers": headers.merge({"content-type":"application/json"}), "body": {"rows":[{"json":message.data}]}}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   מחליפים את PIPELINE_NAME במזהה של צינור העיבוד או בשם מוגדר במלואו, לדוגמה, my-pipeline.

   שימו לב לנקודות הבאות:

   • המפתח http_endpoint_message_binding_template משנה את האירוע לפורמט שה-API מצפה לו. כשמגדירים קישור הודעה, צריך להגדיר פורמט קלט כדי לגשת למטען הייעודי (Payload).
   • המפתח oauth_token_authentication_service_account מציין את כתובת האימייל בחשבון שירות. האימייל הזה משמש ליצירת טוקן OAuth, שבדרך כלל צריך להשתמש בו רק כשקוראים לממשקי Google API שמתארחים ב-*.googleapis.com.
   • הדגל input-payload-format-json מציין שפורמט המטען הייעודי (payload) של צינור הנתונים הוא JSON. הודעות שלא תואמות לפורמט הזה נחשבות שגיאות קבועות.

2. כדי ליצור הרשמה, משתמשים בפקודה gcloud eventarc enrollments create:

   gcloud eventarc enrollments create ENROLLMENT_NAME \
       --cel-match=MATCH_EXPRESSION \
       --destination-pipeline=PIPELINE_NAME \
       --message-bus=BUS_NAME \
       --message-bus-project=PROJECT_ID \
       --location=$REGION

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

   • ‫ENROLLMENT_NAME: המזהה של ההרשמה או שם מוגדר במלואו, לדוגמה my-enrollment.

   • ‫MATCH_EXPRESSION: ביטוי ההתאמה להרשמה הזו באמצעות CEL – לדוגמה:

     "message.type == 'hello-world-type'"
     

פרסום הודעת אירוע באפיק

כדי לפרסם הודעה ישירות באפיק (bus), אפשר להשתמש בפקודה gcloud eventarc message-buses publish או לשלוח בקשה ל-Eventarc Publishing API בארכיטקטורת REST. מידע נוסף זמין במאמר בנושא פרסום אירועים ישירות.

ההודעה צריכה להיות בפורמט CloudEvents, שהוא מפרט לתיאור נתוני אירועים בצורה משותפת. רכיב data הוא מטען הייעודי (payload) של האירוע, והוא צריך להתאים בסופו של דבר לסכימה של הטבלה ב-BigQuery. אפשר להזין בשדה הזה כל JSON בפורמט תקין. מידע נוסף על מאפייני ההקשר של CloudEvents זמין במאמר בנושא פורמט אירועים.

הדוגמאות הבאות מראות איך לפרסם אירוע ישירות לאפיק (bus) מתקדם של Eventarc Advanced:

דוגמה 1

אפשר לפרסם אירוע באפיק באמצעות ה-CLI של gcloud ודגל --event-data ודגלים אחרים של מאפייני אירוע:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"name": "my-name", "age": "20"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

דוגמה 2

אפשר לפרסם אירוע באפיק כהודעת JSON באמצעות ה-CLI של gcloud והדגל --json-message:

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"name": "my-name", "age": "20"}}'

אחרי פרסום אירוע, אמורה להתקבל ההודעה 'האירוע פורסם בהצלחה'.

הצגת נתוני האירועים בטבלה ב-BigQuery

אחרי שמפרסמים אירוע באפיק Eventarc Advanced, אפשר להשתמש בפקודה bq query כדי לוודא שנוספה שורה חדשה לטבלה ב-BigQuery.

bq query \
    --use_legacy_sql=false \
    'SELECT
      *
    FROM
      `PROJECT_ID.DATASET_ID.TABLE_ID`
    LIMIT
      10;'

יצרתם בהצלחה Eventarc Advanced ואפיק (bus) ונרשמתם אליו, פרסמתם הודעת אירוע באפיק (bus) ואימתתם את התוצאה הצפויה באמצעות שליחת שאילתה בטבלה ב-BigQuery.

הסרת המשאבים

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

1. מחיקת טבלה ב-BigQuery.

2. מחיקת מערך נתונים ב-BigQuery.

3. מחיקת משאבים מתקדמים של Eventarc:

   1. מחיקת הרשמה.

   2. מחיקת צינור עיבוד נתונים.

   3. מחיקת אוטובוס

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

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המשימות במדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

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

כדי למחוק Google Cloud פרויקט:

gcloud projects delete PROJECT_ID

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

• פרסום אירועים ממקורות של Google
• פרסום אירועים ישירות
• שינוי אירועים שהתקבלו
• עיצוב אירועים שהתקבלו