Azure 事件方格適用于 JavaScript 的用戶端程式庫 - 5.1.0-Beta.1 版

Azure 事件方格是雲端式服務，可提供大規模的可靠事件傳遞。

使用用戶端程式庫可以：

• 使用事件方格、雲端事件 1.0 架構或自訂架構，將事件傳送至事件方格
• 解碼和處理傳遞至事件方格處理常式的事件
• 產生事件方格的共用存取簽章主題

重要連結：

• 原始程式碼 \(英文\)
• 套件 (NPM)
• API 參考文件
• 產品文件
• 範例

開始使用

目前支援的環境

• LTS 版本的 Node.js
• Safari、Chrome、Edge 和 Firefox 的最新版本。

如需詳細資訊，請參閱我們的支援原則。

必要條件

• Azure 訂用帳戶。
• 現有的 事件方格 主題或網域。 如果您需要建立資源，您可以使用 Azure 入口網站或Azure CLI。

如果您使用 Azure CLI，請將 和 <your-resource-name> 取代 <your-resource-group-name> 為您自己的唯一名稱：

建立事件方格主題

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

建立事件方格網域

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

安裝 @azure/eventgrid 套件

使用 安裝適用于 JavaScript npm 的 Azure 事件方格 用戶端程式庫：

npm install @azure/eventgrid

建立和驗證 EventGridPublisherClient

若要建立用戶端物件來存取 Event Grid API，您需要 endpoint Event Grid 主題和 credential 的 。 事件方格用戶端可以使用存取金鑰或共用存取簽章， (SAS) 從存取金鑰建立。

您可以在 Azure 入口網站或使用下列 Azure CLI 程式碼片段，找到事件方格主題的端點：

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

使用存取金鑰

使用 Azure 入口網站 流覽至您的事件方格資源並擷取存取金鑰，或使用下列 Azure CLI 程式碼片段：

az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>

擁有 API 金鑰和端點之後，您可以使用 AzureKeyCredential 類別來驗證用戶端，如下所示：

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureKeyCredential("<Access Key>")
);

使用 SAS 權杖

如同存取金鑰，SAS 權杖允許存取將事件傳送至事件方格主題。 不同于在重新產生存取金鑰之前可以使用的存取金鑰，SAS 權杖具有 experation 時間，此時它不再有效。 若要使用 SAS 權杖進行驗證，請使用 AzureSASCredential 如下所示：

const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureSASCredential("<SAS Token>")
);

您可以使用 函 generateSharedAccessSigniture 式來產生 SAS 權杖。

const { generateSharedAccessSignature, AzureKeyCredential } = require("@azure/eventgrid");

// Create a SAS Token which expires on 2020-01-01 at Midnight.
const token = generateSharedAccessSignature(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  new Date("2020-01-01T00:00:00")
);

使用 Azure Active Directory (AAD)

Azure EventGrid 提供與 Azure Active Directory (Azure AD) 整合，以進行要求的身分識別型驗證。 透過 Azure AD，您可以使用角色型存取控制 (RBAC) ，將Azure 事件方格資源的存取權授與使用者、群組或應用程式。

若要將事件傳送至具有 TokenCredential 的主題或網域，已驗證的身分識別應該已指派「EventGrid 資料傳送者」角色。

@azure/identity透過套件，您可以在開發和生產環境中順暢地授權要求。 若要深入瞭解 Azure Active Directory，請參閱@azure/identity 讀我檔案。

例如，使用 可用來 DefaultAzureCredential 建構使用 Azure Active Directory 進行驗證的用戶端：

const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new DefaultAzureCredential()
);

重要概念

EventGridPublisherClient

EventGridPublisherClient 是用來將事件傳送至事件方格主題或事件方格網域。

事件架構

事件方格支援多個編碼事件的架構。 建立自訂主題或網域時，您可以指定發佈事件時將使用的架構。 雖然您可以將主題設定為使用 自訂架構 ，但較常使用已定義的 事件方格架構 或 CloudEvents 1.0 架構。 CloudEvents 是 Cloud Native Computing Foundation 專案，其會產生一個規格，以常見方式描述事件資料。 當您建構 EventGridPublisherClient 時，您必須指定主題設定為要使用的架構：

如果您的主題設定為使用事件方格架構，請將 「EventGrid」 設定為架構類型：

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API Key>")
);

如果您的主題設定為使用雲端事件架構，請將 「CloudEvent」 設定為架構類型：

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new AzureKeyCredential("<API Key>")
);

如果您的主題設定為使用自訂事件架構，請將 「Custom」 設定為架構類型：

