יצירת אוטובוס להעברת הודעות

מתקדם

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

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

התפקידים הנדרשים

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

• כדי לקבל את ההרשאה שנדרשת ליצירת אוטובוס, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM Eventarc Admin (roles/eventarc.admin) או Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin) בפרויקט האוטובוס. התפקידים המוגדרים מראש האלה כוללים את ההרשאה eventarc.messageBuses.create, שנדרשת כדי ליצור אוטובוס.
• כדי לקבל את ההרשאה שנדרשת לשימוש באפיק, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM ‏Eventarc Message Bus User‏ (roles/eventarc.messageBusUser) בפרויקט האפיק. התפקיד המוגדר מראש הזה כולל את ההרשאה eventarc.buses.use, שנדרשת כדי להשתמש באוטובוס.
• כדי ליצור צינור ורישום, נדרשות הרשאות נוספות. מידע נוסף זמין במאמר בנושא התפקידים הנדרשים כשיוצרים הרשמה.

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

יצירת אוטובוס

אפשר ליצור אוטובוס בדרכים הבאות:

• במסוף Google Cloud
• באמצעות Google Cloud CLI בטרמינל או ב-Cloud Shell
• שליחת בקשה ל-Eventarc API

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

המסוף

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

   מעבר אל Bus

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

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

   1. מזינים שם של אוטובוס. זהו המזהה של האוטובוס.
   2. אופציונלי: מזינים שם מוצג של האוטובוס שיוצג בדף פרטי האוטובוס.
   3. ברשימה Region, בוחרים אזור נתמך לפריסת האוטובוס.
   4. ברשימה Log severity (חומרת היומן), בוחרים את רמת החומרה המינימלית של האירועים שמתוארים ברשומות היומן. ברירת המחדל היא ללא. מידע נוסף זמין במאמר LogSeverity.
   5. בקטע הצפנה, מאשרים את ברירת המחדל Google-managed encryption key או בוחרים באפשרות מפתח Cloud KMS. מידע נוסף מופיע במאמר בנושא שימוש במפתחות הצפנה בניהול הלקוח (CMEK).

   6. אם בוחרים באפשרות מפתח Cloud KMS, מבצעים את הפעולות הבאות:

      1. ברשימה Key type (סוג המפתח), בוחרים שיטה לניהול המפתחות.

         אתם יכולים לנהל את המפתחות באופן ידני או להשתמש ב-Autokey, שמאפשר לכם ליצור מחזיקי מפתחות ומפתחות לפי דרישה. אם האפשרות Cloud KMS with Autokey מושבתת, היא עדיין לא משולבת עם סוג המשאב הנוכחי.

      2. בתפריט Select a Cloud KMS key, בוחרים מפתח.

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

      3. אופציונלי: כדי להזין ידנית את שם המשאב של המפתח, ברשימה Select a customer-managed key (בחירת מפתח בניהול הלקוח), לוחצים על Enter key manually (הזנת מפתח באופן ידני) ומזינים את שם המפתח בפורמט שצוין.

      4. אם מתבקשים, מקצים את התפקיד cloudkms.cryptoKeyEncrypterDecrypter לסוכן השירות של Eventarc.

   7. אופציונלי: כדי להוסיף מקור הודעה, לוחצים על הוספת מקור.

      1. בחלונית הוספת מקור הודעה, בשדה של ספק ההודעות של Google API, מאשרים את ברירת המחדל google-api-source או מזינים שם מקור אחר.

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

         כך מתאפשר איסוף אוטומטי של אירועים שמגיעים ישירות ממקורות של Google.

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

   8. אופציונלי: כדי להוסיף תוויות, לוחצים על הוספת תווית. תוויות הן צמדי מפתח/ערך שעוזרים לכם לארגן אתGoogle Cloud המשאבים. מידע נוסף זמין במאמר מהן תוויות?

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

gcloud

1. פותחים טרמינל.

2. יוצרים אוטובוס באמצעות הפקודה gcloud eventarc message-buses create.

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

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

   • ‫BUS_NAME: המזהה או המזהה המלא של האוטובוס

   • ‫REGION: מיקום נתמך לאוטובוס

     אפשר גם להגדיר את מאפיין המיקום של Google Cloud CLI:

     gcloud config set eventarc/location REGION
     

   אופציונלי: אפשר גם להשתמש בדגלים הבאים:

   • ‫--async כדי לחזור מהפקודה באופן מיידי, בלי לחכות שהפעולה תסתיים.
   • ‫--crypto-key כדי לציין את השם המלא של מפתח הצפנה בניהול הלקוח. אם לא מציינים מפתח,נעשה שימוש ב- Google-owned and managed keys .
   • ‫--logging-config כדי להגדיר את מידת החומרה המינימלית לאירועים שמתוארים ברשומות ביומן. חייב להיות אחד מהערכים הבאים: NONE,‏ DEBUG, ‏ INFO, ‏ NOTICE, ‏ WARNING, ‏ ERROR, ‏ CRITICAL, ‏ ALERT,‏ EMERGENCY. ערך ברירת המחדל הוא NONE. מידע נוסף זמין במאמר LogSeverity.

