Context Hub 精选文档解读：Azure Notification Hubs JavaScript SDK（@azure/notification-hubs 2.0.2）接入实战-开发者社区

【免费下载链接】context-hub

项目地址：https://gitcode.com/gh_mirrors/co/context-hub

本指南以 content/azure/docs/notification-hubs/javascript/DOC.md 为核心，系统讲解如何用@azure/notification-hubs2.0.2 完成 Azure 通知中心的>npm install @azure/notification-hubs@2.0.2

该包使用 Notification Hubs 的连接字符串（connection string）进行认证，而不是 Microsoft Entra 凭据。因此，本文展示的工作流不需要额外引入@azure/identity。如果你看到某些旧示例同时引入了@azure/identity和@azure/notification-hubs，请确认它们是否真的用于其他认证场景，本 SDK 的数据面调用以连接字符串为准。

前置条件与初始化配置

在代码能够发送通知或注册设备之前，你必须在 Azure 侧先准备好以下资源：

一个 Azure Notification Hubs 命名空间（namespace）与通知中心（hub）——这是资源级前提，需在 Azure 订阅中创建；
在 hub 上配置好你将使用的推送平台凭据，例如 APNS 或 FCM——SDK 无法替你在 hub 侧补齐平台配置，这是发送成功的硬性前置；
一个权限与代码工作内容匹配的 hub 连接字符串——连接字符串中的 SharedAccessKeyName 对应的策略（policy）决定你能执行哪些操作。

推荐通过环境变量注入这些敏感配置，避免硬编码：

export AZURE_NOTIFICATION_HUB_CONNECTION_STRING="Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<policy>;SharedAccessKey=<key>" export AZURE_NOTIFICATION_HUB_NAME="my-notification-hub" # Example device tokens for app-side registration workflows export APNS_DEVICE_TOKEN="<ios-device-token>" export FCM_DEVICE_TOKEN="<android-device-token>"

三个关键概念务必区分清楚：

连接字符串（connection string）：认证 SDK 调用本身，告诉 SDK 如何向 Notification Hubs 服务认证；
hub 名称（hub name）：告诉 SDK 要操作哪个通知中心；
设备令牌 / 推送通道（device token / push channel）：在 APNS、FCM、WNS 等推送平台内部标识目标设备。

客户端初始化：createClientContext

创建一个共享的客户端上下文，并在相关操作中复用，而不是每次调用都重新构造：

import { createClientContext } from "@azure/notification-hubs"; const connectionString = process.env.AZURE_NOTIFICATION_HUB_CONNECTION_STRING; const hubName = process.env.AZURE_NOTIFICATION_HUB_NAME; if (!connectionString || !hubName) { throw new Error( "AZURE_NOTIFICATION_HUB_CONNECTION_STRING and AZURE_NOTIFICATION_HUB_NAME are required", ); } export const context = createClientContext(connectionString, hubName);

createClientContext(connectionString, hubName)接收连接字符串与 hub 名称两个参数，返回一个可复用的上下文对象。安装管理、注册和发送操作都应共享同一个 context，这既减少了重复初始化开销，也避免连接字符串在代码中散落多处。

核心工作流一：管理安装（Installation）

对于新代码，优先使用 Installation（安装）模型作为设备注册方式。一个 Installation 将以下信息绑定在一起：

你应用的安装标识符（installation identifier）；
平台推送通道（push channel）；
之后用于定向分发的标签（tags）。

这种"一体式"记录便于在设备令牌变化时原地更新（upsert），而无需在应用逻辑中维护令牌与标签的映射。

创建或更新安装：createOrUpdateInstallation

无论设备首次注册，还是其推送令牌发生轮换，都应调用createOrUpdateInstallation(...)：

