פרסום אירועים במשימה ב-Cloud Run

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

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

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

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

  1. פריסת משימה של Cloud Run מקוד מקור.

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

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

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

  5. מוודאים שהג'וב של Cloud Run בוצע בהצלחה.

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

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

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

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

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

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

    gcloud init
  5. יוצרים או בוחרים 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 .

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

  7. מפעילים את ממשקי ה-API של Artifact Registry, ‏ Cloud Build, ‏ Cloud Run ו-Eventarc, אם הם עדיין לא מופעלים:

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

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

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 
  8. התקינו את ה-CLI של Google Cloud.

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

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

    gcloud init
  11. יוצרים או בוחרים 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 .

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

  13. מפעילים את ממשקי ה-API של Artifact Registry, ‏ Cloud Build, ‏ Cloud Run ו-Eventarc, אם הם עדיין לא מופעלים:

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

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

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 
  14. עדכון רכיבים של gcloud:
    gcloud components update
  15. נכנסים באמצעות החשבון:
    gcloud auth login
  16. מגדירים את משתנה ההגדרה שמשמש במדריך הזה להתחלה מהירה:
    REGION=REGION

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

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

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

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

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

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

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

  18. כדי לתת ל-Eventarc Advanced את ההרשאות שנדרשות להפעלת משימה ב-Cloud Run, צריך לבקש מהאדמין להקצות לחשבון שירות בפרויקטGoogle Cloud את תפקיד ה-IAM‏ Cloud Run Invoker‏ (roles/run.invoker).
    1. יוצרים חשבון שירות. לצורך בדיקה, תצרפו את חשבון השירות הזה לצינור מתקדם של Eventarc כדי לייצג את הזהות של הצינור.
      ‫
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
      מחליפים את SERVICE_ACCOUNT_NAME בשם שרוצים לתת לחשבון השירות.
    2. מקצים לחשבון השירות את התפקיד roles/run.invoker ב-IAM:
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/run.invoker

פריסת משימת Cloud Run מקוד מקור

פריסה של משימת Cloud Run כיעד של האירוע. שלא כמו שירות Cloud Run, שמקשיב לבקשות ומטפל בהן, משימת Cloud Run מפעילה רק את המשימות שלה ויוצאת כשהיא מסיימת. העבודה לא מאזינה לבקשות ולא משרתת אותן.

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

יוצרים משימה מקוד מקור של Python באמצעות הפקודה gcloud run jobs deploy. הקוד שלכם נארז אוטומטית בקובץ אימג' של קונטיינר, מועלה ל-Artifact Registry ואז נפרס ב-Cloud Run.

  1. יוצרים ספרייה בשם jobs ועוברים אליה:

    mkdir jobs
    cd jobs
    
  2. יוצרים קובץ main.py ומעתיקים אליו את קוד לדוגמה הבא:

    import os
    
    TASK_INDEX = os.getenv("CLOUD_RUN_TASK_INDEX", 0)
    
    def main():
        """
        This job prints "Hello world"
        """
        print(f"Starting task #{TASK_INDEX}...")
        print("Hello world")
        print(f"Completed task #{TASK_INDEX}.")
    
    # Start script
    if __name__ == "__main__":
        main()
    
  3. יוצרים קובץ טקסט בשם Procfile בלי סיומת קובץ ומעתיקים אליו את הטקסט הבא:

    web: python3 main.py
    
  4. פורסים את העבודה:

    gcloud run jobs deploy JOB_NAME \
        --source . \
        --tasks 1 \
        --region=$REGION

    מחליפים את JOB_NAME בשם ייחודי למשימת Cloud Run, למשל my-job.

יצירת אפיק Eventarc Advanced

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

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

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

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

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

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

ההרשמה קובעת אילו הודעות ינותבו ליעד. הוא גם מציין את צינור עיבוד הנתונים שמשמש להגדרת היעד של הודעות האירועים. במקרה הזה, יעד הטירגוט הוא משימת Cloud Run.

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

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

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

    gcloud eventarc pipelines create PIPELINE_NAME \
        --destinations=http_endpoint_uri='JOB_URI',http_endpoint_message_binding_template='{"body": ""}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --input-payload-format-json= \
        --location=$REGION

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

    • ‫PIPELINE_NAME: המזהה של צינור העיבוד או שם מלא, לדוגמה, my-pipeline.
    • ‫JOB_URI: ה-URI של משימת Cloud Run בפורמט הבא:

      https://REGION-run.googleapis.com/apis/run.googleapis.com/v1/namespaces/PROJECT_NUMBER/jobs/JOB_NAME:run

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

      gcloud projects describe PROJECT_ID --format='value(projectNumber)'

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

    • המפתח http_endpoint_message_binding_template משנה את האירוע לפורמט שצפוי על ידי Cloud Run Admin API. כשמגדירים message binding, צריך להגדיר פורמט קלט כדי לגשת למטען הייעודי (payload). לדוגמה: {"body": ""}.
    • המפתח oauth_token_authentication_service_account מציין את כתובת האימייל בחשבון שירות. כתובת האימייל הזו משמשת ליצירת טוקן OAuth, שבדרך כלל משמש רק כשקוראים לממשקי API של Google שמתארחים ב-*.googleapis.com.
  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) של האירוע. אפשר להזין בשדה הזה כל JSON בפורמט תקין. מידע נוסף על מאפייני ההקשר של CloudEvents זמין במאמר בנושא פורמט אירועים.

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

דוגמה 1

כדי לפרסם אירוע באפיק באמצעות ה-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

דוגמה 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":
 {"key": "hello-world-data"}}'

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

אישור שהג'וב ב-Cloud Run בוצע בהצלחה

אחרי שמפרסמים אירוע באוטובוס Eventarc Advanced, בודקים את היומנים של משימת Cloud Run כדי לוודא שמשימת Cloud Run בוצעה בהצלחה ושנכתב "Hello world". יכול להיות שיעברו כמה דקות עד שהעבודה תופעל ותסתיים.

  1. מסננים את הרשומות ביומן ומחזירים את הפלט באמצעות הפקודה gcloud logging read:

    gcloud logging read 'textPayload: "Hello world"'
    
  2. מחפשים רשומה ביומן שדומה לזו:

    insertId: 693c8dd0000cb2976d7966b8
    ...
    labels:
        job_name: JOB_NAME
        location: REGION
        project_id: PROJECT_ID
    type: cloud_run_job
    textPayload: Hello world
    timestamp: '2025-12-12T21:49:04.832151Z'
    
  3. אפשר גם לוודא שהמשימה של Cloud Run בוצעה בהצלחה באמצעות הפקודה gcloud run jobs describe:

    gcloud run jobs describe JOB_NAME \
        --region=$REGION
    

    הפלט שמתקבל אמור להיראות כך:

    ✔ Job JOB_NAME in region us-central1
    Executed 1 time
    ...
    

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

הסרת המשאבים

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

  1. מחיקת משימה ב-Cloud Run

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

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

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

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

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

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

gcloud projects delete PROJECT_ID

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