‫API בארכיטקטורת REST

כדי ליצור אוטובוס, משתמשים ב-method‏ projects.locations.messageBuses.create.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫BUS_NAME: השם המוצג של האוטובוס, לדוגמה my_bus.
• ‫LABEL_KEY ו-LABEL_VALUE: אופציונליים. מיפוי של צמדי מפתח/ערך של תוויות שעוזרים לארגן את Google Cloud המשאבים שלכם. מידע נוסף זמין במאמר מהן תוויות?
• ‫ANNOTATION_KEY ו-ANNOTATION_VALUE: אופציונליים. ‫map של צמדי מפתח/ערך של הערות בטקסט חופשי. אפשר להשתמש בהם כדי לצרף מידע שרירותי שמשויך למשאב. מידע נוסף זמין במאמר בנושא הערות.
• ‫ENCRYPT_KEY: אופציונלי. מפתח Cloud KMS שאוטובוס הנתונים צריך להשתמש בו להצפנת נתונים בפורמט projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME. מידע נוסף מופיע במאמר בנושא שימוש במפתחות הצפנה בניהול הלקוח.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud.
• ‫LOCATION: האזור שבו רוצים ליצור את האוטובוס, לדוגמה us-central1.
• ‫LOG_SEVERITY: אופציונלי. רמת החומרה המינימלית של האירוע שמתואר ברשומה ביומן. אחת מהאפשרויות הבאות: NONE, ‏DEBUG, INFO, ‏NOTICE, ‏WARNING, ‏ERROR, CRITICAL, ‏ALERT, ‏EMERGENCY. ערך ברירת המחדל הוא NONE. מידע נוסף זמין במאמר LogSeverity.

תוכן בקשת JSON:

{
  "display_name": "BUS_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

cat > request.json << 'EOF'
{
  "display_name": "BUS_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}
EOF

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses?messageBusId=BUS_NAME"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

@'
{
  "display_name": "BUS_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}
'@  | Out-File -FilePath request.json -Encoding utf8

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses?messageBusId=BUS_NAME" | Select-Object -Expand Content

‫APIs Explorer (דפדפן)

מעתיקים את גוף הבקשה ופותחים את דף העזר של השיטה. החלונית של API Explorer תיפתח בצד שמאל של הדף. אפשר להשתמש בכלי הזה כדי לשלוח בקשות. מדביקים את גוף הבקשה בכלי הזה, ממלאים את כל שדות החובה ולוחצים על Execute.

אם הפעולה בוצעה בהצלחה, גוף התגובה יכיל מופע חדש של Operation:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.eventarc.v1.OperationMetadata",
    "createTime": "2024-01-25T17:17:45.782370139Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

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

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

• במסוף Google Cloud
• שימוש ב-CLI של gcloud בטרמינל או ב-Cloud Shell
• שליחת בקשה ל-Eventarc API

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

המסוף

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

   מעבר אל Bus

   נפתח הדף Bus details.

2. לוחצים על מחיקה.

3. כשמופיעה בקשה למחוק את האוטובוס, מסמנים את תיבת הסימון Do you want to proceed? (האם ברצונך להמשיך?) כדי לאשר שכל מקורות ההודעות שהוגדרו לשימוש באוטובוס לא יוכלו יותר להשתמש בו.

4. כדי לאשר את המחיקה, מזינים Delete.

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

gcloud

1. פותחים טרמינל.

2. כדי למחוק אוטובוס, משתמשים בפקודה gcloud eventarc message-buses delete.

   gcloud eventarc message-buses delete BUS_NAME \
       --location=REGION
   

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

   • ‫BUS_NAME: המזהה או המזהה המלא של האוטובוס
   • ‫REGION: המיקום הנתמך של האוטובוס

‫API בארכיטקטורת REST

כדי למחוק אוטובוס, משתמשים בשיטה projects.locations.messageBuses.delete.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud.
• ‫LOCATION: האזור שבו נוצר האוטובוס. לדוגמה, us-central1.
• ‫BUS_NAME: השם של האפיק (bus) שרוצים למחוק.

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME" | Select-Object -Expand Content

‫APIs Explorer (דפדפן)

פותחים את דף העזר של ה-method. החלונית של API Explorer תיפתח בצד שמאל של הדף. אפשר להשתמש בכלי הזה כדי לשלוח בקשות. ממלאים את כל שדות החובה ולוחצים על Execute.

אם הפעולה בוצעה בהצלחה, גוף התגובה יכיל מופע חדש של Operation:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.eventarc.v1.OperationMetadata",
    "createTime": "2024-01-25T17:17:45.782370139Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

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

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