import { createClientContext, createOrUpdateInstallation, } from "@azure/notification-hubs"; const context = createClientContext( process.env.AZURE_NOTIFICATION_HUB_CONNECTION_STRING, process.env.AZURE_NOTIFICATION_HUB_NAME, ); const installation = { installationId: "user-42-ios", platform: "apns", pushChannel: process.env.APNS_DEVICE_TOKEN, tags: ["user:42", "tenant:acme", "ios"], }; await createOrUpdateInstallation(context, installation);

该对象中关键字段的语义如下：

字段	作用
`installationId`	应用安装的稳定标识符，建议使用与业务绑定的稳定 ID（如`user-42-ios`），用于后续读取、更新与删除
`platform`	该设备所属的推送平台，如`apns`、`fcm`等
`pushChannel`	当前从推送平台获取的设备令牌或通道标识（如 APNS device token）
`tags`	可选的定向标签，后续可在`tagExpression`中引用

createOrUpdateInstallation是幂等的 upsert 语义：同一installationId重复调用即更新，这正是设备令牌变化时"原地更新"的基础。

读取或删除安装：getInstallation / deleteInstallation

import { createClientContext, deleteInstallation, getInstallation, } from "@azure/notification-hubs"; const context = createClientContext( process.env.AZURE_NOTIFICATION_HUB_CONNECTION_STRING, process.env.AZURE_NOTIFICATION_HUB_NAME, ); const installationId = "user-42-ios"; const installation = await getInstallation(context, installationId); console.log(installation.installationId, installation.tags); await deleteInstallation(context, installationId);

在以下场景应删除安装：用户永久注销、用户关闭通知权限、或你确定该应用安装不应再接收推送时。删除后，该设备将不再出现在任何发送目标中。

核心工作流二：发送通知（sendNotification）

sendNotification(...)通过 Notification Hubs 发送平台载荷：

如果不提供任何定向选项，通知将以**广播（broadcast）**方式发送给 hub 中所有匹配平台的注册设备；
如果提供tagExpression，通知将变为**定向（targeted）**发送，仅投递给满足标签表达式的设备。

注意一个关键事实：body内的载荷必须与你发送的目标推送平台匹配。Notification Hubs 只负责路由载荷，但APNS 仍然期望 APNS JSON 格式，FCM 仍然期望 FCM JSON 格式，SDK 不会替你转换平台载荷。

向标签表达式发送 APNS 通知

import { createAppleNotification, createClientContext, sendNotification, } from "@azure/notification-hubs"; const context = createClientContext( process.env.AZURE_NOTIFICATION_HUB_CONNECTION_STRING, process.env.AZURE_NOTIFICATION_HUB_NAME, ); const notification = createAppleNotification({ body: JSON.stringify({ aps: { alert: { title: "Order shipped", body: "Tap to track package 12345", }, sound: "default", }, orderId: "12345", }), }); await sendNotification(context, notification, { tagExpression: "user:42", });

示例中：

createAppleNotification({ body })是 APNS 平台的载荷构造器，body内是完整的 APNS JSON（aps键及其alert、sound子字段），同时可携带自定义业务字段（如orderId）；
sendNotification(context, notification, { tagExpression: "user:42" })将通知仅发送给打了user:42标签的设备。

发送 FCM v1 通知

import { createClientContext, createFcmV1Notification, sendNotification, } from "@azure/notification-hubs"; const context = createClientContext( process.env.AZURE_NOTIFICATION_HUB_CONNECTION_STRING, process.env.AZURE_NOTIFICATION_HUB_NAME, ); const notification = createFcmV1Notification({ body: JSON.stringify({ message: { notification: { title: "Order shipped", body: "Tap to track package 12345", }, data: { orderId: "12345", }, }, }), }); await sendNotification(context, notification, { tagExpression: "tenant:acme && android", });

FCM v1 使用的是message.notification+message.data结构（区别于旧版 FCM 的notification顶层结构），createFcmV1Notification正是面向该结构的构造器。示例中的tagExpression: "tenant:acme && android"演示了复合标签表达式：同时满足租户标签tenant:acme与平台标签android的设备才会收到推送。

标签（Tags）与定向分发

