Phone Numbers - Search Available Phone Numbers

服務:

Communication

API 版本:

2025-02-11

搜尋要購買的可用電話號碼。

POST {endpoint}/availablePhoneNumbers/countries/{countryCode}/:search?api-version=2025-02-11

URI 參數

名稱	位於	必要	類型	Description
countryCode	path	True	string	ISO 3166-2 國家/地區代碼，例如美國。
endpoint	path	True	string (url)	通訊資源，例如 https://resourcename.communication.azure.com
api-version	query	True	string	要叫用的 API 版本

要求本文

名稱	必要	類型	Description
assignmentType	True	PhoneNumberAssignmentType	要搜尋的電話號碼指派類型。 電話號碼可以指派給人員或應用程式。
capabilities	True	PhoneNumberCapabilities	電話號碼的功能。
phoneNumberType	True	PhoneNumberType	要搜尋的電話號碼類型，例如地理或 tollFree。
areaCode		string	所需電話號碼的區域代碼，例如 425。
quantity		integer (int32) minimum: 1 maximum: 2147483647	所需電話號碼的數量。 預設值為 1。

回應

名稱	類型	Description
202 Accepted	PhoneNumberSearchResult	服務已接受要求，稍後將會開始處理。 它會立即傳回 『Accepted』，並包含 『Operation-Location』 和 'Location' 標頭。 客戶端應該使用 『Operation-Location』 標頭中指定的 URL 進一步查詢作業狀態。 作業完成時，會使用 'Location' 標頭中指定的 URL 順利查詢最終結果。 標題 Location: string Operation-Location: string operation-id: string search-id: string
Other Status Codes	CommunicationErrorResponse	失敗

範例

Search for phone numbers

範例要求

HTTP

POST https://resourcename.communication.azure.com//availablePhoneNumbers/countries/US/:search?api-version=2025-02-11

{
  "phoneNumberType": "tollFree",
  "assignmentType": "application",
  "capabilities": {
    "sms": "inbound+outbound",
    "calling": "none"
  },
  "areaCode": "425",
  "quantity": 1
}

範例回覆

狀態碼:

202

Operation-Location: /phoneNumbers/operations/search_378ddf60-81be-452a-ba4f-613198ea6c28
Location: /availablePhoneNumbers/searchResults/378ddf60-81be-452a-ba4f-613198ea6c28
operation-id: search_378ddf60-81be-452a-ba4f-613198ea6c28
search-id: 378ddf60-81be-452a-ba4f-613198ea6c28

{
  "searchId": "378ddf60-81be-452a-ba4f-613198ea6c28",
  "phoneNumbers": [
    "+18001212121"
  ],
  "phoneNumberType": "tollFree",
  "assignmentType": "application",
  "capabilities": {
    "sms": "inbound+outbound",
    "calling": "none"
  },
  "cost": {
    "amount": 1.2,
    "currencyCode": "USD",
    "billingFrequency": "monthly"
  },
  "searchExpiresBy": "2020-11-19T16:31:49.048Z"
}

定義

名稱	Description
BillingFrequency	計費成本的頻率。
CommunicationError	通訊服務錯誤。
CommunicationErrorResponse	通訊服務錯誤。
Error	將錯誤訊息對應至程序代碼
PhoneNumberAssignmentType	表示供應專案的指派類型。
PhoneNumberCapabilities	電話號碼的功能。
PhoneNumberCapabilityType	呼叫的功能值。
PhoneNumberCost	單一電話號碼所產生的成本。
PhoneNumberSearchRequest	表示尋找電話號碼的電話號碼搜尋要求。 找到的電話號碼會暫時保留，以供購買。
PhoneNumberSearchResult	電話號碼搜尋作業的結果。
PhoneNumberType	表示供應項目的數目類型。

BillingFrequency

列舉型別

計費成本的頻率。

值	Description
monthly

CommunicationError

Object

通訊服務錯誤。

名稱	類型	Description
code	string	錯誤碼。
details	CommunicationError[]	導致此錯誤之特定錯誤的詳細數據。
innererror	CommunicationError	如果有，則為內部錯誤。
message	string	錯誤訊息。
target	string	錯誤目標。

CommunicationErrorResponse

Object

通訊服務錯誤。

名稱	類型	Description
error	CommunicationError	通訊服務錯誤。

Error

列舉型別

將錯誤訊息對應至程序代碼

值	Description
AllNumbersNotAcquired
AuthorizationDenied
BillingUnavailable
InvalidAddress
InvalidOfferModel
MissingAddress
NoError
NoWallet
NotEnoughCredit
NotEnoughLicenses
NumbersPartiallyAcquired
OutOfStock
ProvisioningFailed
PurchaseFailed
ReservationExpired
UnknownErrorCode
UnknownSearchError

PhoneNumberAssignmentType

列舉型別

表示供應專案的指派類型。

值	Description
application
person

PhoneNumberCapabilities

Object

電話號碼的功能。

名稱	類型	Description
calling	PhoneNumberCapabilityType	呼叫的功能值。
sms	PhoneNumberCapabilityType	SMS 的功能值。

PhoneNumberCapabilityType

列舉型別

呼叫的功能值。

值	Description
inbound
inbound+outbound
none
outbound

PhoneNumberCost

Object

單一電話號碼所產生的成本。

名稱	類型	Description
amount	number (double)	成本金額。
billingFrequency	BillingFrequency	計費成本的頻率。
currencyCode	string	成本金額的 ISO 4217 貨幣代碼，例如美元。

PhoneNumberSearchRequest

Object

表示尋找電話號碼的電話號碼搜尋要求。 找到的電話號碼會暫時保留，以供購買。

名稱	類型	預設值	Description
areaCode	string		所需電話號碼的區域代碼，例如 425。
assignmentType	PhoneNumberAssignmentType		要搜尋的電話號碼指派類型。 電話號碼可以指派給人員或應用程式。
capabilities	PhoneNumberCapabilities		電話號碼的功能。
phoneNumberType	PhoneNumberType		要搜尋的電話號碼類型，例如地理或 tollFree。
quantity	integer (int32) minimum: 1 maximum: 2147483647	1	所需電話號碼的數量。 預設值為 1。

PhoneNumberSearchResult

Object

電話號碼搜尋作業的結果。

名稱	類型	Description
assignmentType	PhoneNumberAssignmentType	電話號碼的指派類型。
capabilities	PhoneNumberCapabilities	電話號碼的功能。
cost	PhoneNumberCost	單一電話號碼所產生的成本。
error	Error	將錯誤訊息對應至程序代碼
errorCode	integer (int32)	搜尋的錯誤碼。
phoneNumberType	PhoneNumberType	電話號碼的類型，例如地理或 tollFree。
phoneNumbers	string[]	可用的電話號碼。 可能小於所需的搜尋數量。
searchExpiresBy	string (date-time)	此搜尋結果到期的日期，且電話號碼已不再保留。 搜尋結果的到期時間少於 15 分鐘，例如 2020-11-19T16：31：49.048Z。
searchId	string	搜尋標識碼。

PhoneNumberType

列舉型別

表示供應項目的數目類型。

值	Description
geographic
tollFree