Python용 Azure Communication Phone Numbers 패키지 클라이언트 라이브러리 - 버전 1.1.0

아티클
03/30/2023

Azure Communication Phone Numbers 클라이언트 패키지는 전화 번호를 관리하는 데 사용됩니다.

고지 사항

Python 2.7에 대한 Azure SDK Python 패키지 지원은 2022년 1월 1일에 종료되었습니다. 자세한 내용과 질문은 을 참조하세요. https://github.com/Azure/azure-sdk-for-python/issues/20691

시작

필수 조건

이 패키지를 사용하려면 Python 3.7 이상이 필요합니다.
Azure 구독이 있어야 합니다.
배포된 Communication Services 리소스. Azure Portal 또는 Azure PowerShell 사용하여 설정할 수 있습니다.

패키지 설치

pip를 사용하여 Python용 Azure Communication Phone Numbers 클라이언트 라이브러리를 설치합니다.

pip install azure-communication-phonenumbers

주요 개념

이 SDK는 및 숫자를 쉽게 관리할 direct offerdirect routing 수 있는 기능을 제공합니다.

숫자는 direct offer 지리적 및 무료라는 두 가지 유형으로 제공됩니다. 지리적 전화 플랜은 지리적 위치의 지역 코드와 연결된 전화 번호의 지역 번호가 있는 위치와 연결된 전화 요금입니다. Toll-Free 전화 플랜은 연결된 위치가 아닌 전화 요금입니다. 예를 들어 미국에서는 무료 번호에 800 또는 888과 같은 지역 번호가 함께 제공 될 수 있습니다. 다음을 사용하여 관리됩니다. PhoneNumbersClient

이 direct routing 기능을 사용하면 기존 전화 통신 인프라를 ACS에 연결할 수 있습니다. 구성은 전화 통신 서브넷에 SipRoutingClient대한 호출을 제대로 처리하기 위해 SIP 트렁크 및 음성 라우팅 규칙을 설정하는 메서드를 제공하는 를 사용하여 관리됩니다.

클라이언트 초기화

클라이언트는 AAD 인증을 사용하여 초기화할 수 있습니다.

import os
from azure.communication.phonenumbers import PhoneNumbersClient
from azure.identity import DefaultAzureCredential

endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
phone_numbers_client = PhoneNumbersClient(endpoint, DefaultAzureCredential())

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient
from azure.identity import DefaultAzureCredential

endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
sip_routing_client = SipRoutingClient(endpoint, DefaultAzureCredential())

또 다른 옵션은 리소스의 연결 문자열을 사용하여 클라이언트를 초기화하는 것입니다.

# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers import PhoneNumbersClient

connection_str = "endpoint=ENDPOINT;accessKey=KEY"
phone_numbers_client = PhoneNumbersClient.from_connection_string(connection_str)

# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient

connection_str = "endpoint=ENDPOINT;accessKey=KEY"
sip_routing_client = SipRoutingClient.from_connection_string(connection_str)

전화 번호 클라이언트

전화 번호 유형 개요

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

숫자 검색 및 구매 및 해제

지역 코드, 전화 번호 수량, 애플리케이션 유형, 전화 번호 유형 및 기능을 제공하여 검색 생성 API를 통해 전화 번호를 검색할 수 있습니다. 제공된 전화 번호 수량은 10분 동안 예약되며 이 시간 내에 구매할 수 있습니다. 검색을 구매하지 않으면 10분 후에 다른 사용자가 전화 번호를 사용할 수 있게 됩니다. 검색을 구매한 경우 Azure 리소스에 대한 전화 번호를 가져옵니다.

릴리스 API를 사용하여 전화 번호를 해제할 수도 있습니다.

SIP 라우팅 클라이언트

직접 라우팅 기능을 사용하면 고객이 제공한 전화 통신 인프라를 Azure Communication Resources에 연결할 수 있습니다. 라우팅 구성을 올바르게 설정하려면 고객이 호출에 대한 SIP 트렁크 구성 및 SIP 라우팅 규칙을 제공해야 합니다. SIP 라우팅 클라이언트는 이 구성을 설정하는 데 필요한 인터페이스를 제공합니다.

호출이 이루어지면 시스템은 정의된 경로의 regex 번호 패턴과 대상 번호를 일치시키려고 시도합니다. 숫자와 일치하는 첫 번째 경로가 선택됩니다. regex 일치 순서는 구성의 경로 순서와 동일하므로 경로 순서가 중요합니다. 경로가 일치하면 경로의 트렁크 목록에서 첫 번째 트렁크로 호출이 라우팅됩니다. 트렁크를 사용할 수 없는 경우 목록에서 다음 트렁크가 선택됩니다.

예제