标签是定向投递的核心手段——它让你在应用逻辑中无需维护原始推送令牌，即可定位设备子集。典型标签模式包括：

按用户：user:42
按租户：tenant:acme
按平台：ios、android
按功能或偏好：marketing-opt-in

标签配合tagExpression支持布尔组合（如tenant:acme && android）。使用标签时保持标签稳定且语义明确：当设备令牌轮换时，应在原安装上原地更新，而不是用新的installationId创建新安装——除非应用安装本身发生了变化（例如用户卸载重装产生的新安装实例）。

Registrations（注册）与 Installations（安装）如何选择

Notification Hubs 同时支持：

Legacy registrations（传统注册模型）：较旧的一对一注册记录；
Installation（安装模型）：较新的推荐模型，将设备身份、标签与模板元数据绑定到单条可 upsert 的记录。

对于新的 JavaScript 集成，优先使用 Installation，除非你正在维护已有的基于 registration 的旧流程。这一选择的核心收益正如前文所述：当推送通道变化时，设备身份、标签和模板元数据都绑定在同一条 installation 记录上，一次createOrUpdateInstallation即可完成原地更新，避免"令牌变了、标签丢了"的不一致问题。

实战注意点（Practical Notes）

将 hub 连接字符串保存在服务端密钥存储或环境变量中，绝不能放进浏览器代码或移动端应用包内；
在发送之前，务必先在 hub 上配置好 APNS、FCM、WNS 等平台凭据——SDK 无法弥补 hub 侧平台配置缺失的问题；
在相关操作间复用同一个createClientContext(...)的结果；
每当底层设备令牌变化时，更新对应的 installation；
尽可能使用范围受限的 SAS 策略（如仅Listen/Send权限），而不是宽泛的管理凭据。这一点与管理面文档 content/azure/docs/mgmt-notificationhubs/python/DOC.md 中的建议一致：面向设备或应用侧的代码，权限越窄越好。

常见陷阱（Common Pitfalls）

把这个包当作 Azure Resource Manager SDK 去预置命名空间或 hub——这是数据面/管理面职责混淆的典型错误；
把 APNS 载荷发给 Android 设备、或把 FCM 载荷发给 Apple 设备——平台载荷格式必须匹配目标平台；
在调用sendNotification(...)之前忘记在通知中心配置平台凭据；
在公开的前端代码中暴露 Notification Hubs 连接字符串；
每次设备令牌变化都创建新的 installation ID，而不是更新现有安装。

2.0.2 版本注意事项

本指南针对@azure/notification-hubs2.0.2；
新应用代码应围绕createClientContext(...)、安装管理和平台专属通知构造器（如createAppleNotification、createFcmV1Notification）展开；
如果你正在维护基于旧 registration 的示例，在把它们搬进新代码之前，务必仔细映射到当前顶层 API（top-level operations）——旧示例中的函数签名与行为可能已发生变化。

如何在本仓库中获取与检索该文档

本仓库是 Context Hub——为编码 Agent 提供精选、带版本号、按语言区分的文档集合。本文对应的原始文档位于 content/azure/docs/notification-hubs/javascript/DOC.md，其 frontmatter 声明了name: notification-hubs、languages: javascript、versions: 2.0.2、source: maintainer，标签为azure,notification-hubs,push-notifications,javascript,apns,fcm,installations。

按照 docs/content-guide.md 描述的目录规范（author/docs/entry-name/language/DOC.md），该文档对应内容 ID 为azure/notification-hubs的 JavaScript 语言变体。Agent 或开发者可使用chubCLI 拉取它：

chub get azure/notification-hubs --lang js

也可用--version 2.0.2锁定文档对应的 SDK 版本。完整的 CLI 用法（--lang、--version、--full、--file等）参见 docs/cli-reference.md。管理面（预置命名空间、hub、凭据）的内容则由 content/azure/docs/mgmt-notificationhubs/python/DOC.md 覆盖。