Partager via

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

  • Article

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, selon le pays, le type de numéro et le type d’affectation. 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-phone-numbers

Prise en charge des navigateurs

Ensemble JavaScript

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

Concepts clés

Le package de numéros de téléphone expose le PhoneNumbersClient qui fournit des méthodes pour gérer les numéros de téléphone.

Types de numéro de téléphone

Les numéros de téléphone sont de deux types ; Géographique et gratuit. Les numéros de téléphone géographiques sont des numéros de téléphone associés à un emplacement, dont les indicatifs régionaux sont associés à l’indicatif régional d’un emplacement géographique. Toll-Free numéros de téléphone ne sont pas associés à un 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 numéros de téléphone géographiques d’un même pays sont regroupés dans un groupe de forfait téléphonique avec un type de numéro de téléphone géographique. Tous les numéros de téléphone Toll-Free dans le même pays sont regroupés dans un groupe de forfait téléphonique.

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 ou gratuit), un type d’affectation (personne ou application), des fonctionnalités d’appel et de sms, 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 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 deviennent 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, ou non si vous n’utilisez pas le numéro de téléphone pour appeler. Il en est de même pour les 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.

Exemples

Authentification

Pour créer un objet client afin d’accéder à l’API Communication Services, vous aurez besoin d’un connection string ou 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 avec l’une PhoneNumbersClient des méthodes suivantes :

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

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

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new PhoneNumbersClient(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 le 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);

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 Azure Identity. 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 @azure/identity package :

npm install @azure/identity

Le @azure/identity package fournit divers types d’informations d’identification que votre application peut utiliser pour ce faire. LE FICHIER 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";

let credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<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 :

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

Utilisez la beginSearchAvailablePhoneNumbers méthode 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 à searchId la beginPurchasePhoneNumbers méthode .

beginSearchAvailablePhoneNumbers est une opération de longue durée et retourne un pollueur.

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

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

async function main() {
  const searchRequest = {
    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 = searchPoller.pollUntilDone();
  console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
  console.log(`searchId: ${searchResults.searchId}`);
}

main();

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

beginPurchasePhoneNumbers est une opération de longue durée et retourne un pollueur.

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

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

async function main() {
  const searchRequest = {
    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 } = searchPoller.pollUntilDone();

  const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

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

main();

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

Utilisez la beginReleasePhoneNumber méthode pour libérer un numéro de téléphone précédemment acheté. Les numéros de téléphone libéré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 libéré est obligatoire.

beginReleasePhoneNumber est une opération de longue durée et retourne un pollueur.

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

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

async function main() {
  const phoneNumberToRelease = "<phone-number-to-release>";

  const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

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

main();

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

Utilisez la beginUpdatePhoneNumberCapabilities méthode 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 et sms entrants et/ou sortants, ou aucun des deux.

beginUpdatePhoneNumberCapabilities est une opération de longue durée et retourne un pollueur.

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

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

async function main() {
  const phoneNumberToUpdate = "<phone-number-to-update>";

  // This will update phone number to send and receive sms, but only send calls.
  const updateRequest = {
    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}`);
}

main();

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

Utilisez la getPurchasedPhoneNumber méthode 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 { PhoneNumbersClient } from "@azure/communication-phone-numbers";

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

async main function() {
  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}`);
}

main();

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

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

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

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

async main function() {
  const phoneNumbers = await 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}`);
  }
}

main();

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