Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Communication] - Phone Number - Redesigned API #16671

Merged
merged 32 commits into from
Mar 6, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
a2e811d
Added new pnm redesign code
jorge-beauregard Feb 10, 2021
f781a83
Added sanitization
jorge-beauregard Feb 11, 2021
0ff036e
Regenerated code
jorge-beauregard Feb 12, 2021
d4f316d
Added README and samples
jorge-beauregard Feb 15, 2021
0133451
Tests work with new area code
jorge-beauregard Feb 16, 2021
5ad4bfa
Addresses comments
jorge-beauregard Feb 17, 2021
3fda514
Corrected samples
jorge-beauregard Feb 17, 2021
d11dabe
Corrected samples
jorge-beauregard Feb 17, 2021
bf22ddd
Added fixed samples
jorge-beauregard Feb 17, 2021
d3f4e36
Removed hardcoded info from tests
jorge-beauregard Feb 18, 2021
64adb44
Added managed identity tests and addressed apiview comments
jorge-beauregard Feb 22, 2021
b4591fb
Addressed comments
jorge-beauregard Feb 22, 2021
0bc5cd2
Regenerated code and addressed comments
jorge-beauregard Feb 25, 2021
d82a9f7
Addressed APIView comments
jorge-beauregard Mar 2, 2021
5c457fb
Added new pnm redesign code
jorge-beauregard Feb 10, 2021
4684093
Added sanitization
jorge-beauregard Feb 11, 2021
fd45f5a
Regenerated code
jorge-beauregard Feb 12, 2021
61d1936
Added README and samples
jorge-beauregard Feb 15, 2021
62cda6f
Tests work with new area code
jorge-beauregard Feb 16, 2021
598c24a
Addresses comments
jorge-beauregard Feb 17, 2021
5a34e82
Corrected samples
jorge-beauregard Feb 17, 2021
92bc389
Added fixed samples
jorge-beauregard Feb 17, 2021
4141b14
Removed hardcoded info from tests
jorge-beauregard Feb 18, 2021
0b19746
Added managed identity tests and addressed apiview comments
jorge-beauregard Feb 22, 2021
938e10a
Addressed comments
jorge-beauregard Feb 22, 2021
8031157
Regenerated code and addressed comments
jorge-beauregard Feb 25, 2021
2e549c5
Fixed merge conflicts
jorge-beauregard Mar 2, 2021
545fcb0
Reworked tests
jorge-beauregard Mar 5, 2021
a7d0a0c
Fixed EVERYTHING
jorge-beauregard Mar 5, 2021
e268c60
Addressed comments
jorge-beauregard Mar 5, 2021
b14ef4d
Added more sanitization
jorge-beauregard Mar 5, 2021
8b92a11
Disabling search tests
jorge-beauregard Mar 5, 2021
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 63 additions & 87 deletions sdk/communication/azure-communication-phonenumbers/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,153 +16,129 @@ Install the Azure Communication Phone Numbers client library for Python with [pi
pip install azure-communication-phonenumbers
```

# Key concepts
## Key concepts

## CommunicationPhoneNumberClient
### Initializing Phone Numbers Client
```python
# You can find your endpoint and access token from your resource in the Azure Portal
beltr0n marked this conversation as resolved.
Show resolved Hide resolved
# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers import PhoneNumbersAdministrationClient
from azure.communication.phonenumbers import PhoneNumbersClient
from azure.identity import DefaultAzureCredential

endpoint = os.getenv('AZURE_COMMUNICATION_SERVICE_ENDPOINT')
endpoint = os.getenv('AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING')

# 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_number_administration_client = PhoneNumbersAdministrationClient(endpoint, DefaultAzureCredential())

```
### Initializing Phone Numbers Client Using Connection String
### Initializing the Client Using Your Connection String
Connection string authentication is also available for Phone Numbers Client.

```python
# You can find your endpoint and access token from your resource in the Azure Portal
# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers import PhoneNumbersAdministrationClient
from azure.communication.phonenumbers import PhoneNumbersClient

connection_str = os.getenv('AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING')
phone_number_administration_client = PhoneNumbersAdministrationClient.from_connection_string(connection_str)
```

### Phone plans overview
### Phone Number Types 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.
Phone numbers come in two types; Geographic and Toll-Free. Geographic phone numbers are phone numbers associated with a location, whose area codes are associated with the area code of a geographic location. Toll-Free phone numbers are phone numbers with no 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 Purchasing and Releasing numbers

### Reserving and Acquiring numbers
Phone numbers can be searched through the search creation API by providing an area code, quantity of phone numbers, application type, phone number type, and capabilities. The provided quantity of phone numbers will be reserved for ten minutes and can be purchased within this time. If the search is not purchased, the phone numbers will become available to others after ten minutes. If the search is purchased, then the phone numbers are acquired for the Azure resources.

Phone numbers can be reserved through the begin_reserve_phone_numbers 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 reservation of phone numbers can either be cancelled or purchased. If the reservation is cancelled, then the phone numbers will become available to others. If the reservation is purchased, then the phone numbers are acquired for the Azure resources.
Phone numbers can also be released using the release API.

### Configuring / Assigning numbers
## Examples

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.
### Get All Phone Numbers

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

## Communication Phone number
### Get Countries
Lists all of your acquired phone numbers

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

supported_countries = phone_number_administration_client.list_all_supported_countries()
for supported_country in supported_countries:
print(supported_country)
acquired_phone_numbers = phone_numbers_client.list_acquired_phone_numbers()
acquired_phone_number = acquired_phone_numbers.next()
print(acquired_phone_number.phone_number)
```

### Get Phone Plan Groups
### Get Phone Number

Phone plan groups come in two types, Geographic and Toll-Free.
Gets the information from the specified phone number

```python
phone_number_administration_client = PhoneNumbersAdministrationClient.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)
result = phone_numbers_client.get_phone_number("<phone number>")
print(result.country_code)
print(result.phone_number)
```

### Get Phone Plans
## Long Running Operations

Unlike Toll-Free phone plans, area codes for Geographic Phone Plans are empty. Area codes are found in the Area Codes API.
The Phone Number Client supports a variety of long running operations that allow indefinite polling time to the functions listed down below.

```python
phone_number_administration_client = PhoneNumbersAdministrationClient.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
### Search for Available Phone Number

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.
You can search for available phone numbers by providing the capabilities of the phone you want to acquire, the phone number type, the assignment type, and the country code. It's worth mentioning that for the toll-free phone number type, proving the area code is optional.
The result of the search can then be used to purchase the number in the corresponding API.

```python
phone_number_administration_client = PhoneNumbersAdministrationClient.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>'
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
)
print(location_options_response)
search_result = poller.result()
```

### Get Area Codes
### Purchase Phone Numbers

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.
The result of your search can be used to purchase the specificied phone numbers. This can be done by passing the `search_id` from the search response to the purchase phone number API.

```python
phone_number_administration_client = PhoneNumbersAdministrationClient.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>'
purchase_poller = phone_numbers_client.begin_purchase_phone_numbers(
search_result.search_id,
polling=True
)
print(all_area_codes)
```

### Create Reservation
### Release Phone Number

```python
phone_number_administration_client = PhoneNumbersAdministrationClient.from_connection_string(connection_str)
Releases an acquired phone number.

