פורמט CloudEvents – קישור לפרוטוקול HTTP

‫CloudEvents‏ (cloudevents.io) הוא מפרט לתיאור נתוני אירועים בצורה משותפת. המפרט נמצא ב-Cloud Native Computing Foundation‏ (CNCF) ומאורגן על ידי קבוצת העבודה Serverless של CNCF.

‫Eventarc מעביר אירועים למקבל האירועים בפורמט CloudEvents באמצעות בקשת HTTP.

כותרות של בקשת HTTP

שירותי היעד מקבלים אירועים מנתבי אירועים כבקשות HTTP POST בפורמט של CloudEvents גרסה 1.0 מפרט של שיוך פרוטוקול HTTP. כל בקשת HTTP מכילה כותרות וגוף ספציפיים לאירוע, ונשלחת לנתיב של כתובת ה-URL הבסיסית (/) של השירות.

בנוסף לכותרות HTTP אחרות, לכל האירועים יש את כותרות ה-HTTP הבאות של CloudEvents:

כותרת תיאור דוגמה
ce-id מזהה ייחודי של האירוע 1096434104173400
ce-source לזיהוי המקור של האירוע //pubsub.googleapis.com/projects/my-project/topics/my-topic
ce-specversion גרסת המפרט של CloudEvents שמשמשת לאירוע הזה 1.0
ce-type סוג נתוני האירועים google.cloud.pubsub.topic.v1.messagePublished
ce-time שעת יצירת האירוע, בפורמט RFC 3339 (אופציונלי) 2020-12-20T13:37:33.647Z

פורמט ה-payload של HTTP

יומני ביקורת של Cloud

אירועים מהסוג google.cloud.audit.log.v1.written הם בפורמט הבא:

כותרות

ce-specversion: 1.0
ce-type: google.cloud.audit.log.v1.written
ce-source: //SERVICE_NAME/projects/PROJECT_ID
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH
  • ‫SERVICE_NAME: ה-URI של Google API לשירות שיוצר את האירוע. לדוגמה, bigquery.googleapis.com לאירועים מ-BigQuery.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: נוצר על ידי המערכת.

גוף

המטען הייעודי הוא אובייקט JSON עם פרטים על האירוע ביומני הביקורת של Cloud. ב-protoPayload אפשר למצוא את הערכים resourceName,‏ serviceName ו-methodName. מידע נוסף זמין במאמר בנושא קביעת מסנני אירועים ליומני ביקורת של Cloud.

Pub/Sub

אירועים מהסוג google.cloud.pubsub.topic.v1.messagePublished מופיעים בפורמט הבא:

כותרות

ce-specversion: 1.0
ce-type: google.cloud.pubsub.topic.v1.messagePublished
ce-source: //pubsub.googleapis.com/TOPIC
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH
  • ‫TOPIC: נושא ה-Pub/Sub שהאירוע פורסם בו.
  • ‫MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: נוצר על ידי המערכת.

גוף

המטען הייעודי הוא הודעת דחיפה של Pub/Sub. בשדה data אפשר למצוא את ההודעה כמחרוזת בקידוד Base64. דוגמה מופיעה במאמר הזה בקטע אירועים נפוצים.

מאגר קוד פתוח

המבנה של גוף ה-HTTP לכל האירועים זמין במאגר CloudEvents ב-GitHub.

המאגר מכיל את הרכיבים הבאים שיעזרו לכם להבין את נתוני CloudEvents ולהשתמש בהם בשפת התכנות שלכם:

  • Google Protocol Buffers for CloudEvents data payloads
  • סכימות JSON שנוצרו
  • קטלוג ציבורי של סכימות JSON

המאמר כולל גם קישורים לספריות לקוח.

אירועים נפוצים

‫Protocol Buffers (או protobufs) מייצגים את הנתונים באירועים שנוצרים על ידי Eventarc. ‫Protocol Buffers ל-CloudEvents מסופקים כסכימות שניתנות לקריאה על ידי מכונה, ומאפשרים ליצור ספריות של סוגי נתונים ולהשתמש באירועים בקלות רבה יותר.

