用于 JavaScript 的 Azure 通信普通客户端库
这个包包含了Azure通信服务库的通用代码.
开始
先决条件
- 一个 Azure 订阅。 。 。 .
- 现有通信服务资源。 如果您需要创建资源, 您可以使用 Azure 门户,则 Azure 动力壳,或 阿苏尔CLI。 。 。 .
- 安装了 @azure/ 身份包 .
安装
npm install @azure/communication-common
npm install @azure/identity
浏览器支持
Java 脚本套装
要在浏览器中使用此客户端库,首先需要使用捆绑器. 关于如何做到这一点的详情,请参见我们 捆绑文件。 。 。 .
关键概念
信用通讯和Azure通讯 证书
这个 CommunicationTokenCredential 是一个用于认证用户与通信服务的接口,例如聊天或呼叫.
这个 AzureCommunicationTokenCredential 提供了一种方便的方法来创建执行上述接口的证书,并允许您利用内置的自动更新逻辑.
根据你的情况,你可能想要初始化 AzureCommunicationTokenCredential 改为:
- 静态符号(适用于短寿命客户端,例如发送一次性聊天信息)或
- 一个可确保通信中持续认证状态的回调功能(理想的,如长调会话).
- 能够获取 Entra 用户令牌的证书。 您可以提供执行 Token 证书界面。它适合需要Entra用户访问令牌与通信服务进行认证的情况.
给 AzureCommunicationTokenCredential 可以通过构建器或通过符号再生回调,可以通过Azure通信身份库获得.
实例
用静态符号创建证书
对于寿命短的客户来说,到期后刷新信使是不必要的,而且 AzureCommunicationTokenCredential 可能用静态符号进行即时处理.
import { AzureCommunicationTokenCredential } from "@azure/communication-common";
const tokenCredential = new AzureCommunicationTokenCredential(
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
);
创建带有召回的证书
在这里,我们假设我们有一个功能 fetchTokenFromMyServerForUser 以获取 JWT 符号字符串。 我们把它传到证书 给鲍勃从自己的服务器取个信物 我们的服务器会使用 Azure 通讯身份库 来发行信使。 有必要让 fetchTokenFromMyServerForUser 函数返回一个有效的符号(在未来设定了过期日期).
import { AzureCommunicationTokenCredential } from "@azure/communication-common";
function fetchTokenFromMyServerForUser(user: string): Promise<string> {
// Your custom implementation to fetch a token for the user
return Promise.resolve("some-unique-token-for-" + user);
}
const tokenCredential = new AzureCommunicationTokenCredential({
tokenRefresher: async () => fetchTokenFromMyServerForUser("[email protected]"),
});
创建具有主动更新的证书
设置 refreshProactively {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}真的会叫你的 tokenRefresher 当符号接近过期时,函数.
import { AzureCommunicationTokenCredential } from "@azure/communication-common";
function fetchTokenFromMyServerForUser(user: string): Promise<string> {
// Your custom implementation to fetch a token for the user
return Promise.resolve("some-unique-token-for-" + user);
}
const tokenCredential = new AzureCommunicationTokenCredential({
tokenRefresher: async () => fetchTokenFromMyServerForUser("[email protected]"),
refreshProactively: true,
});
创建具有主动更新和初始符号的证书
通过 initialToken 是一个可选的优化以跳过第一个调用到 tokenRefresher。您可以使用此工具将启动器与您的应用程序与随后的符号刷新周期区分开来.
import { AzureCommunicationTokenCredential } from "@azure/communication-common";
function fetchTokenFromMyServerForUser(user: string): Promise<string> {
// Your custom implementation to fetch a token for the user
return Promise.resolve("some-unique-token-for-" + user);
}
const tokenCredential = new AzureCommunicationTokenCredential({
tokenRefresher: async () => fetchTokenFromMyServerForUser("[email protected]"),
refreshProactively: true,
token:
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
});
为加密或不透明的访问令牌创建证书
一些访问令牌——如发给企业Entra用户的令牌——是加密的,无法在客户端上解码,因此证书无法读取其过期. 建议的办法是返回 AccessToken (单位:千美元){ token, expiresOnTimestamp }从你的 tokenRefresher (或通过一个作为初始) token),设置 expiresOnTimestamp 从符号响应的 expires_in。这保持了主动更新时间安排的准确性.
import { AzureCommunicationTokenCredential } from "@azure/communication-common";
// Some access tokens (e.g. for enterprise Entra users) are encrypted and cannot be
// decoded on the client. Return an AccessToken with an explicit expiry so proactive
// refresh scheduling stays accurate; derive expiresOnTimestamp from the response's expires_in.
async function fetchEncryptedTokenForUser(user: string): Promise<{
token: string;
expiresOnTimestamp: number;
}> {
const response = { token: "some-encrypted-token-for-" + user, expiresInSeconds: 8 * 60 * 60 };
return {
token: response.token,
expiresOnTimestamp: Date.now() + response.expiresInSeconds * 1000,
};
}
const tokenCredential = new AzureCommunicationTokenCredential({
tokenRefresher: async () => fetchEncryptedTokenForUser("[email protected]"),
refreshProactively: true,
});
如果你只能提供符号字符串,证书人会接受它并假设一个倒置寿命. 设定 undecodableTokenExpiryIntervalInSeconds 这样它们就不会比需要的更频繁地被刷新; 它默认为600秒.
import { AzureCommunicationTokenCredential } from "@azure/communication-common";
function fetchOpaqueTokenForUser(user: string): Promise<string> {
// Your custom implementation returns an opaque token string that can't be decoded.
return Promise.resolve("some-opaque-token-for-" + user);
}
const tokenCredential = new AzureCommunicationTokenCredential({
tokenRefresher: async () => fetchOpaqueTokenForUser("[email protected]"),
refreshProactively: true,
// When the token can't be decoded and no explicit expiry is provided, assume this
// lifetime (in seconds) instead of the 600s default — set it to your tokens' real lifetime.
undecodableTokenExpiryIntervalInSeconds: 3600,
});
以能够获取 Entra 用户令牌的证书创建证书
对于Entra用户可用于通信服务的情景,您需要初始化任何执行 Token 证书界面 并提供给 EntraCommunicationTokenCredentialOptions。 。 。 .
在此同时, 您必须提供 Azure 通信服务的 URI 资源以及 Entra 用户代号所需的范围 。 这些范围决定了给令牌的许可.
这种方法需要用于授权一个持有Teams许可证的Entra用户通过你的Azure通信服务资源使用Teams Phone扩展功能.
这需要提供 https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls 范围。 对于海合会云环境,使用 https://auth.msft.communication.azure.us/TeamsExtension.ManageCalls。 。 。 .
import { InteractiveBrowserCredential } from "@azure/identity";
import {
EntraCommunicationTokenCredentialOptions,
AzureCommunicationTokenCredential,
} from "@azure/communication-common";
const options = {
tenantId: "<your-tenant-id>",
clientId: "<your-client-id>",
redirectUri: "<your-redirect-uri>",
};
const entraTokenCredential = new InteractiveBrowserCredential(options);
const entraTokenCredentialOptions: EntraCommunicationTokenCredentialOptions = {
resourceEndpoint: "https://<your-resource>.communication.azure.com",
tokenCredential: entraTokenCredential,
scopes: ["https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls"],
};
const credential = new AzureCommunicationTokenCredential(entraTokenCredentialOptions);
Entra用户利用Azure通信服务的其他设想方案目前处于 仅预览阶段,不应用于生产。 。 。 .
这些设想方案的范围遵循格式 https://communication.azure.com/clients/<ACS Scope>如果不提供特定范围,默认范围将被设定为 https://communication.azure.com/clients/.default。 。 。 .
import { InteractiveBrowserCredential } from "@azure/identity";
import {
EntraCommunicationTokenCredentialOptions,
AzureCommunicationTokenCredential,
} from "@azure/communication-common";
const options = {
tenantId: "<your-tenant-id>",
clientId: "<your-client-id>",
redirectUri: "<your-redirect-uri>",
};
const entraTokenCredential = new InteractiveBrowserCredential(options);
const entraTokenCredentialOptions: EntraCommunicationTokenCredentialOptions = {
resourceEndpoint: "https://<your-resource>.communication.azure.com",
tokenCredential: entraTokenCredential,
scopes: ["https://communication.azure.com/clients/VoIP"],
};
const credential = new AzureCommunicationTokenCredential(entraTokenCredentialOptions);
解决问题
- 指定无效的符号:确保你传递给
AzureCommunicationTokenCredential构造器或tokenRefresher召回是一个赤裸的JWT符号字符串. 例如,如果你在使用 Azure 通信身份图书馆 或者说 (原始内容存档于2013-10-12) (英语). REST API 保证你刚刚通过token部分响应对象.
日志
允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 AZURE_LOG_LEVEL 环境变量改为 info。或者,可以在运行时拨打 setLogLevel 输入 @azure/logger数字 :
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
今后的步骤
捐款
如果您想为图书馆捐钱 请读一下 贡献指南 学习如何构建和测试密码.