poller = phone_number_administration_client.begin_reserve_phone_numbers(
area_code='<area code>',
description="testreservation20200014",
display_name="testreservation20200014",
phone_plan_ids=['<phone plan id>'],
quantity=1
```python
poller = self.phone_number_client.begin_release_phone_number(
"<phone number>",
polling = True
)
```

### Get Reservation By Id
```python
phone_number_administration_client = PhoneNumbersAdministrationClient.from_connection_string(connection_str)
### Updating Phone Number Capabilities

phone_number_reservation_response = phone_number_administration_client.get_reservation_by_id(
reservation_id='<reservation id>'
)
print(reservation_id)
```
Updates the specified phone number capabilities for Calling and SMS to one of:

### Purchase Reservation
- `PhoneNumberCapabilityType.NONE`
- `PhoneNumberCapabilityType.INBOUND`
- `PhoneNumberCapabilityType.OUTBOUND`
- `PhoneNumberCapabilityType.INBOUND_OUTBOUND`

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

poller = phone_number_administration_client.begin_purchase_reservation(
reservation_id='<reservation id to purchase>'
poller = self.phone_number_client.begin_update_phone_number_capabilities(
"<phone number>",
PhoneNumberCapabilityType.OUTBOUND,
PhoneNumberCapabilityType.INBOUND_OUTBOUND,
polling = True
)
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,66 +4,27 @@
# license information.
# --------------------------------------------------------------------------

from ._phone_number_administration_client import PhoneNumbersAdministrationClient
from ._polling import ReservePhoneNumberPolling, PurchaseReservationPolling, ReleasePhoneNumberPolling
from ._phone_numbers_client import PhoneNumbersClient

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

from ._shared.models import (
CommunicationUserIdentifier,
PhoneNumberIdentifier,
UnknownIdentifier
PhoneNumberCapabilities,
PhoneNumberCost,
PhoneNumberSearchResult,
BillingFrequency,
PhoneNumberAssignmentType,
PhoneNumberCapabilityType,
PhoneNumberType,
)

__all__ = [
'PhoneNumbersAdministrationClient',
'ReservePhoneNumberPolling',
'PurchaseReservationPolling',
'ReleasePhoneNumberPolling',

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

# from _shared
'CommunicationUserIdentifier',
'PhoneNumberIdentifier',
'UnknownIdentifier'
'PhoneNumberCapabilities',
'PhoneNumberCost',
'PhoneNumberSearchResult',
'BillingFrequency',
'PhoneNumberAssignmentType',
'PhoneNumberCapabilityType',
'PhoneNumberType',
'PhoneNumbersClient'
]
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
# Changes may cause incorrect behavior and will be lost if the code is regenerated.
# --------------------------------------------------------------------------

from ._phone_number_administration_service import PhoneNumberAdministrationService
__all__ = ['PhoneNumberAdministrationService']
from ._phone_numbers_client import PhoneNumbersClient
__all__ = ['PhoneNumbersClient']

try:
from ._patch import patch_sdk # type: ignore
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,13 @@

VERSION = "unknown"

class PhoneNumberAdministrationServiceConfiguration(Configuration):
"""Configuration for PhoneNumberAdministrationService.
class PhoneNumbersClientConfiguration(Configuration):
"""Configuration for PhoneNumbersClient.

Note that all parameters used to create this instance are saved as instance
attributes.

:param endpoint: The endpoint of the Azure Communication resource.
:param endpoint: The communication resource, for example https://resourcename.communication.azure.com.
:type endpoint: str
"""

Expand All @@ -35,11 +35,11 @@ def __init__(
# type: (...) -> None
if endpoint is None:
raise ValueError("Parameter 'endpoint' must not be None.")
super(PhoneNumberAdministrationServiceConfiguration, self).__init__(**kwargs)
super(PhoneNumbersClientConfiguration, self).__init__(**kwargs)

self.endpoint = endpoint
self.api_version = "2020-07-20-preview1"
kwargs.setdefault('sdk_moniker', 'phonenumberadministrationservice/{}'.format(VERSION))
self.api_version = "2021-03-07"
kwargs.setdefault('sdk_moniker', 'phonenumbersclient/{}'.format(VERSION))
self._configure(**kwargs)

def _configure(
Expand Down
Loading