使用 REST 生產者 API

Event Streams 提供 REST API 以協助您將現有系統連接至 Event Streams Kafka 叢集。 透過使用 API，您可以將 Event Streams 與支援 RESTful API 的任何系統整合。

REST 生產者 API 僅作為 Event Streams 標準和企業方案的一部分提供。

REST 生產者 API 是可調整的 REST 介面，用於透過安全 HTTP 端點向 Event Streams 產生訊息。 將事件資料傳送至 Event Streams，使用 Kafka 技術來處理資料資訊來源，並利用 Event Streams 特性來管理資料。

使用 API 將現有系統連接至 Event Streams。 從系統建立針對 Event Streams 的產生要求，包括指定訊息索引鍵、標頭，以及您想要將訊息寫入的主題。

存取 REST 生產者 API

您必須擷取所需的 URL 及認證詳細資料，才能從服務認證物件或服務實例的服務金鑰連接至 API。 如需建立這些物件的相關資訊，請參閱 連接至 Event Streams。

API 端點的 URL 在 kafka_http_url 內容中提供。

鑑別

支援的鑑別機制是使用載送記號。 若要使用 IBM Cloud CLI 取得記號，請先登入 IBM Cloud，然後執行下列指令:

ibmcloud iam oauth-tokens

將此記號放在 HTTP 要求的 Authorization 標頭中，格式為 Bearer<token>。 同時支援 API 金鑰和 JWT 記號。

使用 REST 生產者 API 產生訊息

使用生產者 API 的 v2 端點，將 text、binary、JSON 或 avro 類型的訊息傳送至主題。 透過 v2 端點，您可以透過指定 avro 資料類型的綱目來使用 Event Streams 綱目登錄。

下列程式碼顯示使用 curl 傳送 text 類型之訊息的範例:

curl -v -X POST \
-H "Authorization: Bearer $token" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
  "headers": [
    {
      "name": "colour",
      "value": "YmxhY2s="
    }
  ],
  "key": {
    "type": "text",
    "data": "Test Key"
  },
  "value": {
    "type": "text",
    "data": "Test Value"
  }
}' \
"$kafka_http_url/v2/topics/$topic_name/records"

如需 API 的相關資訊，請參閱 Event Streams REST 生產者 API 參考資料。

產生符合綱目的訊息

您可以利用 REST 生產者 API 的 v2 端點來產生訊息，使訊息索引鍵和值符合綱目。 您可以為索引鍵和值指定不同的綱目。 支援的序列化程式是 confluent，支援的資料類型是 avro。 綱目已建立並儲存在 Event Streams 綱目登錄中。 如需相關資訊，請參閱 Event Streams 綱目登錄。

容許下列綱目命名策略:

  • 主題命名策略: 使用主題名稱來衍生綱目構件 ID。 The ID takes the form "<topicName>-key" for key and "<topicName>-value" for value, where topicName is the name of topic.

  • 記錄命名策略: 使用綱目中的記錄名稱來衍生綱目構件 ID。 The ID takes the form "<composite-recordName>-key" for key and "<composite-recordName>-value" for value. If the schema namespace field is specified, the composite-recordName takes the value of "<namespace>.<recordName>", otherwise it takes the value of "<recordName>".

  • TopicRecord 命名策略: 同時使用主題名稱和記錄名稱來衍生綱目構件 ID。 The ID takes the form "<topicName>-<recordName>-key" for key and "<topicName>-<composite-recordName>-value" for value, where topicName is the name of topic. If the schema namespace field is specified, the composite-recordName takes the value of "<namespace>.<recordName>", otherwise it takes the value of "<recordName>".

下列程式碼顯示使用 curl 傳送符合 schema 欄位下所指定之綱目的訊息範例:

curl -v -X POST \
-H "Authorization: Bearer $token" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
  "value": {
    "type": "avro",
    "schema": "{\"namespace\": \"com.eventstreams.samples\",\"type\": \"record\",\"name\": \"recordValueName\",\"fields\": [{\"name\": \"valueName\", \"type\": \"string\"}]}",
    "schema_name_strategy": "record",
    "data": "{\"valueName\": \"sampleValueName\"}"
  }
}' \
"$kafka_http_url/v2/topics/$topic_name/records?serializer=confluent"

從 REST 生產者 API 的現有端點移轉至 v2 端點

對 v2 端點進行了一些改進，以更好地使用並符合 API 標準。 若要充分利用這些改進，請對現有應用程式進行變更。

下列考量可協助您規劃移轉:

  1. 存取 REST 生產者 API:

    您可以使用與現有 URL 相同的方式來存取 v2 端點，作法是取得服務實例的 kafka_http_url 內容值。 要使用的路徑是 /v2/topics/<topic_name>/records。

    Example URL: https://service-instance-adsf1234asdf1234asdf1234-0000.us-south.containers.appdomain.cloud/v2/topics/topic_name/records

  2. 鑑別：

    支援的鑑別機制是載送記號。 為了加強安全，不再接受使用 API 金鑰進行基本鑑別。

    Example Header:  -H "Authorization: Bearer $token"

  3. 標頭:

    將內容類型及接受標頭設為 application/json。

    Example Headers:  -H "Content-Type: application/json" -H "Accept: application/json"

  4. 有效負載：

    以 JSON 格式提供 v2 端點的有效負載。 訊息金鑰、標頭及資料可以定義在有效負載中。 您可以使用 base64 編碼的值，以清單形式指定標頭。 不過，訊息鍵和標頭是選用的。

    Example payload:
{
  "headers": [
  {
   "name": "colour",
   "value": "YmxhY2s="
  },
  "key": {
   "type": "text",
   "data": "Test Key"
  },
  "value": {
   "type": "text",
   "data": "Test Value"
  }
 }

    您必須為索引鍵和值物件下的欄位類型指定下列其中一個受支援的資料類型:

    a. 文字: 提供的資料驗證為純文字格式，由線性字元序列組成。

    b. 二進位: 所提供的資料驗證為 base64-encoded 二進位格式。

    c. JSON: 所提供的資料會驗證為 JSON 格式。

    d. Avro: 資料驗證為 Apache Avro 資料格式。

  5. 錯誤回應:

    錯誤回應包含 trace、error message、error code、more_info 及 target 內容。

    Example error response:
{
 "trace": "a222e93c-e5f9-435d-b275-5d4919ea87ed",
 "error": {
  "code": "invalid_type",
  "message": "'type' field in 'value' object is required ...",
  "more_info": "https://cloud.ibm.com/apidocs/event-streams/restproducer_v2",
  "target": {
   "type": "field",
   "name": "type"
  }
 }
}

限制

當您使用 REST 生產者 API 時，作為要求有效負載傳遞的訊息大小上限存在限制。 有效負載的大小上限限制為 64 K。

API 參考資料

如需 v2 端點 API 的完整資料，請參閱 Event Streams REST 生產者 v2 API 參考資料。

如需現有端點 API 的完整資料，請參閱 Event Streams REST 生產者 API 參考資料。