CloudEvents – פורמט אירוע JSON

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

‫Eventarc מעביר אירועים למקבל האירועים בפורמט CloudEvents באמצעות בקשת HTTP. יעד היעד – לדוגמה, שירות Workflows – ממיר את האירוע לאובייקט JSON (בהתאם למפרט CloudEvents) ומעביר את האירוע להרצת זרימת העבודה כארגומנט של זמן הריצה של זרימת העבודה.

פורמט מטען ייעודי (payload) של JSON

שירות היעד מקבל אירועים מנתבי אירועים ומעצב את האירועים בפורמט JSON Event Format for CloudEvents version 1.0.1 עם מאפייני CloudEvents הבאים:

מאפיין תיאור דוגמה
נתונים המטען הייעודי של נתוני האירוע. 
{
  "subscription": "projects/my-project/subscriptions/my-sub",
  "message": {
    "attributes": {
      "attr1":"attr1-value"
    },
    "data": "aGVsbG8gd29ybGQ=",
    "messageId": "2070443601311540",
    "publishTime":"2021-02-26T19:13:55.749Z"
  }
}
datacontenttype סוג הנתונים שהועברו application/json
id המזהה הייחודי של האירוע 2070443601311540
מקור המקור של האירוע //pubsub.googleapis.com/projects/my-project/topics/my-topic
specversion גרסת המפרט של CloudEvents שמשמשת לאירוע הזה 1.0
סוג סוג נתוני האירועים google.cloud.pubsub.topic.v1.messagePublished
פעם שעת יצירת האירוע, בפורמט RFC 3339 (אופציונלי) 2020-12-20T13:37:33.647Z

בהתאם לסוג האירוע, פורמט המטען הייעודי (Payload) הוא כדלקמן:

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

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

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

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json; charset=utf-8",
  "id": "MESSAGE_ID",
  "source": "//cloudaudit.googleapis.com/projects/PROJECT_ID/logs/data_access",
  "specversion": "1.0",
  "type": "google.cloud.audit.log.v1.written",
  "time": "EVENT_GENERATION_TIME",
  "dataschema": "https://googleapis.github.io/google-cloudevents/jsonschema/google/events/cloud/audit/v1/LogEntryData.json",
  "methodName": "jobservice.jobcompleted",
  "resourceName": "projects/my-project/jobs/bqjob_r3ac45813612fa2d6_0000017d591922c9_1",
  "serviceName": "bigquery.googleapis.com",
  "subject": "bigquery.googleapis.com/projects/my-project/jobs/bqjob_r3ac45813612fa2d6_0000017d591922c9_1"
}
  • ‫EVENT_DATA: תוכן ההודעה המפוענח בפורמט JSON. מידע נוסף מופיע בקטע אירועים נפוצים.
  • MESSAGE_ID, EVENT_GENERATION_TIME: נוצר על ידי המערכת.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫dataschema, methodName, resourceName, serviceName, subject: מאפיינים שספציפיים לסוג האירוע.

Cloud Storage

הארגומנטים של זמן הריצה הם שינויים ב-Cloud Storage. בשדה data אפשר לראות את השינוי בקטגוריה של Cloud Storage. במסמך הזה, ראו את הדוגמה של אירועים נפוצים.

אירועים מהסוג google.cloud.storage.object.v1.finalized מופיעים בפורמט הבא:

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json",
  "id": "MESSAGE_ID",
  "source": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME",
  "specversion": "1.0",
  "type": "google.cloud.storage.object.v1.finalized",
  "time": "EVENT_GENERATION_TIME",
  "subject": "objects/my-file.txt"
}
  • ‫EVENT_DATA: תוכן ההודעה המפוענח בפורמט JSON. מידע נוסף מופיע בקטע אירועים נפוצים.
  • MESSAGE_ID, EVENT_GENERATION_TIME: נוצר על ידי המערכת.
  • ‫BUCKET_NAME: השם של קטגוריית Cloud Storage שמתעדכנת.
  • ‫subject: מאפיין שספציפי לסוג האירוע.

Pub/Sub

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

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

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json; charset=utf-8",
  "id": "MESSAGE_ID",
  "source": "//pubsub.googleapis.com/TOPIC_NAME",
  "specversion": "1.0",
  "type": "google.cloud.pubsub.topic.v1.messagePublished",
  "time": "EVENT_GENERATION_TIME"
}
  • ‫EVENT_DATA: תוכן ההודעה המפוענח בפורמט JSON. מידע נוסף מופיע בקטע אירועים נפוצים.
  • MESSAGE_ID, EVENT_GENERATION_TIME: נוצר על ידי המערכת.
  • ‫TOPIC_NAME: שם נושא ה-Pub/Sub שאליו פורסם האירוע.

מאגר קוד פתוח

המבנה של גוף ה-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