פרסום וקבלת אירועים באמצעות יצירת אוטובוס והרשמה (מסוף)

פרסום וקבלת אירועים באמצעות יצירת אוטובוס והרשמה (מסוף)

מתקדם

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

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

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

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

1. יוצרים מאגר רגיל של Artifact Registry.

2. פריסת שירות לקבלת אירועים ב-Cloud Run.

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

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

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

6. צפייה בנתוני האירועים ביומנים של Cloud Run.

אפשר להשלים את רוב השלבים במדריך למתחילים הזה באמצעות מסוף Google Cloud . כדי לבצע את כל השלבים באמצעות ה-CLI של gcloud, אפשר לעיין במאמר פרסום וקבלת אירועים באמצעות יצירה של אפיק (bus) והרשמה (gcloud CLI).

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

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

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. כדי לבצע כמה מהשלבים במדריך למתחילים הזה, צריך להשתמש ב-CLI של gcloud:
   1. מגדירים את ה-CLI של gcloud באחת מסביבות הפיתוח הבאות:

      Cloud Shell

      כדי להשתמש בטרמינל אונליין שכבר מוגדר בו ה-CLI של gcloud, צריך להפעיל את Cloud Shell:

      בחלק התחתון של הדף הזה מתחיל סשן של Cloud Shell ומופיעה הודעה של שורת הפקודה. הסשן יופעל תוך כמה שניות.

      מעטפת מקומית

      כדי להשתמש בסביבת פיתוח מקומית:

      1. מתקינים את ה-CLI של gcloud.
      2. מפעילים את ה-CLI של gcloud.
   2. בוחרים את הפרויקט Google Cloud :

      gcloud config set project PROJECT_ID

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

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

      gcloud components update

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

      gcloud auth login

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

      REGION=us-central1

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

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

   שימו לב: כברירת מחדל, ההרשאות של Cloud Build כוללות הרשאות להעלאה ולהורדה של ארטיפקטים מ-Artifact Registry.

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

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

   • עריכה ב-Cloud Build (roles/cloudbuild.builds.editor)
   • אדמין ב-Cloud Run (roles/run.admin)
   • מפתח 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)

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

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

3. לצורך בדיקה, יוצרים חשבון שירות ומקצים לו את התפקידים שנדרשים כדי להשלים את המדריך הזה. משתמשים בחשבון השירות כדי ליצור ולפרוס את קובץ האימג' של הקונטיינר, ומצרפים אותו לצינור Eventarc Advanced כדי לייצג את הזהות של צינור עיבוד הנתונים.
   1. נכנסים לדף Service accounts במסוף Google Cloud .
      

      כניסה לדף Service accounts

   2. לוחצים על Create service account (יצירת חשבון שירות).
   3. מזינים שם לחשבון השירות.
   4. לוחצים על Create and continue.
   5. ברשימה Select a role (בחירת תפקיד), מסננים את התפקידים הבאים ובוחרים אותם:
      • Artifact Registry Writer: להעלאת פריטי מידע שנוצרו בתהליך פיתוח (Artifact) ב-Artifact Registry
      • ‫Logs Writer: כדי לכתוב יומנים ב-Cloud Logging
      • אדמין של אחסון: כדי לגשת לאובייקטים ב-Cloud Storage
      • ‫Cloud Run Invoker: כדי להתקשר אל Cloud Run
   6. לוחצים על סיום.

   שימו לב שאפשר להגדיר מי יכול לגשת לשירות Cloud Run באחת מהדרכים הבאות:

   • נותנים הרשאה לבחור חשבונות שירות או קבוצות כדי לאפשר גישה לשירות. כל הבקשות חייבות לכלול כותרת הרשאה של HTTP שמכילה אסימון OpenID Connect שנחתם על ידי Google עבור אחד מחשבונות השירות המורשים. כך מוגדרת הגישה במדריך למתחילים הזה.
   • צריך לתת הרשאה ל-allUsers כדי לאפשר גישה לכולם.

   מידע נוסף זמין במאמר בקרת גישה ל-Cloud Run.

יצירת מאגר רגיל ב-Artifact Registry

יוצרים מאגר רגיל ב-Artifact Registry כדי לאחסן את קובץ אימג' של קונטיינר.

1. נכנסים לדף Repositories במסוף Google Cloud .

   כניסה לדף Repositories

2. לוחצים על Create repository (יצירת מאגר).

3. מזינים שם – לדוגמה, my-repo.

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

4. במאגר Format, בוחרים באפשרות Docker.

5. ברשימה Region בוחרים באפשרות us-central1 (Iowa).

6. מאשרים את כל ברירות המחדל האחרות.

7. לוחצים על יצירה.

פריסת שירות לקבלת אירועים ב-Cloud Run

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

1. במסוף, משכפלים את מאגר GitHub:

   git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

2. עוברים לספרייה שמכילה את הקוד לדוגמה של Cloud Run:

   cd eventarc-samples/eventarc-advanced-quickstart/

3. יוצרים קובץ אימג' של קונטיינר Docker ומעבירים אותו בדחיפה למאגר:

   gcloud builds submit \
       --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
       --service-account=projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --default-buckets-behavior=regional-user-owned-bucket

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

   • ‫REPOSITORY: השם של מאגר Artifact Registry.
   • ‫SERVICE_ACCOUNT_NAME: השם של חשבון השירות שיצרתם קודם.

