Event Streams for IBM Cloud 的快速設定手冊

步驟 2: 使用主控台佈建 Event Streams 實例

1. 登入 IBM Cloud 主控台。

2. 按一下 型錄中的 Event Streams 服務。

3. 從 選取定價方案 區段中選取 精簡方案、標準方案或 企業方案。

4. 輸入服務的名稱。 您可以使用預設值。

5. 按一下建立。 即會開啟 Event Streams 資源清單 頁面。

6. 建立您的實例之後，請按一下實例名稱以檢視相關資訊。

7. 選用。 您可以完成 入門指導教學 中的步驟，以執行範例入門範本應用程式。

步驟 2: 使用 CLI 佈建 Event Streams 實例

如果這是您第一次使用 CLI，請參閱 開始使用 CLI。

若要使用 IBM Cloud CLI 來佈建 Event Streams 標準方案的實例，請完成下列步驟:

1. 完成 開始使用 IBM Cloud CLI中的步驟，以安裝 IBM Cloud CLI。

2. 執行下列指令，以登入 IBM Cloud：

   ibmcloud login -a cloud.ibm.com
   

3. 使用精簡方案、標準方案或企業方案在 Event Streams 上建立 IBM Cloud 實例。

   選取下列其中一種方法：

   • 若要在企業計劃上使用 CLI 建立實體，請執行下列指令：

     ibmcloud resource service-instance-create <INSTANCE_NAME> messagehub enterprise-3nodes-2tb <REGION>
     

     由於企業計劃的每個群集都有自己的專用資源，因此需要較長的時間進行佈建，所以一個新的企業實例可能需要長達 3 小時的時間。

   • 若要在標準方案上從 CLI 建立實例，請執行下列指令:

     ibmcloud resource service-instance-create <INSTANCE_NAME> messagehub standard <REGION>
     

     由於底層資源已經設定，因此可立即提供新的標準計劃實例。

步驟 2: 使用資源控制器 API 來佈建 Event Streams 實例

佈建實例的偏好方法是使用 CLI。

或者，您可以使用 資源控制器 API。 首先，擷取存取記號，然後使用存取記號來執行資源控制器 API 指令，以 建立實例。

curl -X POST https://resource-controller.cloud.ibm.com/v2/resource_instances -H "Authorization: ${token}" -H "Content-Type: application/json" \
-d '{ "name": "JG-test-curl", "target": "us-south", "resource_group":"9eba3cff1b0540b9ab7fb93829911da0", "resource_plan_id": "ibm.message.hub.enterprise.3nodes.2tb", "parameters":{"service-endpoints":"public","throughput":"150"}}'

步驟 3: 使用主控台建立主題並選取分割區數目

如需建立主題時可修改之設定的指引，請參閱 主題配置。

1. 從新佈建的實例，使用左側的功能表導覽至 主題。

2. 按一下 建立主題 按鈕，然後輸入主題名稱。 按下一步。 主題名稱最多只能有 200 個字元。

3. 選取分割區數目。

   主題由一個以上分割區構成。 分割區是訊息的排序清單。1 個分割區已足夠開始使用，但正式作業系統通常有更多。

   分區分佈在經銷商間，以增加主題的可擴展性。 您也可以使用這些分割區，在消費者群組的成員之間配送訊息。

   按下一步。

4. 設定訊息保留期限。 這是訊息在刪除之前保留的時間長度。 如果消耗者未在此時間內讀取訊息，則會遺失這些訊息。 預設的訊息保留期限為 24 小時。 最短 1 小時，最長 30 天。 請以小時的倍數來指定此值。

   按一下 建立主題。

步驟 3: 使用 CLI 建立主題並選取分割區數目

如需建立主題時可修改之設定的指引，請參閱 主題配置。

使用下列 ibmcloud es topic-create 指令，以您選擇的分割區數目來建立新主題:

ibmcloud es topic-create [--name] TOPIC_NAME [--partitions PARTITIONS] [--config KEY=VALUE[;KEY=VALUE]* ]*

必要條件：無

指令選項：

--name value, -n value

主題名稱。 主題名稱最多只能有 200 個字元。

--partitions value, -p value

設定主題的分割區數目。

