Phone Numbers - Browse Available Numbers

服务:

Communication

API 版本:

2025-04-01

浏览要购买的可用电话号码。 响应将是可用于购买的符合浏览条件的电话号码的随机列表。 此作未分页。 由于结果是随机的，重复相同的请求不能保证相同的结果。

POST {endpoint}/availablePhoneNumbers/countries/{countryCode}/:browse?api-version=2025-04-01

URI 参数

名称	在	必需	类型	说明
countryCode	path	True	string	ISO 3166-2 国家/地区代码，例如美国。
endpoint	path	True	string (url)	通信资源，例如 https://resourcename.communication.azure.com
api-version	query	True	string	要调用的 API 版本

请求正文

名称	必需	类型	说明
phoneNumberType	True	PhoneNumberType	表示产品/服务的数量类型。
assignmentType		PhoneNumberAssignmentType	表示产品/服务的分配类型。 也称为用例。
capabilities		PhoneNumberBrowseCapabilitiesRequest	浏览作请求的最低所需功能。
phoneNumberPrefixes		string[]	要匹配的电话号码前缀。 如果指定，搜索将仅限于以任何给定前缀开头的电话号码。

响应

名称	类型	说明
200 OK	PhoneNumbersBrowseResult	可用于购买的符合浏览条件的电话号码的随机列表。
Other Status Codes	CommunicationErrorResponse	失败

示例

Browse available phone numbers

示例请求

HTTP

POST https://resourcename.communication.azure.com/availablePhoneNumbers/countries/US/:browse?api-version=2025-04-01

{
  "phoneNumberType": "geographic",
  "capabilities": {
    "calling": "outbound",
    "sms": "none"
  },
  "assignmentType": "person",
  "phoneNumberPrefixes": [
    "1425",
    "1626"
  ]
}

示例响应

状态代码:

200

{
  "phoneNumbers": [
    {
      "id": "14254567890",
      "countryCode": "US",
      "phoneNumber": "+14254567890",
      "capabilities": {
        "calling": "outbound",
        "sms": "none"
      },
      "phoneNumberType": "geographic",
      "assignmentType": "person",
      "cost": {
        "amount": 1,
        "currencyCode": "USD",
        "billingFrequency": "monthly"
      },
      "status": "available",
      "isAgreementToNotResellRequired": false
    },
    {
      "id": "16264567890",
      "countryCode": "US",
      "phoneNumber": "+16264567890",
      "capabilities": {
        "calling": "outbound",
        "sms": "none"
      },
      "phoneNumberType": "geographic",
      "assignmentType": "person",
      "cost": {
        "amount": 1,
        "currencyCode": "USD",
        "billingFrequency": "monthly"
      },
      "status": "available",
      "isAgreementToNotResellRequired": false
    }
  ]
}

定义

名称	说明
AvailablePhoneNumber	表示清单中可用的电话号码
AvailablePhoneNumberError	在保留、释放或购买电话号码时出现故障时，包含错误详细信息。 请注意，当请求中存在时，服务会忽略此项。
AvailablePhoneNumberStatus	表示电话号码的状态。 可能的值包括：“available”、“reserved”、“expired”、“error”、“purchased”。
BillingFrequency	费用计费的频率。
CommunicationError	通信服务错误。
CommunicationErrorResponse	通信服务错误。
Cost	此电话号码产生的成本。
PhoneNumberAssignmentType	表示产品/服务的分配类型。
PhoneNumberBrowseCapabilitiesRequest	浏览作请求的最低所需功能。
PhoneNumberCapabilities	电话号码的功能。
PhoneNumberCapabilityType	调用的功能值。
PhoneNumbersBrowseRequest	浏览作的参数。
PhoneNumbersBrowseResult	电话号码浏览作的结果。
PhoneNumberType	表示产品/服务的数量类型。

AvailablePhoneNumber

Object

表示清单中可用的电话号码

名称	类型	说明
assignmentType	PhoneNumberAssignmentType	表示产品/服务的分配类型。 也称为用例。
capabilities	PhoneNumberCapabilities	电话号码的功能。
cost	Cost	此电话号码产生的成本。
countryCode	string	ISO 3166-2 国家/地区代码，例如美国。
error	AvailablePhoneNumberError	在保留、释放或购买电话号码时出现故障时，包含错误详细信息。 请注意，当请求中存在时，服务会忽略此项。
id	string	电话号码的 ID。
isAgreementToNotResellRequired	boolean	指示是否需要转售协议。 如果为 true，则无法获取电话号码，除非客户提供明确协议来不转售电话号码。
phoneNumber	string	E.164 格式的电话号码，例如 +11234567890。
phoneNumberType	PhoneNumberType	表示产品/服务的数量类型。
status	AvailablePhoneNumberStatus	表示电话号码的状态。 可能的值包括：“available”、“reserved”、“expired”、“error”、“purchased”。

AvailablePhoneNumberError

Object

在保留、释放或购买电话号码时出现故障时，包含错误详细信息。 请注意，当请求中存在时，服务会忽略此项。

名称	类型	说明
code	string	错误代码，指示对电话号码执行的作失败的原因。
message	string	描述发生的失败的错误消息。

AvailablePhoneNumberStatus

枚举

表示电话号码的状态。 可能的值包括：“available”、“reserved”、“expired”、“error”、“purchased”。

值	说明
available
error
expired
purchased
reserved

BillingFrequency

枚举

费用计费的频率。

值	说明
monthly

CommunicationError

Object

通信服务错误。

名称	类型	说明
code	string	错误代码。
details	CommunicationError[]	有关导致此错误的特定错误的更多详细信息。
innererror	CommunicationError	内部错误（如果有）。
message	string	错误消息。
target	string	错误目标。

CommunicationErrorResponse

Object

通信服务错误。

名称	类型	说明
error	CommunicationError	通信服务错误。

Cost

Object

此电话号码产生的成本。

名称	类型	说明
amount	number (double)	成本金额。
billingFrequency	BillingFrequency	费用计费的频率。
currencyCode	string	成本金额的 ISO 4217 货币代码，例如美元。

PhoneNumberAssignmentType

枚举

表示产品/服务的分配类型。

值	说明
application
person

PhoneNumberBrowseCapabilitiesRequest

Object

浏览作请求的最低所需功能。

名称	类型	说明
calling	PhoneNumberCapabilityType	调用的功能值。
sms	PhoneNumberCapabilityType	SMS 的功能值。

PhoneNumberCapabilities

Object

电话号码的功能。

名称	类型	说明
calling	PhoneNumberCapabilityType	调用的功能值。
sms	PhoneNumberCapabilityType	SMS 的功能值。

PhoneNumberCapabilityType

枚举

调用的功能值。

值	说明
inbound
inbound+outbound
none
outbound

PhoneNumbersBrowseRequest

Object

浏览作的参数。

名称	类型	说明
assignmentType	PhoneNumberAssignmentType	表示产品/服务的分配类型。 也称为用例。
capabilities	PhoneNumberBrowseCapabilitiesRequest	浏览作请求的最低所需功能。
phoneNumberPrefixes	string[]	要匹配的电话号码前缀。 如果指定，搜索将仅限于以任何给定前缀开头的电话号码。
phoneNumberType	PhoneNumberType	表示产品/服务的数量类型。

PhoneNumbersBrowseResult

Object

电话号码浏览作的结果。

名称	类型	说明
phoneNumbers	AvailablePhoneNumber[]	可供购买的电话号码。

PhoneNumberType

枚举

表示产品/服务的数量类型。

值	说明
geographic
tollFree