Skip to content

Commit

Permalink
Azure Communication Service - Phone Number Administration (#14237)
Browse files Browse the repository at this point in the history 
* Add tnm

* Azure Communication Service - Phone Number Administration - Live Test (#14109)

* add tnm live tests and recordings

* address comments

* assert functions returning none

* sync srubbed config and playback config

Co-authored-by: Eason Yang <easony@microsoft.com>

* Azure Communication Services - Phone Number Admin - Implementing long running operations for phone number search  (#14157)

*  Implementing long running operations for phone number search

* refresh swagger and auto generated code (#14182)

* Azure Communication Service - Phone Number Administration - Samples (#14162)

* add tnm samples v0

* address comments

* update samples with long run operation

* add basic readme for phone number description

* add e=code example to tnm readme

* update admin setup.py with long_description_content_type

Co-authored-by: Eason Yang <easony@microsoft.com>

* Revert "Azure Communication Services - Phone Number Admin - Implementing long running operations for phone number search  (#14157)" (#14208)

This reverts commit fd7191d.

* revert LRO from TNM samples (#14211)

Co-authored-by: Eason Yang <easony@microsoft.com>

* refresh swagger link and auto generated code (#14210)

* remove duplicate long_description_content_type (#14230)

Co-authored-by: Eason Yang <easony@microsoft.com>

* add readme changes (#14222)

Co-authored-by: Eason Yang <easony@microsoft.com>

* Azure Communication Service - Phone Number Administration - Add release phone number to live tests (#14227)

* Azure Communication Service - Phone Number Administration - Samples (#14162)

* add tnm samples v0

* address comments

* update samples with long run operation

* add basic readme for phone number description

* add e=code example to tnm readme

* update admin setup.py with long_description_content_type

Co-authored-by: Eason Yang <easony@microsoft.com>

* rename live tests variables

* add release phone numbers

* remove extra lines readme

Co-authored-by: Eason Yang <easony@microsoft.com>

Co-authored-by: tural farhadov <tufarhad@microsoft.com>
Co-authored-by: Eason <eason.yty@gmail.com>
Co-authored-by: Eason Yang <easony@microsoft.com>
  • Loading branch information
@HeliWang @ytyeason
4 people authored Oct 5, 2020
1 parent 026580e commit ac9406e
Show file tree
Hide file tree
Showing 86 changed files with 10,146 additions and 1 deletion.
133 changes: 133 additions & 0 deletions sdk/communication/azure-communication-administration/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,13 +24,146 @@ pip install azure-communication-administration

- Create/revoke scoped user access tokens to access services such as chat, calling, sms. Tokens are issued for a valid Azure Communication identity and can be revoked at any time.

## CommunicationPhoneNumberClient
### Initializing Phone Number Client
```python
# You can find your endpoint and access token from your resource in the Azure Portal
import os
from azure.communication.administration import PhoneNumberAdministrationClient

connection_str = os.getenv('AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING')
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)
```
### Phone plans overview

Phone plans come in two types; Geographic and Toll-Free. Geographic phone plans are phone plans associated with a location, whose phone numbers' area codes are associated with the area code of a geographic location. Toll-Free phone plans are phone plans not associated location. For example, in the US, toll-free numbers can come with area codes such as 800 or 888.

All geographic phone plans within the same country are grouped into a phone plan group with a Geographic phone number type. All Toll-Free phone plans within the same country are grouped into a phone plan group.

### Searching and Acquiring numbers

Phone numbers search can be search through the search creation API by providing a phone plan id, an area code and quantity of phone numbers. The provided quantity of phone numbers will be reserved for ten minutes. This search of phone numbers can either be cancelled or purchased. If the search is cancelled, then the phone numbers will become available to others. If the search is purchased, then the phone numbers are acquired for the Azure resources.

### Configuring / Assigning numbers

Phone numbers can be assigned to a callback URL via the configure number API. As part of the configuration, you will need an acquired phone number, callback URL and application id.

# Examples
The following section provides several code snippets covering some of the most common Azure Communication Services tasks, including:

[Create/delete Azure Communication Service identities][identitysamples]

[Create/revoke scoped user access tokens][identitysamples]

## Communication Phone number
### Get Countries

```python
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)

supported_countries = phone_number_administration_client.list_all_supported_countries()
for supported_country in supported_countries:
print(supported_country)
```

### Get Phone Plan Groups

Phone plan groups come in two types, Geographic and Toll-Free.

```python
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)

phone_plan_groups_response = phone_number_administration_client.list_phone_plan_groups(
country_code='<country code>'
)
for phone_plan_group in phone_plan_groups_response:
print(phone_plan_group)
```

### Get Phone Plans

Unlike Toll-Free phone plans, area codes for Geographic Phone Plans are empty. Area codes are found in the Area Codes API.

```python
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)

phone_plans_response = phone_number_administration_client.list_phone_plans(
country_code='<country code>',
phone_plan_group_id='<phone plan group id>'
)
for phone_plan in phone_plans_response:
print(phone_plan)
```

### Get Location Options

For Geographic phone plans, you can query the available geographic locations. The locations options are structured like the geographic hierarchy of a country. For example, the US has states and within each state are cities.

```python
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)

location_options_response = phone_number_administration_client.get_phone_plan_location_options(
country_code='<country code>',
phone_plan_group_id='<phone plan group id>',
phone_plan_id='<phone plan id>'
)
print(location_options_response)
```

### Get Area Codes

Fetching area codes for geographic phone plans will require the the location options queries set. You must include the chain of geographic locations traversing down the location options object returned by the GetLocationOptions API.

```python
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)

all_area_codes = phone_number_administration_client.get_all_area_codes(
location_type="NotRequired",
country_code='<country code>',
phone_plan_id='<phone plan id>'
)
print(all_area_codes)
```

### Create Search

```python
from azure.communication.administration import CreateSearchOptions
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)

searchOptions = CreateSearchOptions(
area_code='<area code>',
description="testsearch20200014",
display_name="testsearch20200014",
phone_plan_ids=['<phone plan id>'],
quantity=1
)
search_response = phone_number_administration_client.create_search(
body=searchOptions
)
print(search_response)
```

### Get search by id
```python
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)

phone_number_search_response = phone_number_administration_client.get_search_by_id(
search_id='<search id>'
)
print(phone_number_search_response)
```

### Purchase Search

```python
phone_number_administration_client = PhoneNumberAdministrationClient.from_connection_string(connection_str)

phone_number_administration_client.purchase_search(
search_id='<search id to purchase>'
)
```

# Troubleshooting
The Azure Communication Service Identity client will raise exceptions defined in [Azure Core][azure_core].

Expand Down
45 changes: 45 additions & 0 deletions ...ication/azure-communication-administration/azure/communication/administration/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,35 @@
# --------------------------------------------------------------------------

from ._communication_identity_client import CommunicationIdentityClient
from ._phone_number_administration_client import PhoneNumberAdministrationClient

from ._identity._generated.models import (
CommunicationTokenRequest,
CommunicationIdentityToken
)

from ._phonenumber._generated.models import (
AcquiredPhoneNumber,
AcquiredPhoneNumbers,
AreaCodes,
CreateSearchResponse,
LocationOptionsQuery,
LocationOptionsResponse,
NumberConfigurationResponse,
NumberUpdateCapabilities,
PhoneNumberCountries,
PhoneNumberEntities,
PhoneNumberRelease,
PhoneNumberSearch,
PhonePlanGroups,
PhonePlansResponse,
PstnConfiguration,
ReleaseResponse,
UpdateNumberCapabilitiesResponse,
UpdatePhoneNumberCapabilitiesResponse,
CreateSearchOptions
)

from ._shared.models import (
CommunicationUser,
PhoneNumber,
Expand All @@ -19,11 +42,33 @@

__all__ = [
'CommunicationIdentityClient',
'PhoneNumberAdministrationClient',

# from _identity
'CommunicationTokenRequest',
'CommunicationIdentityToken',

# from _phonenumber
'AcquiredPhoneNumber',
'AcquiredPhoneNumbers',
'AreaCodes',
'CreateSearchResponse',
'LocationOptionsQuery',
'LocationOptionsResponse',
'NumberConfigurationResponse',
'NumberUpdateCapabilities',
'PhoneNumberCountries',
'PhoneNumberEntities',
'PhoneNumberRelease',
'PhoneNumberSearch',
'PhonePlanGroups',
'PhonePlansResponse',
'PstnConfiguration',
'ReleaseResponse',
'UpdateNumberCapabilitiesResponse',
'UpdatePhoneNumberCapabilitiesResponse',
'CreateSearchOptions',

# from _shared
'CommunicationUser',
'PhoneNumber',
Expand Down
Loading

0 comments on commit ac9406e

Please sign in to comment.