Queries the endpoints of all regions supported by Object Storage Service (OSS) or a specific region, including public endpoints, internal endpoints, and accelerate endpoints.

Usage notes

  • To query the endpoints of a region, you must have the oss:DescribeRegions permission. For more information, see Attach a custom policy to a RAM user.
  • Requests initiated by calling the DescribeRegions operation can contain only second-level domains, such as oss-cn-hangzhou.aliyuncs.com.

Request syntax

Note For more information about supported regions, see Regions and OSS endpoints for access in the public cloud.
  • Query the endpoints of all supported regions
    GET /?regions HTTP/1.1
    Host: oss.example.com
    Date: GMT Date
    Authorization: SignatureValue
  • Query the endpoints of a specific region
    GET /?regions=oss-cn-hangzhou HTTP/1.1
    Host: oss.example.com
    Date: GMT Date
    Authorization: SignatureValue

Request headers

This request contains only common request headers. For more information, see Common request headers.

Response headers

This request contains only common response headers. For more information, see Common response headers.

Response elements

Element Type Example Description
RegionInfoList Container N/A The list of region information.

Child nodes: RegionInfo

Parent nodes: none

RegionInfo Container N/A The region information.

Child nodes: Region, InternetEndpoint, InternalEndpoint, and AccelerateEndpoint

Parent nodes: RegionInfoList

Region String oss-cn-hangzhou The ID of the region.

Parent nodes: RegionInfo

InternetEndpoint String oss-cn-hangzhou.aliyuncs.com The public endpoint of the region.

Parent nodes: RegionInfo

InternalEndpoint String oss-cn-hangzhou-internal.aliyuncs.com The internal endpoint of the region.

Parent nodes: RegionInfo

AccelerateEndpoint String oss-accelerate.aliyuncs.com The accelerate endpoint of the region. The value is fixed as oss-accelerate.aliyuncs.com.

Parent nodes: RegionInfo

Examples

  • Query the endpoints of all supported regions
    • Sample requests
      GET /?regions HTTP/1.1
      Host: oss-cn-hangzhou.aliyuncs.com
      Date: Fri, 20 Aug 2021 06:38:30 GMT
      Authorization: SignatureValue
    • Sample responses
      HTTP/1.1 200 OK
      x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
      Date: Fri, 20 Aug 2021 06:38:30 GMT
      Content-Type: application/xml
      Content-Length: 344606
      Server: AliyunOSS
      
      <?xml version="1.0" encoding="UTF-8"?>
      <RegionInfoList>
        <RegionInfo>
           <Region>oss-cn-hangzhou</Region>
           <InternetEndpoint>oss-cn-hangzhou.aliyuncs.com</InternetEndpoint>
           <InternalEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</InternalEndpoint>
           <AccelerateEndpoint>oss-accelerate.aliyuncs.com</AccelerateEndpoint>  
        </RegionInfo>
        <RegionInfo>
           <Region>oss-cn-shanghai</Region>
           <InternetEndpoint>oss-cn-shanghai.aliyuncs.com</InternetEndpoint>
           <InternalEndpoint>oss-cn-shanghai-internal.aliyuncs.com</InternalEndpoint>
           <AccelerateEndpoint>oss-accelerate.aliyuncs.com</AccelerateEndpoint>  
        </RegionInfo>
      </RegionInfoList>
  • Query the endpoints of a specific region
    • Sample requests
      GET /?regions=oss-cn-hangzhou HTTP/1.1
      Host: oss-cn-hangzhou.aliyuncs.com
      Date: Fri, 20 Aug 2021 06:40:30 GMT
      Authorization: SignatureValue
    • Sample responses
      HTTP/1.1 200 OK
      x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
      Date: Fri, 20 Aug 2021 06:40:30 GMT
      Content-Type: application/xml
      Content-Length: 3446
      Server: AliyunOSS
      
      <?xml version="1.0" encoding="UTF-8"?>
      <RegionInfoList>
        <RegionInfo>
          <Region>oss-cn-hangzhou</Region>
          <InternetEndpoint>oss-cn-hangzhou.aliyuncs.com</InternetEndpoint>
          <InternalEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</InternalEndpoint>
          <AccelerateEndpoint>oss-accelerate.aliyuncs.com</AccelerateEndpoint>  
        </RegionInfo>
      </RegionInfoList>

Error codes

Error code HTTP status code Description
AccessDenied 403 Possible causes:
  • The information that is required for user authentication is not passed to or is incorrect in the DescribeRegions request.
  • You do not have the oss:DescribeRegions permission.

    You can configure a custom policy in the Script configuration mode to grant the permission to the specified RAM user. For more information, see Attach a custom policy to a RAM user.

InvalidArgument 400 The error message returned because a specified parameter is invalid.
NoSuchRegion 404 The error message returned because the specified region does not exist.