主題由一個以上分割區構成。 分割區是訊息的排序清單。1 個分割區已足夠開始使用，但正式作業系統通常有更多。

分區分佈在經銷商間，以增加主題的可擴展性。 您也可以使用這些分割區，在消費者群組的成員之間配送訊息。

--config KEY=VALUE, -c KEY=VALUE（選用）

將主題的配置選項設定為 KEY=VALUE 配對。

可以指定多個 --config 選項。 每個 "--config" 選項可以指定一個以分號區隔的指派清單。 下列清單顯示有效的配置金鑰:

• cleanup.policy
• retention.ms
• retention.bytes
• segment.bytes
• segment.ms
• segment.index.bytes

retention.ms 金鑰指定的訊息預設保留期間為 24 小時。 最短 1 小時，最長 30 天。 請以小時的倍數來指定此值。

ibmcloud es topics [--filter FILTER] [--json]

ibmcloud es cluster [--json]

步驟 3: 使用管理 REST API 建立主題並選取分割區數目

Event Streams 提供用於管理的 REST API，可用來建立及列出主題。

您可以對 /admin/topics 路徑發出 POST 要求來建立 Kafka 主題。 要求的內文必須包含 JSON 文件。 例如：

{
    "name": "topicname",
    "partitions": 1,
    "configs": {
        "retentionMs": 86400000,
        "cleanupPolicy": "delete"
    }
}

JSON 文件必須包含 name 屬性，並指定要建立的 Kafka 主題名稱。 主題名稱限制為最多 200 個 characters.The JSON 也可以指定要指派給主題的分割區數目 (使用 partitions 內容)。 如果未指定分割區數目，則會使用單一分割區來建立主題。

主題由一個以上分割區構成。 分割區是訊息的排序清單。1 個分割區已足夠開始使用，但正式作業系統通常有更多。

分區分佈在經銷商間，以增加主題的可擴展性。 您也可以使用這些分割區，在消費者群組的成員之間配送訊息。

您也可以在要求內指定選用的 configs 物件。 這可讓您指定 retentionMs 內容，該內容可控制 Kafka 保留已發佈至主題之訊息的時間 (毫秒)。 過了此時間之後，會自動刪除訊息以釋放空間。 您必須以整數時數來指定 retentionMs 內容的值 (例如，3600000 的倍數)。 預設的訊息保留期限為 24 小時。 最短 1 小時，最長 30 天。

如需建立主題時可修改之設定的指引，請參閱 主題配置。

預期的 HTTP 狀態代碼如下：

• 202: 已接受主題建立要求。
• 400: 要求 JSON 無效。
• 403: 未獲授權建立主題。
• 422: 要求局部無效。

如果建立 Kafka 主題的請求成功，則會傳回 HTTP 狀態代碼 202 (已接受)。 如果操作失敗，則會返回 HTTP 狀態代碼 422 (Unprocessable Entity)，並返回包含失敗相關附加資訊的 JSON 物件作為回應的正文。

curl -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Authorization: Bearer ${TOKEN}' --data '{ "name": "newtopic", "partitions": 1}' ${ADMIN_URL}/admin/topics

[
  {
    "name": "topic1",
    "partitions": 1,
    "retentionMs": 86400000,
    "cleanupPolicy": "delete"
  },
  { "name": "topic2",
    "partitions": 2,
    "retentionMs": 86400000,
    "cleanupPolicy": "delete"
  }
]

curl -i -X GET -H 'Accept: application/json' -H 'Authorization: Bearer ${TOKEN}' ${ADMIN_URL}/admin/topics

步驟 4: 使用主控台建立服務認證

若要容許您連接至 Event Streams 實例，請使用 IBM Cloud 主控台來建立服務金鑰:

1. 在 資源清單中尋找 Event Streams 服務。
2. 按一下您的服務磚。
3. 按一下服務認證。
4. 按一下新認證。
5. 填寫新認證的詳細資料，例如名稱及角色，然後按一下新增。 新認證會出現在認證清單中。
6. 展開新認證的區段，以 JSON 格式顯示詳細資料。

步驟 4: 使用 CLI 建立服務認證

使用 IBM Cloud CLI 建立服務金鑰，以便您可以連接至 Event Streams 實例:

