適用於 JavaScript 的 Azure 通知中樞 SDK

發行項
05/21/2024

Azure 通知中樞提供向外延展的推播引擎，可讓您從任何後端 (雲端或內部部署) ，將通知傳送至任何平臺 (Apple、Amazon Kindle、Firebase、Baidu、Pipelinemi、Web、Windows ) 等。通知中樞適用於企業和取用者案例。以下是一些範例案例：

傳送即時新聞通知給數百萬人，且延遲時間很低。
將位置型折價券傳送給感興趣的使用者區段。
將事件相關通知傳送給媒體/運動/財金/遊戲應用程式的使用者或群組。
將促銷內容推播到應用程式，來與客戶互動及行銷。
對使用者發送企業事件通知，例如新訊息和工作項目。
傳送 Multi-Factor Authentication 的程式碼。

重要連結：

注意：如果您來自使用 azure-sb 套件，請參閱 migration guide to move from azure-sb to @azure/notification-hubs

開始使用

目前支援的環境

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

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

安裝套件

npm install @azure/notification-hubs

必要條件

Azure 訂用帳戶
應用程式通知中樞資源。

Create Azure 通知中樞資源

您可以使用下列方法來建立 Azure 通知中樞：

建立之後，可以使用 Azure 入口網站或 Azure CLI 來設定通知中樞。

匯入用戶端

此適用於 JavaScript 的 SDK 提供兩種方式來與 Azure 通知中樞互動，不論是透過類別型方法，還是使用模組化設計方法。類別型方法在所有套件中都是一致的，以建立用戶端，然後與用戶端上的方法互動。

import {
  NotificationHubsClient,
  createAppleInstallation
} from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const installation = createAppleInstallation({
  installationId: "<installation-id>",
  pushChannel: "<push-channel>",
  tags: ["likes_javascript"],
});

const result = await client.createOrUpdateInstallation(installation);

模組化方法可讓開發人員挑選並選擇要匯入的函式，因為每個方法都會個別公開。此方法使用子路徑匯出搭配 ES-Modules，透過直接匯入公開方法。透過個別匯出，這會建立更好的樹狀結構震動體驗，以及開發人員可以利用的較小套件組合大小。

請注意，建立用戶端會透過 "@azure/notification-hubs/api" 子路徑公開，而所有用戶端方法都會透過 "@azure/notification-hubs/api" 子路徑公開。導出的每個函式都會採用 client 做為第一個參數，其餘的參數仍保持不變。

下列子路徑會公開：

@azure/notification-hubs/api - 透過 createClientContext 用戶端的主要進入點，以及或之類的 getInstallation 用戶端方法 sendNotification
@azure/notification-hubs/models - 通知中樞模型和處理站方法。

然後，上述代碼段會變成下列內容：

import { createClientContext, createOrUpdateInstallation } from "@azure/notification-hubs/api";
import { createAppleInstallation } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

const installation = createAppleInstallation({
  installationId: "<installation-id>",
  pushChannel: "<push-channel>",
  tags: ["likes_javascript"],
});

const result = await createOrUpdateInstallation(context, installation);

驗證用戶端

與 Azure 通知中樞的互動會從支援共用存取簽章連接字串的開始NotificationHubsClient。這包括下列許可權等級：接聽、管理、傳送。

接聽可讓用戶端透過註冊和安裝 API 自行註冊。傳送可讓用戶端使用傳送 API 將通知傳送至裝置。最後，[管理] 可讓使用者執行註冊和安裝管理，例如查詢。

您可以使用具有連接字串和通知中樞名稱的建構函式來建立新的NotificationHubsClient用戶端。

import { NotificationHubsClient } from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

使用模組化方法， createClientContext 可以透過 "@azure/notification-hubs/api" 子路徑匯入。

import { createClientContext } from "@azure/notification-hubs/api";

const context = createClientContext("<connection string>", "<hub name>");

重要概念

NotificationHubClient初始化之後，即可探索下列概念。

透過安裝和註冊描述裝置管理
將通知傳送至裝置

裝置管理

裝置管理是通知中樞的核心概念，能夠儲存原生平臺通知服務的唯一標識符， (PNS) 例如 APN 或 Firebase，以及相關聯的元數據，例如用來將推播通知傳送給物件。這是使用兩個 API 來完成的：安裝 API 是較新且慣用的機制，以及註冊。

安裝 API

安裝是裝置管理的較新原生 JSON 方法，其中包含其他屬性，例如安裝標識碼和使用者識別碼，可用來傳送給物件。安裝 API 有一些優點，可透過下列方式使用現有的註冊 API：

