다음을 통해 공유

JavaScript용 Azure Communication Phone Numbers 클라이언트 라이브러리 - 버전 1.0.0

  • 아티클

전화 번호 라이브러리는 전화 번호 관리를 위한 기능을 제공합니다.

구매한 전화 번호는 국가, 번호 유형 및 할당 유형에 따라 많은 기능을 사용할 수 있습니다. 기능의 예로는 SMS 인바운드 및 아웃바운드 사용, PSTN 인바운드 및 아웃바운드 사용이 있습니다. 웹후크 URL을 통해 전화 번호를 봇에 할당할 수도 있습니다.

시작

사전 요구 사항

  • Azure 구독.
  • 기존 Communication Services 리소스입니다. 리소스를 만들어야 하는 경우 Azure Portal, Azure PowerShell 또는 Azure CLI를 사용할 수 있습니다.

설치

npm install @azure/communication-phone-numbers

브라우저 지원

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서를 참조하세요.

주요 개념

전화 번호 패키지는 전화 번호를 관리하는 방법을 제공하는 을 노출 PhoneNumbersClient 합니다.

전화 번호 유형

전화 번호는 두 가지 유형으로 제공됩니다. 지리적 및 무료. 지리적 전화 번호는 지역 코드가 지리적 위치의 지역 코드와 연결된 위치와 연결된 전화 번호입니다. Toll-Free 전화 번호는 위치와 연결되지 않습니다. 예를 들어 미국에서는 무료 번호에 800 또는 888과 같은 지역 번호가 함께 제공 될 수 있습니다.

동일한 국가 내의 모든 지리적 전화 번호는 지리적 전화 번호 유형이 있는 전화 요금제 그룹으로 그룹화됩니다. 동일한 국가 내의 모든 Toll-Free 전화 번호는 전화 요금제 그룹으로 그룹화됩니다.

숫자 검색 및 획득

전화 번호 유형(지리적 또는 무료), 할당 유형(사람 또는 응용 프로그램), 통화 및 sms 기능, 지역 코드 및 전화 번호 수량을 제공하여 검색 생성 API를 통해 전화 번호를 검색할 수 있습니다. 제공된 전화 번호 수량은 15분 동안 예약됩니다. 이 전화 번호 검색은 취소하거나 구입할 수 있습니다. 검색이 취소되면 다른 사용자가 전화 번호를 사용할 수 있게 됩니다. 검색을 구매한 경우 Azure 리소스에 대한 전화 번호를 가져옵니다.

전화 번호 구성

전화 번호에는 기능의 조합이 있을 수 있습니다. 인바운드 및/또는 아웃바운드 통화를 지원하도록 구성하거나 통화에 전화 번호를 사용하지 않을 경우 둘 다 구성할 수 없습니다. SMS 기능도 마찬가지입니다.

전화 번호의 할당 유형을 고려하는 것이 중요합니다. 일부 기능은 특정 할당 유형으로 제한됩니다.

예

인증

Communication Services API에 액세스하는 클라이언트 개체를 만들려면 Communication Services 리소스 credential및 의 또는 endpoint 이 필요합니다connection string. 전화 번호 클라이언트는 Azure Active Directory 자격 증명 또는 API 키 자격 증명을 사용하여 인증할 수 있습니다.

Azure Portal의 Communication Services 리소스에서 키 및/또는 연결 문자열을 가져올 수 있습니다. Azure Portal에서 Communication Services 리소스에 대한 엔드포인트를 찾을 수도 있습니다.

키가 있으면 다음 방법 중 원하는 방법으로 를 인증 PhoneNumbersClient 할 수 있습니다.

연결 문자열 사용

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

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

와 함께 액세스 키 사용 AzureKeyCredential

키를 사용하여 클라이언트를 초기화하는 경우 적절한 엔드포인트도 제공해야 합니다. Azure Portal의 Communication Services 리소스에서 이 엔드포인트를 가져올 수 있습니다. 키와 엔드포인트가 있으면 다음 코드로 인증할 수 있습니다.

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);

Azure Active Directory 자격 증명 사용

연결 문자열 인증은 대부분의 예제에서 사용되지만 Azure ID 라이브러리를 사용하여 Azure Active Directory로 인증할 수도 있습니다. 아래에 표시된 DefaultAzureCredential 공급자 또는 Azure SDK와 함께 제공되는 다른 자격 증명 공급자를 사용하려면 패키지를 설치 @azure/identity 하세요.

npm install @azure/identity

패키지는 @azure/identity 애플리케이션에서 이 작업을 수행하는 데 사용할 수 있는 다양한 자격 증명 형식을 제공합니다. 에 대한 추가 정보는 시작하기 위한 @azure/identity 자세한 내용과 샘플을 제공합니다.

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

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

사용량

다음 섹션에서는 Azure Communication Services 전화 번호 클라이언트를 사용하는 몇 가지 일반적인 작업을 다루는 코드 조각을 제공합니다. 여기서 다루는 시나리오는 다음으로 구성됩니다.

사용 가능한 전화 번호 검색

메서드를 beginSearchAvailablePhoneNumbers 사용하여 전화 번호를 검색하고 예약합니다. 반환된 전화 번호는 15분 동안 예약되어 있으며 이 기간 동안 메서드에 을 searchIdbeginPurchasePhoneNumbers 제공하여 구매할 수 있습니다.

beginSearchAvailablePhoneNumbers 는 장기 실행 작업이며 폴러를 반환합니다.

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();

메서드를 beginPurchasePhoneNumbers 사용하여 검색에서 전화 번호를 구입합니다. 구매한 전화 번호는 클라이언트를 시작할 때 사용되는 Communication Services 리소스에 할당됩니다. 에서 beginSearchAvailablePhoneNumbers 반환된 가 searchId 필요합니다.

beginPurchasePhoneNumbers 는 장기 실행 작업이며 폴러를 반환합니다.

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();

구매한 전화 번호 해제

메서드를 beginReleasePhoneNumber 사용하여 이전에 구매한 전화 번호를 해제합니다. 릴리스된 전화 번호는 더 이상 Communication Services 리소스와 연결되지 않으며 다른 작업(예: )과 함께 사용할 수 없습니다. 리소스의 SMS) 해제되는 전화 번호가 필요합니다.

beginReleasePhoneNumber 는 장기 실행 작업이며 폴러를 반환합니다.

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();

전화 번호 기능 업데이트

메서드를 beginUpdatePhoneNumberCapabilities 사용하여 구매한 전화 번호의 기능을 업데이트합니다. 전화 번호는 인바운드 및/또는 아웃바운드 통화 및 sms를 지원하도록 구성할 수 있습니다.

beginUpdatePhoneNumberCapabilities 는 장기 실행 작업이며 폴러를 반환합니다.

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();

구매한 전화 번호 가져오기

메서드를 getPurchasedPhoneNumber 사용하여 구매한 전화 번호에 대한 정보를 가져옵니다. 이 정보에는 전화 번호의 유형, 기능, 비용 및 구매 날짜가 포함됩니다.

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();

구매한 전화 번호 나열

메서드를 listPurchasedPhoneNumbers 사용하여 구매한 모든 전화 번호를 페이징합니다.

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();

문제 해결

다음 단계

이 라이브러리를 사용하는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

Impressions