PhoneNumbersClient

구매한 모든 전화 번호 받기

구매한 모든 전화 번호를 나열합니다.

purchased_phone_numbers = phone_numbers_client.list_purchased_phone_numbers()
for acquired_phone_number in purchased_phone_numbers:
    print(acquired_phone_number.phone_number)

구매한 전화 번호 받기

지정된 전화 번호에서 정보를 가져옵니다.

result = phone_numbers_client.get_purchased_phone_number("<phone number>")
print(result.country_code)
print(result.phone_number)

장기 실행 작업

전화 번호 클라이언트는 아래에 나열된 함수에 무기한 폴링 시간을 허용하는 다양한 장기 실행 작업을 지원합니다.

사용 가능한 전화 번호 검색

획득하려는 휴대폰의 기능, 전화 번호 유형, 할당 유형 및 국가 코드를 제공하여 사용 가능한 전화 번호를 검색할 수 있습니다. 무료 전화 번호 유형에 대해 지역 번호를 증명하는 것은 선택 사항임을 언급할 가치가 있습니다. 그런 다음 검색 결과를 사용하여 해당 API의 번호를 구매할 수 있습니다.

capabilities = PhoneNumberCapabilities(
        calling = PhoneNumberCapabilityType.INBOUND,
        sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND
    )
poller = phone_numbers_client.begin_search_available_phone_numbers(
    "US",
    PhoneNumberType.TOLL_FREE,
    PhoneNumberAssignmentType.APPLICATION,
    capabilities,
    area_code ="833", # Area code is optional for toll-free numbers
    quantity = 2, # Quantity is optional. If not set, default is 1
    polling = True
)
search_result = poller.result()

전화 번호 구매

검색 결과를 사용하여 지정된 전화 번호를 구입할 수 있습니다. 이 작업은 검색 응답에서 구매 전화 번호 API로 를 전달 search_id 하여 수행할 수 있습니다.

purchase_poller = phone_numbers_client.begin_purchase_phone_numbers(
    search_result.search_id,
    polling=True
)

전화 번호 해제

획득한 전화 번호를 해제합니다.

poller = self.phone_number_client.begin_release_phone_number(
    "<phone number>",
    polling = True
)

전화 번호 기능 업데이트

통화 및 SMS에 대해 지정된 전화 번호 기능을 다음 중 하나로 업데이트.

PhoneNumberCapabilityType.NONE
PhoneNumberCapabilityType.INBOUND
PhoneNumberCapabilityType.OUTBOUND
PhoneNumberCapabilityType.INBOUND_OUTBOUND

poller = self.phone_number_client.begin_update_phone_number_capabilities(
    "<phone number>",
    PhoneNumberCapabilityType.OUTBOUND,
    PhoneNumberCapabilityType.INBOUND_OUTBOUND,
    polling = True
)

SipRoutingClient

SIP 트렁크 및 경로 검색

현재 구성된 트렁크 또는 경로 목록을 가져옵니다.

trunks = sip_routing_client.list_trunks()
for trunk in trunks:
    print(trunk.fqdn)
    print(trunk.sip_signaling_port)
routes = sip_routing_client.list_routes()
for route in routes:
    print(route.name)
    print(route.description)
    print(route.number_pattern)
    for trunk_fqdn in route.trunks:
        print(trunk_fqdn)

SIP 트렁크 및 경로 바꾸기

현재 구성된 트렁크 또는 경로 목록을 새 값으로 바꿉니다.

new_trunks = [SipTrunk(fqdn="sbs1.contoso.com", sip_signaling_port=1122), SipTrunk(fqdn="sbs2.contoso.com", sip_signaling_port=1123)]
new_routes = [SipTrunkRoute(name="First rule", description="Handle numbers starting with '+123'", number_pattern="\+123[0-9]+", trunks=["sbs1.sipconfigtest.com"])]
sip_routing_client.set_trunks(new_trunks)
sip_routing_client.set_routes(new_routes)

단일 트렁크 검색

trunk = sip_routing_client.get_trunk("sbs1.contoso.com")

단일 트렁크 설정

# Set function will either modify existing item or add new item to the collection.
# The trunk is matched based on it's FQDN.
new_trunk = SipTrunk(fqdn="sbs3.contoso.com", sip_signaling_port=5555)
sip_routing_client.set_trunk(new_trunk)

단일 트렁크 삭제

sip_routing_client.delete_trunk("sbs1.contoso.com")

문제 해결

전화 번호 관리 클라이언트는 Azure Core에 정의된 예외를 발생합니다.

다음 단계

추가 샘플 코드

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

피드백 제공

버그가 발생하거나 제안이 있는 경우 프로젝트의 문제 섹션에 문제를 제출하세요.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.