const client = new EventGridPublisherClient(
  "<endpoint>",
  "Custom",
  new AzureKeyCredential("<API Key>")
);

建構具有與主題所預期不同架構的用戶端，會導致服務發生錯誤，而且不會發佈您的事件。

您可以使用下列 Azure CLI 程式碼片段，查看事件方格主題已設定的輸入架構：

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"

EventGridDeserializer

事件方格傳遞至取用者的事件會以 JSON 形式傳遞。 視要傳遞的取用者類型而定，事件方格服務可能會在單一承載中傳遞一或多個事件。 雖然這些事件可能會使用之類的 JSON.parse 一般 JavaScript 方法還原序列化，但此程式庫會提供協助程式類型來還原序列化事件，稱為 EventGridDeserializer 。

相較于直接使用 JSON.parse ， EventGridDeserializer 在還原序列化事件時會執行一些額外的轉換：

1. EventGridDeserializer 會驗證事件的必要屬性是否存在，而且是正確的類型。
2. EventGridDeserializer 將事件時間屬性轉換成 JavaScript Date 物件。
3. 使用雲端事件時，二進位資料可用於事件的資料屬性， (使用 Uint8Array) 。 透過事件方格傳送事件時，它會以 Base 64 編碼。 EventGridDeserializer 會將此資料解碼回 實例 Uint8Array 。
4. 將 系統事件 還原序列化 (另一個 Azure 服務所產生的事件) 時，會執行其他轉換， EventGridDeserializerdata 讓物件符合描述其資料的對應介面。 使用 TypeScript 時，這些介面可確保當您存取系統事件之資料物件的屬性時，您具有強型別。

建立 的 EventGridDeserializer 實例時，可能會提供用來進一步轉換 data 物件的自訂還原序列化器。

分散式追蹤和雲端事件

此程式庫支援使用 @azure/core-tracing 的分散式追蹤。 使用分散式追蹤時，此程式庫會在作業期間 send 建立範圍。 此外，使用雲端事件 1.0 架構傳送事件時，SDK 會使用 分散式追蹤延伸模組將分散式追蹤中繼資料新增至事件。 和 tracestate 延伸模組屬性的值 traceparent 會對應至 traceparent 傳送事件的 HTTP 要求中的 和 tracestate 標頭。 如果事件已經有 traceparent 擴充屬性，則不會更新。

Kubernetes 上的事件方格

此程式庫已在 Kubernetes 上使用 Azure Arc進行測試和驗證。

範例

使用事件方格架構將自訂事件發佈至事件方格主題

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

使用事件方格架構，將自訂事件發佈至事件方格網域中的主題

將事件發佈至事件方格網域類似于發佈至事件方格主題，不同之處在于針對事件使用 Event Grid 架構時，您必須包含 topic 屬性。 在 Cloud Events 1.0 架構中發佈事件時，必要 source 屬性會用來作為網域中主題的名稱，以發佈至：

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    topic: "my-sample-topic",
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

還原序列化事件

EventGridDeserializer 可用來還原序列化事件方格所傳遞的事件。 在此範例中，我們有一個使用 EventGridDeserializer 還原序列化的雲端事件，並使用 isSystemEvent 來偵測它們所在的事件種類。

const { EventGridDeserializer, isSystemEvent } = require("@azure/eventgrid");

async function main() {
  const deserializer = new EventGridDeserializer();
  const message = {
    id: "5bc888aa-c2f4-11ea-b3de-0242ac130004",
    source:
      "/subscriptions/<subscriptionid>/resourceGroups/dummy-rg/providers/Microsoft.EventGrid/topics/dummy-topic",
    specversion: "1.0",
    type: "Microsoft.ContainerRegistry.ImagePushed",
    subject: "Test Subject",
    time: "2020-07-10T21:27:12.925Z",
    data: {
      hello: "world",
    },
  };
  const deserializedMessage = await deserializer.deserializeCloudEvents(message);
  console.log(deserializedMessage);

  if (
    deserializedMessage != null &&
    deserializedMessage.length !== 0 &&
    isSystemEvent("Microsoft.ContainerRegistry.ImagePushed", deserializedMessage[0])
  ) {
    console.log("This is a Microsoft.ContainerRegistry.ImagePushed event");
  }
}

main();

疑難排解

記錄

啟用記錄有助於找出失敗的相關實用資訊。 若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

如需如何啟用記錄的詳細指示，請參閱 @azure/記錄器套件檔。

下一步

如需如何使用此程式庫的詳細範例，請參閱 範例 目錄。

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

相關專案

• Microsoft Azure SDK for JAVAscript