完全等冪 API，因此在安裝上呼叫 create，因此可以重試作業，而不需要擔心重複。
userId支援和 installationId 屬性，這些屬性接著可用於標籤運算式，例如 $InstallationId:{myInstallId} 和 $UserId:{bob@contoso.com}。
範本現在是安裝的一部分，而不是個別的註冊，而且可以依名稱參考作為傳送的標記。
部分更新可透過 JSON 修補程式標準支援，這可讓您新增標籤並變更其他數據，而不需要先查詢安裝。

您可以透過 createOrUpdateInstallation 方法建立安裝，例如下列各項：

import { NotificationHubsClient, createAppleInstallation } from "@azure/notification-hubs";
import { v4 as uuid } from "uuid";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

// Create an installation for APNs
let installation = createAppleInstallation({
  installationId: uuid(), // Must be unique
  pushChannel: "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0", // PNS specific handle
  tags: ["likes_hockey", "likes_football"],
});

installation = await client.createOrUpdateInstallation(installation);

使用模組化方法時，程式代碼如下所示：

import { createClientContext, createOrUpdateInstallation } from "@azure/notification-hubs/api";
import { createAppleInstallation } from "@azure/notification-hubs/models";
import { v4 as uuid } from "uuid";

const context = createClientContext("<connection string>", "<hub name>");

// Create an installation for APNs
let installation = createAppleInstallation({
  installationId: uuid(), // Must be unique
  pushChannel: "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0", // PNS specific handle
  tags: ["likes_hockey", "likes_football"],
});

installation = await createOrUpdateInstallation(context, installation);

您可以透過 JSON 修補程式架構來更新安裝，例如使用 updateInstallation 方法來新增標籤和使用者識別碼。

import { NotificationHubsClient, JsonPatch } from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const installationId = "<unique installation ID>";

const updates: JsonPatch[] = [
  { op: "add", path: "/tags", value: "likes_baseball" },
  { op: "add", path: "/userId", value: "bob@contoso.com" },
];

const installation = await client.updateInstallation(installationId, updates);

使用模組化方法時，程式代碼如下所示：

import { createClientContext, updateInstallation } from "@azure/notification-hubs/api";
import { JsonPatch } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

const installationId = "<unique installation ID>";

const updates: JsonPatch[] = [
  { op: "add", path: "/tags", value: "likes_baseball" },
  { op: "add", path: "/userId", value: "bob@contoso.com" },
];

const installation = await updateInstallation(context, installationId, updates);

若要擷取現有的安裝，請使用 getInstallation 方法搭配您現有的唯一安裝標識符。

import { NotificationHubsClient } from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const installationId = "<unique installation ID>";

const installation = client.getInstallation(installationId);

使用模組化方法時，程式代碼如下所示：

import { createClientContext, getInstallation } from "@azure/notification-hubs/api";

const context = createClientContext("<connection string>", "<hub name>");

const installationId = "<unique installation ID>";

const installation = getInstallation(context, installationId);

註冊 API

註冊與 PNS 相關聯，就像上述安裝一樣，具有 PNS 的唯一裝置識別碼，以及相關聯的標記。範本註冊是建立預先定義的本文範本的方式，這些範本接著可以在傳送時間使用屬性來填入訊息。如需範本的詳細資訊，請參閱範本檔。

您可以透過下列兩種方式之一建立安裝，首先使用和方法createOrUpdateRegistrationcreateRegistration從伺服器getInstallationId取得註冊標識符。

import {
  NotificationHubsClient,
  createAppleRegistrationDescription,
} from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

let registration = createAppleRegistrationDescription({
  deviceToken: "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0",
  tags: ["likes_hockey", "likes_football"],
});

registration = await client.createRegistration(registration);

console.log(`New Registration ID: ${registration.registrationId}`);

使用模組化方法時，程式代碼如下所示：

import { createClientContext, createRegistration } from "@azure/notification-hubs/api";
import { createAppleRegistrationDescription } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

let registration = createAppleRegistrationDescription({
  deviceToken: "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0",
  tags: ["likes_hockey", "likes_football"],
});

registration = await createRegistration(context, registration);

console.log(`New Registration ID: ${registration.registrationId}`);

匯報可以透過 updateRegistration 方法完成，但與安裝不同，不支援累加式更新。您可以使用 getRegistration 方法來查詢現有的註冊。

import { NotificationHubsClient } from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const registrationId = "<unique Registration ID>";

let registration = await client.getRegistration(registrationId);

registration.tags.push("likes_sports");

registration = await client.updateRegistration(registration);

使用模組化方法時，程式代碼如下所示：

import {
  createClientContext,
  getRegistration,
  updateRegistration
} from "@azure/notification-hubs/api";

const context = createClientContext("<connection string>", "<hub name>");

const registrationId = "<unique Registration ID>";

let registration = await getRegistration(context, registrationId);

registration.tags.push("likes_sports");

registration = await updateRegistration(context, registration);