4. פורסים את קובץ האימג' של הקונטיינר ב-Cloud Run:

   1. נכנסים לדף Cloud Run במסוף Google Cloud .

      כניסה ל-Cloud Run

   2. לוחצים על פריסת מאגר > שירות.

   3. בוחרים באפשרות Deploy one revision from an existing container image (פריסת גרסה אחת מקובץ אימג' של קונטיינר קיים).

   4. בשדה כתובת ה-URL של קובץ האימג' של קונטיינר, לוחצים על בחירה כדי לציין את קובץ האימג' של קונטיינר ב-Artifact Registry שיצרתם קודם.

   5. אפשר גם לשנות את שם השירות, למשל ל-my-service.

   6. ברשימה Region בוחרים באפשרות us-central1 (Iowa).

   7. בקטע אימות, בוחרים באפשרות דרישת אימות.

      ההגדרה הזו קובעת שהשירות יאפשר רק הפעלות מאומתות.

   8. בקטע Ingress (תנועה נכנסת), בוחרים באפשרות All (הכול).

      כך כל הבקשות, כולל בקשות ישירות מהאינטרנט, מגיעות לכתובת ה-URL run.app. מידע נוסף זמין במאמר הגבלת תעבורת רשת נכנסת ב-Cloud Run.

   9. מאשרים את כל ברירות המחדל האחרות.

   10. לוחצים על יצירה וממתינים לסיום הפריסה.

יצירת אפיק Eventarc Advanced

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

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

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

1. במסוף Google Cloud , נכנסים לדף Eventarc >‏ Bus.

   מעבר אל Bus

2. לוחצים על Create bus.

3. בדף Create a bus, מבצעים את הפעולות הבאות:

   1. מזינים שם של אוטובוס – לדוגמה, my-bus.
   2. ברשימה Region בוחרים באפשרות us-central1 (Iowa).

4. מאשרים את כל ברירות המחדל האחרות.

5. לוחצים על יצירה.

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

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

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

כשמשתמשים במסוף Google Cloud , אפשר ליצור הרשמה וצינור (pipeline) בו-זמנית.

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

1. כדי ליצור הרשמה, במסוף Google Cloud נכנסים לדף Eventarc > Pipelines.

   מעבר אל Pipelines

2. לוחצים על Create pipeline.

3. בחלונית Pipeline details:

   1. מזינים שם של פייפליין – לדוגמה, my-pipeline.
   2. ברשימה Region בוחרים באפשרות us-central1 (Iowa). צריך ליצור את הפייפליין באותו אזור שבו נמצא האפיק (bus).
   3. מאשרים את כל ברירות המחדל האחרות.
   4. לוחצים על Continue.

4. בחלונית Enrollments:

   1. לוחצים על הוספת הרשמה.
   2. מזינים שם הרשמה – לדוגמה, my-enrollment.
   3. ברשימה Eventarc Advanced Bus, בוחרים את האוטובוס שיצרתם קודם.

   4. בשדה CEL expression (ביטוי CEL), כותבים ביטוי הערכה באמצעות CEL. לדוגמה:

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

   5. לוחצים על סיום.

   6. לוחצים על Continue.

   7. בחלונית תהליך בחירת הרשת לאירועים, לוחצים שוב על המשך.

5. בחלונית Destination (יעד):

   1. ברשימה סוג היעד, בוחרים באפשרות שירות Cloud Run (דרך HTTP) ואז בוחרים את שירות Cloud Run שיצרתם קודם.

   2. מסמנים את תיבת הסימון Enable authentication (הפעלת אימות).

      1. ברשימה Auth header, בוחרים באפשרות OIDC token.

      2. ברשימה Service account, בוחרים את חשבון השירות שיצרתם קודם ושדרכו יופעל שירות היעד. כתובת האימייל בחשבון השירות משמשת ליצירת אסימון OIDC.

6. לוחצים על יצירה.

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

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

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

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

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

לחלופין, אפשר לפרסם אירוע באוטובוס Eventarc Advanced כהודעת 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":
 {"key": "hello-world-data"}}'

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

צפייה בנתוני האירועים ביומני Cloud Run

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

1. נכנסים לדף Cloud Run במסוף Google Cloud .

   כניסה ל-Cloud Run

2. בדף שירותים, לוחצים על שם השירות.

3. לוחצים על הכרטיסייה Logs (יומנים).

4. אפשר לסנן את הרשומות ביומן ולהחזיר את הפלט. לדוגמה, אפשר לחפש את hello-world-data.

5. מחפשים רשומה ביומן שדומה לזו:

   2025-02-27 08:36:44.350 EST [2025-02-27 13:36:44,352] INFO in server: Body: b'{"key": "hello-world-data"}'
   

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

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

הסרת המשאבים

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

1. מחיקת מאגר Artifact Registry.

2. מחיקת שירות של Cloud Run

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

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

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

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

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

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

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

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

1. במסוף Google Cloud , נכנסים לדף Manage resources.

   כניסה לדף Manage resources

2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

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

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