Partager via

Bibliothèque cliente Azure Communication Administration pour JavaScript - version 1.0.0-beta.3

  • Article

La bibliothèque d’administration est utilisée pour la gestion des utilisateurs et des jetons pour Azure Communication Services. Cette bibliothèque fournit également des fonctionnalités pour l’administration des numéros de téléphone.

Les numéros de téléphone acquis peuvent être fournis avec de nombreuses fonctionnalités, selon le pays, le type de numéro et le forfait téléphonique. L’utilisation entrante et sortante de SMS, l’utilisation RTC entrante et sortante sont des exemples de fonctionnalités. Les numéros de téléphone peuvent également être attribués à un bot via une URL de webhook.

Prise en main

Prérequis

Installation de

npm install @azure/communication-administration

Concepts clés

Clients

Le package d’administration expose deux clients. Fournit CommunicationIdentityClient des méthodes pour gérer les utilisateurs et leurs jetons. Fournit PhoneNumberAdministrationClient des méthodes pour gérer les forfaits téléphoniques et les numéros.

Vue d’ensemble des forfaits téléphoniques

Les forfaits téléphoniques sont de deux types ; Géographique et gratuit. Les forfaits de téléphonie géographique sont des forfaits de téléphone associés à un emplacement, dont les codes régionaux des numéros de téléphone sont associés à l’indicatif régional d’un emplacement géographique. Toll-Free forfaits téléphoniques sont des forfaits téléphoniques qui ne sont pas associés à l’emplacement. Par exemple, aux États-Unis, les numéros gratuits peuvent être fournis avec des indicatifs régionaux tels que 800 ou 888.

Tous les forfaits de téléphonie géographique dans le même pays sont regroupés dans un groupe de forfaits téléphoniques avec un type de numéro de téléphone géographique. Tous les Toll-Free forfaits téléphoniques dans le même pays sont regroupés dans un groupe de forfaits téléphoniques.

Recherche et acquisition de nombres

Les numéros de téléphone peuvent être recherchés via l’API de création de recherche en fournissant un ID de forfait téléphonique, un indicatif régional et une quantité de numéros de téléphone. La quantité de numéros de téléphone fournie sera réservée pendant dix minutes. Cette recherche de numéros de téléphone peut être annulée ou achetée. Si la recherche est annulée, les numéros de téléphone deviennent disponibles pour d’autres personnes. Si la recherche est achetée, les numéros de téléphone sont acquis pour les ressources Azure.

Configuration et affectation de numéros

Les numéros de téléphone peuvent être attribués à une URL de rappel via l’API configurer le numéro. Dans le cadre de la configuration, vous aurez besoin d’un numéro de téléphone, d’une URL de rappel et d’un ID d’application acquis.

Exemples

Authentification

Vous pouvez obtenir une clé et/ou une chaîne de connexion à partir de votre ressource Communication Services dans le portail Azure. Une fois que vous avez une clé, vous pouvez authentifier et CommunicationIdentityClientPhoneNumberAdministrationClient avec l’une des méthodes suivantes :

Créer KeyCredential avec AzureKeyCredential avant d’initialiser le client

import { AzureKeyCredential } from "@azure/core-auth";
import { CommunicationIdentityClient } from "@azure/communication-administration";

const credential = new AzureKeyCredential(KEY);
const client = new CommunicationIdentityClient(HOST, credential);

A l'aide d'une chaîne de connexion

import { PhoneNumberAdministrationClient } from "@azure/communication-administration";

const connectionString = `endpoint=HOST;accessKey=KEY`;
const client = new CommunicationIdentityClient(connectionString);

Si vous utilisez une clé pour initialiser le client, vous devez également fournir le point de terminaison approprié. Vous pouvez obtenir ce point de terminaison à partir de votre ressource Communication Services dans le portail Azure.

Utilisation

CommunicationIdentityClient

Création d’une instance de CommunicationIdentityClient

import { CommunicationIdentityClient } from "@azure/communication-administration";

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Création d’un utilisateur

Utilisez la createUser méthode pour créer un utilisateur.

const user = await client.createUser();

Création et actualisation d’un jeton utilisateur

Utilisez la issueToken méthode pour émettre ou actualiser un jeton pour un utilisateur existant. La méthode accepte également une liste d’étendues de jetons de communication. Les options d’étendue sont les suivantes :

  • chat (Conversation)
  • pstn (Réseau téléphonique commuté public)
  • voip (Voix sur IP)