不同於安裝，您可以查詢註冊以取得所有註冊、比對註冊與條件，或透過標記。您可以使用和 listRegistrationsByChannellistRegistrationsByTag 方法來查詢listRegistrations註冊。所有方法都支援透過 top 選項限制，並支援異步分頁。

import { NotificationHubsClient } from "@azure/notification-hubs/api";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const registrations = await client.listRegistrationsByTag("likes_hockey");

let page = 0;
for await (const pages of registrations.byPage()) {
  console.log(`Page number ${page++}`);
  for (const item of pages) {
    console.log(JSON.stringify(item, null, 2));
  }
}

使用模組化方法時，程式代碼如下所示：

import { createClientContext, listRegistrationsByTag } from "@azure/notification-hubs/api";

const context = createClientContext("<connection string>", "<hub name>");

const registrations = await listRegistrationsByTag(context, "likes_hockey");

let page = 0;
for await (const pages of registrations.byPage()) {
  console.log(`Page number ${page++}`);
  for (const item of pages) {
    console.log(JSON.stringify(item, null, 2));
  }
}

傳送作業

通知中樞支援直接使用唯一的 PNS 提供識別碼、使用對象傳送的標籤，或對所有裝置進行一般廣播，將通知傳送至裝置。使用標準 SKU 和更新版本，排程傳送可讓使用者事先排程最多七天的通知。所有傳送作業都會傳回追蹤標識碼和相互關聯標識碼，可用於通知中樞支援案例。使用標準 SKU 和更新版本時，也會傳回通知標識符，可用來透過 getNotificationOutcomeDetails 方法取得通知遙測。

基於偵錯目的， enableTestSend 選項可以設定為 true ，以在生產案例中，從方法上的 sendNotification PNS 立即收到意見反應。排程傳送方法不支援此功能。

原始 JSON 或 XML 字串可以傳送至傳送或排程傳送方法，或者可以使用通知產生器來協助建構每個 PNS 的訊息，例如 APN、Firebase、百度、ADM 和 WNS。這些產生器會建置原生訊息格式，因此不會猜測每個 PNS 可用的欄位。

// Using the class-based approach
import { createAppleNotificationBody } from "@azure/notification-hubs";

// Using the modular approach
import { createAppleNotification, createAppleNotificationBody } from "@azure/notification-hubs/models";

const apnsBody = createAppleNotificationBody({
  alert: {
    title: "Notification Title",
    subtitle: "Notification Subtitle",
    body: "Notification body goes here",
  },
  sound: "default",
  interruptionLevel: "time-sensitive",
});

// Send the message using the modular approach
const notification = createAppleNotification({
  body: apnsBody
})

const result = await sendNotification(context, notification);

廣播傳送

通知中樞可用來透過 sendNotification 方法將通知傳送至每個平臺的所有已註冊裝置。

import {
  NotificationHubsClient,
  createAppleNotification,
} from "@azure/notification-hubs/api";

const context = createClientContext(connectionString, hubName);

const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await client.sendNotification(message);

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

使用模組化方法時，程式代碼如下所示：

import { createClientContext, sendNotification } from "@azure/notification-hubs/api";
import { createAppleNotification } from "@azure/notification-hubs/models";

const context = createClientContext(connectionString, hubName);

const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await sendNotification(context, message);

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

直接傳送

若要直接傳送裝置，使用者可以使用平臺提供的唯一deviceHandle標識符來傳送，例如 APNs 裝置令牌，方法是使用參數呼叫 sendNotification 方法。

import {
  NotificationHubsClient,
  createAppleNotification,
} from "@azure/notification-hubs";

const client = new NotificationHubsClient(connectionString, hubName);

const deviceHandle = "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await client.sendNotification(message, { deviceHandle });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

使用模組化方法，程式代碼如下所示：

import { createClientContext, sendDirectNotification } from "@azure/notification-hubs/api";
import { createAppleNotification } from "@azure/notification-hubs/models";

const context = createClientContext(connectionString, hubName);

const deviceHandle = "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await sendNotification(context, message, { deviceHandle });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

物件傳送

除了以單一裝置為目標之外，使用者還可以使用標記鎖定多個裝置。這些標籤可以做為標籤清單提供，然後建立標籤表示式以符合已註冊的裝置，或透過標籤運算式提供，以便使用布爾邏輯來以正確的物件為目標。如需標籤表達式的詳細資訊，請參閱路由和標籤表示式。

如果您想要從標籤列建立標籤表示式，可從最上層匯入或模組化匯入中公開的方法提供標籤運算式產生器 createTagExpression ，以從標記建立「或 @azure/notification-hubs/models/tagExpressionBuilder 標籤表達式」。

// Top level import
import { createTagExpression } from "@azure/notification-hubs";