יש שתי הודעות protobuf שרלוונטיות לכל סוג נתון של CloudEvent:

  • ההודעה envelope שמייצגת את CloudEvent המלא, כולל מאפייני הרחבה, לדוגמה, AuditLogWrittenEvent.
  • הודעת הנתונים, לדוגמה, LogEntryData או StorageObjectData.
הרבה סוגים של CloudEvent יכולים להשתמש באותה הודעת נתונים. לדוגמה, כל אירוע שמשויך לאובייקט ב-Cloud Storage משתמש ב-StorageObjectData כהודעת הנתונים. כל הודעה במעטפה מציינת את סוג CloudEvent שאליו היא משויכת באמצעות הערת proto. מידע נוסף זמין במאמר הקשר בין הודעות protobuf לסוגי CloudEvent.

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

יומני ביקורת של Cloud

קובצי Protogoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
הודעה במעטפהgoogle.events.cloud.audit.v1.AuditLogWrittenEvent
הודעת נתוניםgoogle.events.cloud.audit.v1.LogEntryData
סוג האירוע
(כשנכתבת רשומה ביומן הביקורת)		 google.cloud.audit.log.v1.written
תוספים לאירועים
  • serviceName
  • methodName
  • resourceName
רשימת סוגי האירועים באמצעות יומני הביקורת של Cloud
דוגמאות יומן ביקורת של Pub/Sub
יומן ביקורת של BigQuery
מידע נוסף יצירת טריגר Eventarc לאירוע ביומני ביקורת של Cloud
קביעת מסנני אירועים ליומני ביקורת של Cloud
Google Cloud שירותים עם יומני ביקורת

Cloud Storage

קובצי Proto google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
הודעות במעטפהgoogle.events.cloud.storage.v1.ObjectFinalizedEvent
google.events.cloud.storage.v1.ObjectArchivedEvent
google.events.cloud.storage.v1.ObjectDeletedEvent
google.events.cloud.storage.v1.ObjectMetadataUpdatedEvent
הודעת נתוניםgoogle.events.cloud.storage.v1.StorageObjectData
משאב Objects
סוגי אירועים
 רשימת סוגי האירועים הישירים
דוגמאות פשוט
מורכב
מידע נוסף יצירת טריגר Eventarc לאירוע Cloud Storage
קבלת אירועים מ-Cloud Storage בשירות Cloud Run

Firestore

קובצי Proto google/events/cloud/firestore/v1/events.proto
google/events/cloud/firestore/v1/data.proto
הודעות במעטפהgoogle.events.cloud.firestore.v1.DocumentCreatedEvent
google.events.cloud.firestore.v1.DocumentUpdatedEvent
google.events.cloud.firestore.v1.DocumentDeletedEvent
google.events.cloud.firestore.v1.DocumentWrittenEvent
הודעת נתוניםgoogle.events.cloud.firestore.v1.DocumentEventData
משאב Document
סוגי אירועים רשימת סוגי האירועים הישירים
דוגמאות פשוט
מורכב
מידע נוסף יצירת טריגר Eventarc לאירוע Firestore
יצירת ארכיטקטורות מבוססות-אירועים באמצעות Eventarc ו-Firestore
הרחבה באמצעות פונקציות Cloud Run לטיפול באירועים שמופעלים על ידי שינויים ב-Firestore

Pub/Sub

קובצי Proto google/events/cloud/pubsub/v1/events.proto
google/events/cloud/pubsub/v1/data.proto
הודעה במעטפהgoogle.events.cloud.pubsub.v1.MessagePublishedEvent
הודעת נתוניםgoogle.events.cloud.pubsub.v1.MessagePublishedData
משאב PubsubMessage
סוג האירוע
(כשמתפרסמת הודעה ב-Pub/Sub)		 google.cloud.pubsub.topic.v1.messagePublished
דוגמה טקסט
מידע נוסף קבלת אירועים בשירות Cloud Run באמצעות הודעות Pub/Sub
הפעלת תהליך עבודה באמצעות הודעות Pub/Sub

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

מידע נוסף על ניתוב אירועים