ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-602] CloudEvents ​

概述 ​

本規範旨在指導 RESTful API 事件的設計和實現，以確保與 CNCF CloudEvent 標準的兼容性。CNCF CloudEvent 是一個輕量級規範，用於描述事件數據，以促進事件驅動系統中的互操作性。本規範中使用的"應該"（SHOULD）表示強烈建議，但在某些情況下可能允許例外。

上下文屬性 ​

CloudEvents 定義了一組用於描述事件的元數據，稱為上下文屬性。這些屬性分為兩類：

  • 核心屬性
  • 擴展屬性

核心屬性 vs 擴展屬性 ​

角色 ​

  • 事件生產者(Event Producer)
  • 事件消費者(Event Consumer)
  • 事件路由器(Event Router)

指導原則 ​

  • 應該(SHOULD)遵循 CloudEvent 結構：所有 RESTful API 事件都應遵循 CNCF CloudEvent 標準結構，包括核心屬性和適當的擴展屬性。
  • 必須(MUST)遵循 CloudEvents 類型約定
  • 必須(MUST)指定媒體類型（如果可用）：參見 CloudEvents 媒體類型規範
  • 應該(SHOULD)遵循 CloudEvents 源約定
  • CloudEvents 屬性原則：

    • 必須(MUST)將 specversion 指定為 1.0

    • 必須(MUST)提供唯一 ID：確保 ID 在整個系統中是唯一的。

    • 必須(MUST)提供時間：指定發生時間或當前時間（必須在整個系統中保持一致）。提供時，使用 RFC3339 日期格式。參見 CloudEvents 時間規範

    • 應該(SHOULD)提供主題(subject)：包括關於事件的主題。

      :::tip
💡 原始 CloudEvents 規範中對 `subject` 沒有嚴格的規則。它可以是非空字符串。請詳細記錄你會在主題中放置什麼內容。
:::

示例 ​

示例 1：基本 CloudEvent ​

http
Content-Type: application/cloudevents+json

{
  "specversion": "1.0",
  "type": "com.vivotek.user.created",
  "source": "/mycontext",
  "id": "A234-1234-1234",
  "time": "2020-08-14T14:48:09Z",
  "datacontenttype": "application/json",
  "data": {
    "object": {
      "id": "123",
      "name": "Sample Object"
    }
  }
}

這個示例代表一個基本的 CloudEvent，表示創建了一個對象。它包括標準屬性，如 specversion、type、source、id、time、datacontenttype 和 data。

示例 2：帶擴展的 CloudEvent ​

json
{
  "specversion": "1.0",
  "type": "com.example.file.uploaded",
  "source": "/mycontext",
  "id": "B234-1234-1234",
  "time": "2020-08-14T14:48:09Z",
  "subject": "user/123/file/456",
  "datacontenttype": "application/json",
  "data": {
    "file": {
      "id": "456",
      "name": "example.txt",
      "size": "1024"
    }
  },
  "traceparent": "00-abcd1234abcd1234abcd1234abcd1234-01",
  "tracestate": "congo=congospecificinfo"
}

這個示例通過包含額外的屬性如 traceparent 和 tracestate 擴展了基本 CloudEvent。這些提供了支持可觀察性的跟踪資訊。

示例 3：通過 HTTP 傳輸 CloudEvent ​

http
POST /events HTTP/1.1
Host: example.com
Content-Type: application/cloudevents+json
Content-Length: 400

{
  "specversion": "1.0",
  "type": "com.example.user.updated",
  "source": "/mycontext",
  "id": "C234-1234-1234",
  "time": "2020-08-14T14:48:09Z",
  "datacontenttype": "application/json",
  "data": {
    "user": {
      "id": "123",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  }
}

在這個示例中，CloudEvent 通過 HTTP 使用 POST 方法傳輸。請求頭指定 Content-Type: application/cloudevents+json，請求體包含事件數據。

參考資料 ​

設計參考 ​