JavaScript용 Azure Communication Administration 클라이언트 라이브러리 - 버전 1.0.0-beta.3
관리 라이브러리는 Azure Communication Services 대한 사용자 및 토큰을 관리하는 데 사용됩니다. 이 라이브러리는 전화 번호 관리 기능도 제공합니다.
획득 한 전화 번호는 국가, 번호 유형 및 전화 요금제에 따라 많은 기능을 제공 할 수 있습니다. 기능의 예로는 SMS 인바운드 및 아웃바운드 사용, PSTN 인바운드 및 아웃바운드 사용이 있습니다. 웹후크 URL을 통해 전화 번호를 봇에 할당할 수도 있습니다.
시작
사전 요구 사항
- Azure 구독.
- 기존 Communication Services 리소스입니다. 리소스를 만들어야 하는 경우 Azure Portal 또는 Azure CLI를 사용할 수 있습니다.
설치
npm install @azure/communication-administration
주요 개념
클라이언트
관리 패키지는 두 클라이언트를 노출합니다. 는 CommunicationIdentityClient 사용자 및 해당 토큰을 관리하는 메서드를 제공합니다. 는 PhoneNumberAdministrationClient 전화 요금제 및 번호를 관리하는 방법을 제공합니다.
전화 요금 요금 개요
전화 플랜은 두 가지 유형으로 제공됩니다. 지리적 및 무료. 지리적 전화 플랜은 지리적 위치의 지역 코드와 연결된 전화 번호의 지역 번호가 있는 위치와 연결된 전화 요금입니다. Toll-Free 전화 플랜은 연결된 위치가 아닌 전화 요금입니다. 예를 들어 미국에서는 무료 번호에 800 또는 888과 같은 지역 번호가 함께 제공 될 수 있습니다.
동일한 국가 내의 모든 지리적 전화 요금제는 지리적 전화 번호 유형이 있는 전화 요금제 그룹으로 그룹화됩니다. 동일한 국가 내의 모든 Toll-Free 전화 요금제는 전화 요금제 그룹으로 그룹화됩니다.
숫자 검색 및 획득
전화 번호는 전화 요금제 ID, 지역 코드 및 전화 번호 수량을 제공하여 검색 생성 API를 통해 검색할 수 있습니다. 제공된 전화 번호 수량은 10분 동안 예약됩니다. 이 전화 번호 검색은 취소하거나 구입할 수 있습니다. 검색이 취소되면 다른 사용자가 전화 번호를 사용할 수 있게 됩니다. 검색을 구매한 경우 Azure 리소스에 대한 전화 번호를 가져옵니다.
숫자 구성 및 할당
전화 번호는 구성 번호 API를 통해 콜백 URL에 할당할 수 있습니다. 구성의 일부로 획득한 전화 번호, 콜백 URL 및 애플리케이션 ID가 필요합니다.
예제
인증
Azure Portal의 Communication Services 리소스에서 키 및/또는 연결 문자열을 가져올 수 있습니다. 키가 있으면 다음 방법 중 원하는 방법으로 및 PhoneNumberAdministrationClient 를 인증 CommunicationIdentityClient 할 수 있습니다.
클라이언트를 초기화하기 전에 를 AzureKeyCredential 사용하여 만들기 KeyCredential
import { AzureKeyCredential } from "@azure/core-auth";
import { CommunicationIdentityClient } from "@azure/communication-administration";
const credential = new AzureKeyCredential(KEY);
const client = new CommunicationIdentityClient(HOST, credential);
연결 문자열 사용
import { PhoneNumberAdministrationClient } from "@azure/communication-administration";
const connectionString = `endpoint=HOST;accessKey=KEY`;
const client = new CommunicationIdentityClient(connectionString);
키를 사용하여 클라이언트를 초기화하는 경우 적절한 엔드포인트도 제공해야 합니다. Azure Portal의 Communication Services 리소스에서 이 엔드포인트를 가져올 수 있습니다.
사용량
CommunicationIdentityClient
CommunicationIdentityClient 인스턴스 만들기
import { CommunicationIdentityClient } from "@azure/communication-administration";
const client = new CommunicationIdentityClient(CONNECTION_STRING);
새 사용자 만들기
메서드를 createUser 사용하여 새 사용자를 만듭니다.
const user = await client.createUser();
사용자 토큰 만들기 및 새로 고침
메서드를 issueToken 사용하여 기존 사용자에 대한 토큰을 발급하거나 새로 고칩니다. 또한 메서드는 통신 토큰 범위 목록을 사용합니다. 범위 옵션은 다음과 같습니다.
-
chat(채팅) -
pstn(공중 전화망) -
voip(IP를 통해 음성)
let { token } = await client.issueToken(user, ["chat"]);
사용자 토큰을 새로 고치려면 동일한 사용자와 다른 토큰을 발급합니다.
{ token } = await client.issueToken(user, ["chat"]);
사용자에 대한 토큰 해지
메서드를 revokeTokens 사용하여 발급된 모든 사용자 토큰을 해지합니다.
await client.revokeTokens(user);
revokeTokens 는 선택적 두 번째 인수인 를 사용합니다 tokensValidFrom. 이 날짜가 제공되면 revokeTokens 은 이전에 발급된 모든 토큰을 해지합니다. 그렇지 않으면 모든 토큰이 해지됩니다.
사용자를 삭제하는 중
메서드를 deleteUser 사용하여 사용자를 삭제합니다.
await client.deleteUser(user);
PhoneNumberAdministrationClient
PhoneNumberAdministrationClient 인스턴스 만들기
import { CommunicationIdentityClient } from "@azure/communication-administration";
const client = new CommunicationIdentityClient(CONNECTION_STRING);
국가 가져오기
메서드를 listSupportedCountries 사용하여 지원되는 국가 목록을 가져옵니다.
const countries = await client.listSupportedCountries();
for await (const country of countries) {
console.log(`Country code: ${country.countryCode}`);
console.log(`Country name: ${country.localizedName}`);
}
전화 요금제 그룹 가져오기
전화 요금제 그룹은 지리적 및 무료의 두 가지 유형으로 제공됩니다. 메서드를 listPhonePlanGroups 사용하여 가져옵니다.
const countryCode = "US";
const phonePlanGroups = await client.listPhonePlanGroups(countryCode);
for await (const phonePlanGroup of phonePlanGroups) {
console.log(`Phone plan group id: ${phonePlanGroup.phonePlanGroupId}`);
}
위치 옵션 가져오기
지리적 전화 플랜의 경우 사용 가능한 지리적 위치를 쿼리할 수 있습니다. 위치 옵션은 국가의 지리적 계층 구조처럼 구조화됩니다. 예를 들어 미국에는 주가 있고 각 주 내에는 도시가 있습니다.
메서드를 getPhonePlanLocationOptions 사용하여 위치에 대한 옵션을 가져옵니다.
const { locationOptions } = await client.getPhonePlanLocationOptions({
countryCode: "US",
phonePlanGroupId: "phonePlanGroupId",
phonePlanId: "phonePlanId"
});
console.log(`Got location options for: ${locationOptions.labelId}`);
영역 코드 가져오기
지리적 전화 요금에 대한 지역 코드를 가져오려면 위치 옵션 쿼리가 설정되어야 합니다. 에서 반환하는 위치 옵션 개체를 트래버스하는 지리적 위치 체인을 getPhonePlanLocationOptions포함해야 합니다.
메서드를 getAreaCodes 사용하여 지리적 전화 요금에 대한 영역 코드를 가져옵니다.
const { primaryAreaCodes } = await client.getAreaCodes({
locationType: "selection",
countryCode: "US",
phonePlanId: "phonePlanId",
locationOptionsQueries
});
구매를 위해 전화 번호 예약
메서드를 beginReservePhoneNumbers 사용하여 전화 번호를 검색하고 예약합니다. 이 작업을 실행하는 데는 오랜 시간이 소요됩니다.
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
});
예약 결과를 얻으려면 만든 폴러에서 메서드를 사용합니다 pollUntilDone .
const phoneNumberReservation = await reservePoller.pollUntilDone();
만든 폴러에서 메서드를 호출 cancelOperation 하여 폴링 및 예약을 취소할 수 있습니다.
await reservePoller.cancelOperation();
예약에서 전화 번호 구매
메서드를 beginPurchasePhoneNumbers 사용하여 예약에서 전화 번호를 구입합니다. 에서 beginReservePhoneNumbers 반환된 가 reservationId 필요합니다.
beginPurchasePhoneNumbers 는 장기 실행 작업이기도 하다.
const { reservationId } = phoneNumberReservation;
const purchasePoller = await client.beginPurchasePhoneNumbers(reservationId);
구매 결과를 얻으려면 만든 구매 폴러에서 메서드를 사용합니다 pollUntilDone .
const results = await purchasePoller.pollUntilDone();
문제 해결
다음 단계
이 라이브러리를 사용하는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.
참여
이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.
관련된 프로젝트
Azure SDK for JavaScript