let { token } = await client.issueToken(user, ["chat"]);

Pour actualiser le jeton utilisateur, émettez un autre jeton avec le même utilisateur.

{ token } = await client.issueToken(user, ["chat"]);

Révocation de jetons pour un utilisateur

Utilisez la revokeTokens méthode pour révoquer tous les jetons émis d’un utilisateur.

await client.revokeTokens(user);

revokeTokens prend un deuxième argument facultatif, tokensValidFrom. Si cette date est fournie, revokeTokens révoque tous les jetons émis avant elle. Dans le cas contraire, tous les jetons seront révoqués.

Suppression d'un utilisateur

Utilisez la deleteUser méthode pour supprimer un utilisateur.

await client.deleteUser(user);

PhoneNumberAdministrationClient

Création d’une instance de PhoneNumberAdministrationClient

import { CommunicationIdentityClient } from "@azure/communication-administration";

const client = new CommunicationIdentityClient(CONNECTION_STRING);

Obtenir des pays

Utilisez la listSupportedCountries méthode pour obtenir la liste des pays pris en charge.

const countries = await client.listSupportedCountries();

for await (const country of countries) {
  console.log(`Country code: ${country.countryCode}`);
  console.log(`Country name: ${country.localizedName}`);
}

Obtention de groupes de plans téléphoniques

Les groupes de forfait téléphonique sont de deux types, Géographique et Gratuit. Utilisez la listPhonePlanGroups méthode pour les obtenir.

const countryCode = "US";
const phonePlanGroups = await client.listPhonePlanGroups(countryCode);

for await (const phonePlanGroup of phonePlanGroups) {
  console.log(`Phone plan group id: ${phonePlanGroup.phonePlanGroupId}`);
}

Obtention des options d’emplacement

Pour les forfaits de téléphonie géographique, vous pouvez interroger les emplacements géographiques disponibles. Les options d’emplacements sont structurées comme la hiérarchie géographique d’un pays. Par exemple, les États-Unis ont des états et dans chaque état sont des villes.

Utilisez la getPhonePlanLocationOptions méthode pour obtenir les options d’un emplacement.

const { locationOptions } = await client.getPhonePlanLocationOptions({
  countryCode: "US",
  phonePlanGroupId: "phonePlanGroupId",
  phonePlanId: "phonePlanId"
});

console.log(`Got location options for: ${locationOptions.labelId}`);

Obtention d’indicatifs régionaux

L’extraction d’indicatifs régionaux pour les plans téléphoniques géographiques nécessite l’ensemble des requêtes d’options d’emplacement. Vous devez inclure la chaîne d’emplacements géographiques qui traverse l’objet options d’emplacement retourné par .getPhonePlanLocationOptions

Utilisez la getAreaCodes méthode pour obtenir les codes régionaux pour les plans de téléphonie géographique.

const { primaryAreaCodes } = await client.getAreaCodes({
  locationType: "selection",
  countryCode: "US",
  phonePlanId: "phonePlanId",
  locationOptionsQueries
});

Réservation des numéros de téléphone pour l’achat

Utilisez la beginReservePhoneNumbers méthode pour rechercher des numéros de téléphone et les réserver. Cette opération est longue.

const reservePoller = await client.beginReservePhoneNumbers({
    name: "Phone number search 800",
    description: "Search for 800 phone numbers"
    phonePlanIds: ["phone-plan-id-1"],
    areaCode: "800",
    quantity: 3
});

Pour obtenir les résultats de la réservation, utilisez la pollUntilDone méthode sur le polleur que vous avez créé.

const phoneNumberReservation = await reservePoller.pollUntilDone();

Vous pouvez annuler l’interrogation et la réservation en appelant la cancelOperation méthode sur le polleur que vous avez créé.

await reservePoller.cancelOperation();

Achat de numéros de téléphone à partir d’une réservation

Utilisez la beginPurchasePhoneNumbers méthode pour acheter les numéros de téléphone de votre réservation. Le reservationId retourné à partir de beginReservePhoneNumbers est obligatoire. beginPurchasePhoneNumbers est également une opération de longue durée.

const { reservationId } = phoneNumberReservation;
const purchasePoller = await client.beginPurchasePhoneNumbers(reservationId);

Pour obtenir les résultats de l’achat, utilisez la méthode sur le pollUntilDone polleur d’achat que vous avez créé.

const results = await purchasePoller.pollUntilDone();

Dépannage

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions