Partager via

Bibliothèque cliente Azure Communication Phone Numbers pour JavaScript - version 1.5.0

La bibliothèque de numéros de téléphone fournit des fonctionnalités pour l’administration des numéros de téléphone.

Les numéros de téléphone achetés peuvent être fournis avec de nombreuses fonctionnalités, en fonction du pays, du type de numéro et du type d’affectation. Voici quelques exemples de fonctionnalités : utilisation entrante et sortante sms, utilisation entrante RTC et sortante. Les numéros de téléphone peuvent également être attribués à un bot via une URL de webhook.

Commencer

Conditions préalables

  • Un abonnement Azure .
  • Ressource Communication Services existante. Si vous devez créer la ressource, vous pouvez utiliser le portail Azure , le Azure PowerShellou le Azure CLI.

Installation

npm install @azure/communication-phone-numbers

Prise en charge du navigateur

Offre groupée JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

Concepts clés

Ce Kit de développement logiciel (SDK) fournit des fonctionnalités permettant de gérer facilement les nombres direct offer et direct routing.

Il direct offer existe trois types de numéros : géographique, Toll-Free et mobile. Les forfaits de téléphonie géographique et mobile sont des forfaits téléphoniques associés à un emplacement, dont les indicatifs régionaux des numéros de téléphone sont associés à l’indicatif régional d’un lieu géographique. Toll-Free les forfaits téléphoniques ne sont pas associés à l’emplacement. Par exemple, aux États-Unis, les numéros gratuits peuvent être fournis avec des codes de zone tels que 800 ou 888. Ils sont gérés à l’aide du PhoneNumbersClient

La fonctionnalité direct routing permet de connecter votre infrastructure de téléphonie existante à ACS. La configuration est gérée à l’aide de l'SipRoutingClient, qui fournit des méthodes pour configurer des jonctions SIP et des règles de routage vocal, afin de gérer correctement les appels pour votre sous-réseau de téléphonie.

Client numéros de téléphone

Types de numéros de téléphone

Il existe trois types de numéros de téléphone ; Géographique, Toll-Free et mobile. Toll-Free numéros ne sont pas associés à un lieu. Par exemple, aux États-Unis, les numéros gratuits peuvent être fournis avec des codes de zone tels que 800 ou 888. Les numéros de téléphone géographiques et mobiles sont des numéros de téléphone associés à un lieu.

Les types de numéros de téléphone du même pays sont regroupés dans un groupe de forfaits téléphoniques avec ce type de numéro de téléphone. Par exemple, tous les numéros de téléphone Toll-Free d’un 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 type de numéro de téléphone (géographique, gratuit ou mobile), un type d’attribution (personne ou application), des capacités d’appel et de SMS, un indicatif régional et un nombre de numéros de téléphone. La quantité fournie de numéros de téléphone sera réservée pendant 15 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 seront disponibles pour d’autres personnes. Si la recherche est achetée, les numéros de téléphone sont acquis pour la ressource Azure.

Configuration des numéros de téléphone

Les numéros de téléphone peuvent avoir une combinaison de fonctionnalités. Ils peuvent être configurés pour prendre en charge les appels entrants et/ou sortants, ni si vous n’utiliserez pas le numéro de téléphone pour appeler. La même chose s’applique aux fonctionnalités sms.

Il est important de prendre en compte le type d’affectation de votre numéro de téléphone. Certaines fonctionnalités sont limitées à un type d’affectation particulier.

Navigation et réservation de numéros de téléphone

Les API de navigation et de réservation offrent un autre moyen d’acquérir des numéros de téléphone via une expérience de type panier d’achat. Pour ce faire, l’opération de recherche, qui permet de trouver et de réserver des numéros à l’aide d’un seul objet de recherche de données, est divisée en deux étapes synchrones distinctes, Parcourir et Réservation.

L’opération de navigation récupère un échantillon aléatoire de numéros de téléphone disponibles à l’achat pour un pays donné, avec des critères de filtrage facultatifs pour affiner les résultats. Les numéros de téléphone retournés ne sont pas réservés à un quelconque client.

Les réservations représentent un ensemble de numéros de téléphone verrouillés par un client spécifique et en attente d’achat. Ils ont un délai d’expiration de 15 minutes après la dernière modification ou de 2 heures à compter de l’heure de création. Une réservation peut inclure des numéros de différents pays, contrairement à l’opération de recherche. Les clients peuvent créer, récupérer, modifier (en ajoutant et en supprimant des numéros), supprimer et acheter des réservations. L’achat d’une réservation est un LL.

Client de routage SIP

La fonctionnalité de routage direct permet de connecter l’infrastructure de téléphonie fournie par le client aux ressources de communication Azure. Pour configurer correctement la configuration du routage, le client doit fournir la configuration de jonction SIP et les règles de routage SIP pour les appels. Le client de routage SIP fournit l’interface nécessaire pour définir cette configuration.

Lorsqu’un appel est effectué, le système tente de faire correspondre le numéro de destination avec les modèles de nombres regex des itinéraires définis. La première route à mettre en correspondance le nombre sera sélectionnée. L’ordre des correspondances régulières est identique à l’ordre des itinéraires dans la configuration, par conséquent, l’ordre des itinéraires importe. Une fois qu’un itinéraire est mis en correspondance, l’appel est acheminé vers la première jonction de la liste des jonctions de l’itinéraire. Si la jonction n’est pas disponible, la jonction suivante dans la liste est sélectionnée.

Exemples

Authentification

Pour créer un objet client pour accéder à l’API Communication Services, vous aurez besoin d’un connection string ou du endpoint de votre ressource Communication Services et d’un credential. Le client Numéros de téléphone peut utiliser des informations d’identification Azure Active Directory ou des informations d’identification de clé API pour s’authentifier.

Vous pouvez obtenir une clé et/ou une chaîne de connexion à partir de votre ressource Communication Services dans le portail Azure . Vous pouvez également trouver le point de terminaison de votre ressource Communication Services dans le portail Azure .

Une fois que vous avez une clé, vous pouvez authentifier le client avec l’une des méthodes suivantes :

Utilisation d’une chaîne de connexion

import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(connectionString);

import { SipRoutingClient } from "@azure/communication-phone-numbers";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new SipRoutingClient(connectionString);

Utilisation d’une clé d’accès avec AzureKeyCredential

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 portail Azure. Une fois que vous avez une clé et un point de terminaison, vous pouvez vous authentifier avec le code suivant :

import { AzureKeyCredential } from "@azure/core-auth";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new AzureKeyCredential("<key-from-resource>");
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

import { AzureKeyCredential } from "@azure/core-auth";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new AzureKeyCredential("<key-from-resource>");
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

Utilisation d’informations d’identification Azure Active Directory

L’authentification par chaîne de connexion est utilisée dans la plupart des exemples, mais vous pouvez également vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque d’identités Azure . Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le package @azure/identity :

npm install @azure/identity

Le package @azure/identity fournit divers types d’informations d’identification que votre application peut utiliser pour ce faire. Le README pour @azure/identity fournit plus de détails et d’exemples pour vous aider à démarrer.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

Utilisation

Les sections suivantes fournissent des extraits de code qui couvrent certaines des tâches courantes à l’aide du client Numéros de téléphone Azure Communication Services. Les scénarios abordés ici sont les suivants :

PhoneNumbersClient

SipRoutingClient

PhoneNumbersClient

Rechercher des numéros de téléphone disponibles

Utilisez la méthode beginSearchAvailablePhoneNumbers pour rechercher des numéros de téléphone et les réserver. Les numéros de téléphone retournés sont réservés pendant 15 minutes et peuvent être achetés pendant cette période en fournissant la searchId à la méthode de beginPurchasePhoneNumbers.

beginSearchAvailablePhoneNumbers est une opération longue et retourne un polleur.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
  assignmentType: "application",
  capabilities: {
    sms: "outbound",
    calling: "none",
  },
  quantity: 1,
};

const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);

// The search is underway. Wait to receive searchId.
const searchResults = await searchPoller.pollUntilDone();
console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
console.log(`searchId: ${searchResults.searchId}`);

Utilisez la méthode beginPurchasePhoneNumbers pour acheter les numéros de téléphone à partir de votre recherche. Les numéros de téléphone achetés sont attribués à la ressource Communication Services utilisée lors du lancement du client. La searchId retournée par beginSearchAvailablePhoneNumbers est requise.

beginPurchasePhoneNumbers est une opération longue et retourne un polleur.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
  assignmentType: "application",
  capabilities: {
    sms: "outbound",
    calling: "none",
  },
  quantity: 1,
};

const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);

// The search is underway. Wait to receive searchId.
const { searchId, phoneNumbers } = await searchPoller.pollUntilDone();

const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumbers[0]}`);

Parcourez et réservez les numéros de téléphone disponibles

Utiliser l’API Parcourir et Réservations pour réserver un numéro de téléphone

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  BrowseAvailableNumbersRequest,
  AvailablePhoneNumber,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const browseAvailableNumberRequest: BrowseAvailableNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
};

const browseAvailableNumbers = await client.browseAvailablePhoneNumbers(
  browseAvailableNumberRequest,
  {
    capabilities: {
      calling: "outbound",
    },
    assignmentType: "application",
  },
);
const phoneNumbers = browseAvailableNumbers.phoneNumbers;
const phoneNumbersList = [phoneNumbers[0], phoneNumbers[1]];
const reservationResponse = await client.createOrUpdateReservation(
  {
    reservationId: "reservationId",
  },
  {
    add: phoneNumbersList,
  },
);
const numbersWithError: AvailablePhoneNumber[] = [];
for (const number of Object.values(reservationResponse.phoneNumbers || {})) {
  if (number != null && number.status === "error") {
    numbersWithError.push(number);
  }
}
if (numbersWithError.length > 0) {
  console.log("Errors occurred during reservation");
} else {
  console.log("Reservation operation completed without errors.");
}

Libérer un numéro de téléphone acheté

Utilisez la méthode beginReleasePhoneNumber pour libérer un numéro de téléphone précédemment acheté. Les numéros de téléphone publiés ne seront plus associés à la ressource Communication Services et ne seront pas disponibles pour une utilisation avec d’autres opérations (par exemple. SMS) de la ressource. Le numéro de téléphone en cours de publication est requis.

beginReleasePhoneNumber est une opération longue et retourne un polleur.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToRelease = "<phone-number-to-release>";

const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

// Release is underway.
await releasePoller.pollUntilDone();
console.log("Successfully release phone number.");

Mettre à jour les fonctionnalités de numéro de téléphone

Utilisez la méthode beginUpdatePhoneNumberCapabilities pour mettre à jour les fonctionnalités d’un numéro de téléphone acheté. Les numéros de téléphone peuvent être configurés pour prendre en charge les appels entrants et/ou sortants et les sms, ou aucun des deux.

beginUpdatePhoneNumberCapabilities est une opération longue et retourne un polleur.

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  PhoneNumberCapabilitiesRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToUpdate = "<phone-number-to-update>";

// This will update phone number to send and receive sms, but only send calls.
const updateRequest: PhoneNumberCapabilitiesRequest = {
  sms: "inbound+outbound",
  calling: "outbound",
};

const updatePoller = await client.beginUpdatePhoneNumberCapabilities(
  phoneNumberToUpdate,
  updateRequest,
);

// Update is underway.
const { capabilities } = await updatePoller.pollUntilDone();
console.log(`These are the update capabilities: ${capabilities}`);

Obtenir un numéro de téléphone acheté

Utilisez la méthode getPurchasedPhoneNumber pour obtenir des informations sur un numéro de téléphone acheté. Ces informations incluent le type, les fonctionnalités, le coût et la date d’achat du numéro de téléphone.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToGet = "<phone-number-to-get>";

const phoneNumber = await client.getPurchasedPhoneNumber(phoneNumberToGet);

console.log(`The id is the same as the phone number: ${phoneNumber.id}`);
console.log(`Phone number type is ${phoneNumber.phoneNumberType}`);

Réservation d’achat

Étant donné qu’il s’agit d’une réservation existante et active, achetez les numéros de téléphone de cette réservation.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const reservationId = "<reservation-id>";

const purchasePoller = await client.beginReservationPurchase(reservationId);

// Purchase is underway.
const purchaseResult = await purchasePoller.pollUntilDone();
console.log(`Successfully purchased phone numbers in reservation: ${reservationId}`);

Répertorier les numéros de téléphone achetés

Utilisez la méthode listPurchasedPhoneNumbers pour pager tous les numéros de téléphone achetés.

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumbers = client.listPurchasedPhoneNumbers();

for await (const phoneNumber of phoneNumbers) {
  console.log(`The id is the same as the phone number: ${phoneNumber.id}`);
  console.log(`Phone number type is ${phoneNumber.phoneNumberType}`);
}

SipRoutingClient

Récupérer des jonctions et des itinéraires SIP

Obtenez la liste des jonctions ou itinéraires actuellement configurés.

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

const trunks = client.listTrunks();
const routes = client.listRoutes();
for await (const trunk of trunks) {
  console.log(`Trunk ${trunk.fqdn}:${trunk.sipSignalingPort}`);
}

for await (const route of routes) {
  console.log(`Route ${route.name} with pattern ${route.numberPattern}`);
  console.log(`Route's trunks: ${route.trunks?.join()}`);
}

Remplacer les jonctions et itinéraires SIP

Remplacez la liste des jonctions ou itinéraires actuellement configurés par de nouvelles valeurs.

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.setTrunks([
  {
    fqdn: "sbc.one.domain.com",
    sipSignalingPort: 1234,
  },
  {
    fqdn: "sbc.two.domain.com",
    sipSignalingPort: 1234,
  },
]);

await client.setRoutes([
  {
    name: "First Route",
    description: "route's description",
    numberPattern: "^+[1-9][0-9]{3,23}$",
    trunks: ["sbc.one.domain.com"],
  },
  {
    name: "Second Route",
    description: "route's description",
    numberPattern: "^.*$",
    trunks: ["sbc.two.domain.com", "sbc.one.domain.com"],
  },
]);

Récupérer une jonction unique

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

const trunk = await client.getTrunk("sbc.one.domain.com");
if (trunk) {
  console.log(`Trunk ${trunk.fqdn}:${trunk.sipSignalingPort}`);
} else {
  console.log("Trunk not found");
}

Définir une jonction unique

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.setTrunk({
  fqdn: "sbc.one.domain.com",
  sipSignalingPort: 4321,
});

Supprimer une jonction unique

import { DefaultAzureCredential } from "@azure/identity";
import { SipRoutingClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new SipRoutingClient("<endpoint-from-resource>", credential);

await client.deleteTrunk("sbc.one.domain.com");

Dépannage

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentation du package@azure/enregistreur d’événements.

Étapes suivantes

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

Contribuant

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.

  • Last updated on