適用於 JavaScript 的 Azure 事件方格用戶端連結庫 - 5.5.0 版

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

使用用戶端程式庫可以：

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

重要連結：

• 原始程式碼 \(英文\)
• 套件 (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 套件

使用 npm安裝適用於 JavaScript 的 Azure 事件方格用戶端連結庫：

npm install @azure/eventgrid

建立和驗證 EventGridPublisherClient

若要建立客戶端物件來存取事件方格 API，您需要 endpoint 事件方格主題和 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 time，此時不再有效。 若要使用 SAS 令牌進行驗證，請使用 AzureSASCredential ，如下所示：

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

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

您可以使用 函式來產生 SAS 令牌 generateSharedAccessSigniture 。

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 會使用 分散式追蹤延伸模組將分散式追蹤元數據新增至事件。 和擴充屬性的值traceparent會對應至 traceparent HTTP 要求中的和 tracestatetracestate 標頭，以傳送事件。 如果事件已經有 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",
    },
  },
]);

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

將事件發佈至事件方格網域類似於發佈至事件方格主題，但使用事件的事件方格架構時，您必須包含 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