// Modular import
import { createTagExpression } from "@azure/notification-hubs/models";

const tags = ["likes_football", "likes_hockey"];
const tagExpression = createTagExpression(tags);

console.log(tagExpression);
// likes_football||likes_hockey

您可以使用下列程式代碼來傳送標記表示式訊息：

import {
  NotificationHubsClient,
  createAppleNotification,
} from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const tagExpression = "likes_hockey && likes_football";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const notification = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await client.sendNotification(notification, { tagExpression });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

使用模組化方法，程式代碼如下所示：

import { createClientContext, sendNotification } from "@azure/notification-hubs/api";
import { createAppleNotification } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

const tagExpression = "likes_hockey && likes_football";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const notification = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await sendNotification(context, notification, { tagExpression });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

排程傳送

推播通知可以事先排程使用標準 SKU 命名空間和更新版本，使用 scheduleBroadcastNotification 方法來傳送至具有卷標或一般廣播的裝置。這會傳回通知標識碼，然後可在必要時透過方法取消 cancelScheduledNotification 。

import {
  NotificationHubsClient,
  createAppleNotification,
} from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const tagExpression = "likes_hockey && likes_football";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

// Schedule 8 hours from now
const scheduledTime = new Date(Date.now() + (8 * 60 * 60 * 1000));

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await client.scheduleNotification(scheduledTime, message, { tagExpression });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Can be used to cancel via the cancelScheduledSend method
console.log(`Notification ID: ${result.notificationId}`);

使用模組化方法，程式代碼如下所示：

import { createClientContext, scheduleNotification } from "@azure/notification-hubs/api";
import { createAppleNotification } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

const tagExpression = "likes_hockey && likes_football";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

// Schedule 8 hours from now
const scheduledTime = new Date(Date.now() + (8 * 60 * 60 * 1000));

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await scheduleNotification(context, scheduledTime, message, { tagExpression });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Can be used to cancel via the cancelScheduledSend method
console.log(`Notification ID: ${result.notificationId}`);

疑難排解

React Native支援

React Native 目前不支援 Azure 通知中樞 SDK 所使用的 [URLSearchParams]。若要在 React Native 中使用 SDK，您必須先安裝url-search-params-polyfill套件並加以匯入，才能使用 SDK。

import 'url-search-params-polyfill';

我們也需要為 API 和異步反覆運算器 API 提供 polyfill TextEncoder 。如需詳細資訊，請參閱我們的 React Native 範例與 Expo。

診斷已捨棄的通知

Azure 通知中樞有完整的指南，可在診斷 Azure 通知中樞的已捨棄通知指南中針對已捨棄通知的問題進行疑難解答。

方法支援sendNotificationenableTestSend使用選項支援測試傳送：

// Using the client
const result = await client.sendNotification(notification, { tags, enableTestSend: true });

// Using the modular approach
const result = await sendNotification(context, notification, { tags, enableTestSend: true });

記錄

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

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

setLogLevel("info");

如需如何啟用記錄的詳細指示，可參閱 @azure/logger 套件文件。

下一步

下列範例示範與 Azure 通知中樞互動的各種方式：

裝置管理：

安裝 API
- Create 或更新安裝
- 更新安裝
註冊 API

傳送作業：

管理工作：

參與

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

本課程模組的測試是即時和單元測試的混合，需要您擁有 Azure 通知中樞實例。若要執行測試，您必須執行：

rush update
rush build -t @azure/notification-hubs
Create 資料夾中具有這些內容的 sdk\notificationhubs\notification-hubs .env 檔案：NOTIFICATIONHUBS_CONNECTION_STRING=connection string for your Notification Hubs instanceNOTIFICATION_HUB_NAME=Notification Hub name
cd sdk\notificationhubs\notification-hubs
rushx test.

如需詳細資訊，請檢視測試資料夾。

曝光數

共用方式為

適用於 JavaScript 的 Azure 通知中樞 SDK

開始使用

目前支援的環境

安裝套件

必要條件

Create Azure 通知中樞資源

匯入用戶端

驗證用戶端

重要概念

裝置管理

安裝 API

註冊 API

傳送作業

廣播傳送

直接傳送

物件傳送

排程傳送

疑難排解

React Native支援

診斷已捨棄的通知

記錄

下一步

參與

其他資源

共用方式為

適用於 JavaScript 的 Azure 通知中樞 SDK

開始使用

目前支援的環境

安裝套件

必要條件

Create Azure 通知中樞資源

匯入用戶端

驗證用戶端

重要概念

裝置管理

安裝 API

註冊 API

傳送作業

廣播傳送

直接傳送

物件傳送

排程傳送

疑難排解

React Native支援

診斷已捨棄的通知

記錄

下一步

參與

相關專案

其他資源