1. 找到您的服務：

   ibmcloud resource service-instances
   

2. 建立服務金鑰：

   ibmcloud resource service-key-create <key_name> <key_role> --instance-name <your_service_name>
   

3. 列印服務金鑰：

   ibmcloud resource service-key <key_name>
   

   每一個服務金鑰中包含一組端點詳細資料。 對於配置為連接至單一網路類型的服務實例，IBM Cloud 公用網路 (預設值) 或 IBM Cloud 專用網路，服務金鑰包含與該網路類型相關的詳細資料。 對於配置為同時支援專用及公用網路的實例，會傳回公用網路的詳細資料。 如果您想要專用網路的詳細資料，則必須將 --service-endpoint private 參數新增至前一個 service-key-create CLI 指令。 例如：

   ibmcloud resource service-key-create <private-key-name> <role> --instance-name <instance-name> --service-endpoint private
   

步驟 4: 使用 CLI 及 REST 生產者 API 來建立服務認證

若要連接至 Event Streams 實例，支援的鑑別機制正在使用載送記號。 若要使用 IBM Cloud CLI 取得令牌，請先登入 IBM Cloud，然後執行下列指令：

ibmcloud iam oauth-tokens

將此標記以 Bearer<token> 的形式放入 HTTP 請求的授權標頭中。 同時支援 API 金鑰和 JWT 記號。

步驟 5: 使用主控台產生資料

您無法使用主控台來產生資料。 您可以使用 指令行、REST 生產者 API 或 Kafka API 來產生資料。

不過，您可以在 入門指導教學 中完成主控台的步驟，以執行範例入門範本應用程式，並查看流經主題的訊息。

步驟 5: 使用指令行產生資料

您可以使用 Event Streams Kafka 主控台生產者工具來產生資料。 主控台工具位於 Kafka 用戶端下載的 bin 目錄中，您可以從 Apache Kafka 下載下載。 建議您下載最新可用的穩定二進位版本。 Kafka 用戶端版本與伺服器上的 Kafka 版本舊版相容。

您必須提供分配管理系統 (使用 BOOTSTRAP_ENDPOINTS 內容) 及 SASL 認證的清單。

要向此工具提供 SASL 認證，請根據以下範例建立一個 properties 檔案：

    sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="<user>" password="<api_key>";
    security.protocol=SASL_SSL
    sasl.mechanism=PLAIN
    ssl.protocol=TLSv1.2
    ssl.enabled.protocols=TLSv1.2
    ssl.endpoint.identification.algorithm=HTTPS

使用服務金鑰中的 <user> 欄位作為使用者名稱，並使用服務金鑰中的 <api_key> 欄位作為密碼。 您可以在 IBM Cloud 主控台的 Event Streams 服務認證 標籤中找到這些值。

Event Streams 提供 Java 用戶端 的範例 producer.properties 和 consumer.properties 檔案。

建立 properties 檔案後，您可以在終端機執行控制台製作程式，如下所示：

   kafka-console-producer.sh --broker-list BOOTSTRAP_ENDPOINTS --producer.config CONFIG_FILE --topic TOPIC_NAME

將範例中的下列變數取代為您自己的值：

• 使用來自 IBM Cloud 主控台中 Event Streams 服務認證 標籤的值的 BOOTSTRAP_ENDPOINTS。
• CONFIG_FILE 取代為配置檔的路徑。

• 使用服務索引鍵中的 <bootstrap_endpoints> 欄位作為 Kafka 應用程式的 bootstrap.servers 內容。
• 使用服務金鑰中的 <user> 欄位作為使用者名稱，並使用服務金鑰中的 <api_key> 欄位作為密碼。 請確定您的應用程式會剖析詳細資料。

您可以使用此工具的許多其他選項，但需要存取 ZooKeeper 的選項除外。 如需相關資訊，請參閱 搭配使用 Kafka 主控台工具與 Event Streams。

步驟 5: 使用 REST 生產者 API 產生資料

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

• 何謂標頭? 它們是選用項目嗎? 您會在訊息內文中看到標頭。 這是包含要求或回應中所有內容的資料片段。 標頭通常在要求行或回應行之後。 顏色的值是 base64-如何執行?

以下程式碼顯示一個使用 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"

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

步驟 6: 使用主控台耗用資料

您無法使用主控台來耗用資料。 您可以使用 指令行 或 Kafka API 來耗用資料。

不過，您可以完成 入門指導教學 中的步驟，以執行範例入門範本應用程式，並查看流經主題的訊息。

步驟 6: 使用指令行耗用資料

您可以使用 Event Streams Kafka 主控台消費者工具來耗用資料。

主控台工具位於 Kafka 用戶端下載的 bin 目錄中。

您必須提供分配管理系統及 SASL 認證的清單。 依照 使用指令行產生資料 中的說明來建立內容檔之後，請在終端機中執行主控台消費者，如下所示:

   kafka-console-consumer.sh --bootstrap-server BOOTSTRAP_ENDPOINTS --consumer.config CONFIG_FILE --topic TOPIC_NAME

將範例中的下列變數取代為您自己的值：

• 使用來自 IBM Cloud 主控台中 Event Streams 服務認證 標籤的值的 BOOTSTRAP_ENDPOINTS。
• CONFIG_FILE 取代為配置檔的路徑。

您可以使用此工具的許多其他選項，但需要存取 ZooKeeper 的選項除外。 如需相關資訊，請參閱 搭配使用 Kafka 主控台工具與 Event Streams。

步驟 6: 使用 API 耗用資料

您無法使用 Event Streams API 來耗用資料，雖然可以使用原生 Kafka 程式庫來耗用來自 Kafka 的資料。 如需相關資訊，請參閱 Kafka 消費者 API。

作為替代方案，請使用 指令行。

步驟 7: 使用主控台來連接 IBM Cloud Monitoring 以取得作業可見性

您可以使用 IBM Cloud Monitoring 來取得應用程式、服務及平台之效能及性能的作業可見性。IBM Cloud Monitoring 提供管理者、DevOps 團隊及開發人員完整堆疊遙測，以及用來監視及疑難排解、定義警示及設計自訂儀表板的進階特性。

有關如何使用 Monitoring 與 Event Streams 的詳細資訊，請參閱：

• 選擇加入度量值
• 啟用預設度量
• 啟用加強的度量值
• 檢視可用度量值的詳細資料
• 瞭解度量成本資訊

步驟 7: 使用 CLI 或指令行來連接 IBM Cloud Monitoring 以取得作業可見性

您無法使用 CLI 或指令行來連接 IBM Cloud Monitoring。 使用 主控台 來完成這項作業。

步驟 7: 使用 API 來連接 IBM Cloud Monitoring 以取得作業可見性

您無法使用 API 來連接 IBM Cloud Monitoring。 使用 主控台 來完成這項作業。

步驟 8: 將 IBM Cloud® Activity Tracker 連接至審核服務活動

IBM Cloud Activity Tracker 可讓您檢視、管理及審核服務活動，以符合公司原則及產業法規。Activity Tracker 記錄使用者起始的活動，這些活動會變更 IBM Cloud中服務的狀態。 使用 Activity Tracker 追蹤使用者和應用程式如何與標準和企業方案上的 Event Streams 服務互動。

若要開始進行 Activity Tracker，請參閱 開始使用 Activity Tracker。

Activity Tracker 在每個位置只能有一個實例。 若要檢視事件，您必須在可以使用服務實例的相同位置中存取 Activity Tracker 服務的 Web 使用者介面。 如需相關資訊，請參閱 啟動 Web 使用者介面。

如需 Event Streams特定事件的相關資訊，請參閱:

• 檢視事件的位置
• 主題事件
• 訊息審核事件
• 其他事件

事件的格式符合雲端稽核資料聯盟 (CADF) 標準。 如需它們所包含資訊的進一步詳細資料，請參閱 CADF 標準。

步驟 8: 使用 CLI 或指令行連接 IBM Cloud® Activity Tracker 以審核服務活動

您無法使用 CLI 或指令行來連接 Activity Tracker。 使用 主控台 來完成這項作業。

步驟 8: 使用 API 連接 IBM Cloud® Activity Tracker 以審核服務活動

您無法使用 API 來連接 Activity Tracker。 使用 主控台 來完成這項作業。