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

發行項
07/17/2024

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

使用用戶端連結庫來：

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

主要連結：

開始

目前支持的環境

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

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

先決條件

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

如果您使用 Azure CLI，請使用您自己的唯一名稱取代 <your-resource-group-name> 和 <your-resource-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 令牌具有加速時間，此時不再有效。若要使用 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 還原串行化事件時會執行一些額外的轉換：

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

建立 EventGridDeserializer 實體時，您可以提供用來進一步轉換 data 物件的自定義還原串行化器。

分散式追蹤和雲端事件

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

Kubernetes 上的事件方格

此連結庫已在使用 Azure ArcKubernetes 上進行測試和驗證。

例子

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

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

共用方式為

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

開始

目前支持的環境

先決條件

建立事件方格主題

建立事件方格網域

安裝 `@azure/eventgrid` 套件

建立和驗證 `EventGridPublisherClient`

使用存取金鑰

使用SAS令牌

使用 Azure Active Directory （AAD）

重要概念

EventGridPublisherClient

事件架構

EventGridDeserializer

分散式追蹤和雲端事件

Kubernetes 上的事件方格

例子

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

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

還原串行化事件

故障排除

伐木

後續步驟

貢獻

其他資源

共用方式為

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

開始

目前支持的環境

先決條件

建立事件方格主題

建立事件方格網域

安裝 @azure/eventgrid 套件

建立和驗證 EventGridPublisherClient

使用存取金鑰

使用SAS令牌

使用 Azure Active Directory （AAD）

重要概念

EventGridPublisherClient

事件架構

EventGridDeserializer

分散式追蹤和雲端事件

Kubernetes 上的事件方格

例子

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

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

還原串行化事件

故障排除

伐木

後續步驟

貢獻

相關專案

其他資源

安裝 `@azure/eventgrid` 套件

建立和驗證 `EventGridPublisherClient`