All Products
Search

This Product

    Cloud Storage Gateway:DescribeGateways

    Document Center

    Cloud Storage Gateway:DescribeGateways

    Last Updated:Aug 04, 2025

    Queries a list of gateways and returns their IDs and names.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that support authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    hcs-sgw:DescribeGateways

    list

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    StorageBundleId

    string

    No

    The ID of the gateway cluster.

    Note

    • If you do not specify ResourceRegionId, you must specify this parameter.

    sb-0001b2otnkdxrigeq***
    PageNumber

    integer

    No

    The page number of the gateway list.

    • Start value: 1.

    • Default value: 1.

    1
    PageSize

    integer

    No

    The number of entries to return on each page for a paged query.

    • Maximum value: 50.

    • Default value: 10.

    10
    ResourceRegionId

    string

    No

    The ID of the region where the resource resides.

    Response parameters

    Parameter

    Type

    Description

    Example

    object

    TotalCount

    integer

    The total number of gateways in the specified gateway cluster.

    2
    RequestId

    string

    The request ID.

    2C4A8287-66F4-45F9-84E3-866E4232C763
    Message

    string

    The description of the request result.

    successful
    PageSize

    integer

    The number of entries returned per page in the gateway list.

    10
    PageNumber

    integer

    The page number of the gateway list.

    1
    Gateways

    object

    Gateway

    array<object>

    The information about the gateways.

    object

    The information about the gateway.

    VpcId

    string

    The ID of the virtual private cloud (VPC).

    vpc-bp1p0usrgr5z9e7lwr***
    Status

    string

    The status of the gateway. Valid values:

    • Initialized: The gateway is initialized.

    • Deactivated: The gateway is not activated.

    • Activated: The gateway is activated.

    • Deploying: The gateway is being deployed.

    • Running: The gateway is running.

    • Stopping: The gateway is being stopped.

    • Stopped: The gateway is stopped.

    • Starting: The gateway is being started.

    • Rebooting: The gateway is being restarted.

    • Deleting: The gateway is being deleted.

    • Failed: The gateway failed to run.

    • Upgrading: The gateway is being upgraded.

    • Modifying: The gateway is being modified.

    • Unknown: No heartbeat is detected for a long time.

    Running
    Type

    string

    See the GatewayType parameter

    File
    Capacity

    integer

    This parameter is deprecated.

    GatewayId

    string

    The gateway ID.

    gw-0001b2odzvl3b1mhi***
    IsReleaseAfterExpiration

    boolean

    Indicates whether the subscription gateway is released after it expires. Valid values:

    • true: The gateway is released after it expires. The service of the Cloud Storage Gateway is stopped seven days after the gateway expires.

    • false: The gateway is converted to a pay-as-you-go gateway after it expires.

    false
    GatewayType

    string

    The type of the gateway

    • File: file gateway

    • Iscsi: iSCSI gateway

    File
    BuyURL

    string

    The purchase URL. This parameter is returned only for subscription gateways.

    https://common-buy-intl.alibabacloud.com/?commodityCode=hcs_sgw_csg_pre&request={"gateway_id":"gw-0007va9bnidei3s8a***”,”directBuy":"false","gateway_class":"standard","cache_cloud_efficiency_size":0}&regionId=cn-hangzhou#/buy
    EcsInstanceId

    string

    The ID of the ECS instance.

    gw-0001b2onkdzvl3b***
    MaxThroughput

    integer

    This parameter is deprecated.

    GatewayClass

    string

    The gateway class. Valid values:

    • Basic: Basic.

    • Standard: Medium.

    • Enhanced: Enhanced.

    • Advanced: Performance.

    Advanced
    InnerIp

    string

    The mount IP address.

    172.16.0.21
    Description

    string

    The description of the gateway.

    Name

    string

    The name of the gateway.

    fio-weekly***
    InnerIpv6Ip

    string

    The IPv6 address.

    CreatedTime

    integer

    The time when the gateway was created. This value is a UNIX timestamp. Unit: seconds.

    1577179604
    ExpireStatus

    integer

    The expiration status of the gateway. Valid values:

    • 0: Normal.

    • 1: The gateway is about to expire.

    • 2: The gateway has expired.

    0
    DataLoadInterval

    integer

    This parameter is deprecated.

    RenewURL

    string

    The renewal URL.

    https://common-buy-intl.alibabacloud.com/?commodityCode=hcs_sgw_csg_pre&orderType=RENEW&instanceId=ca-0007va9bnideidndnu72#/renew
    IsPostPaid

    boolean

    The billing method. Valid values:

    • true: pay-as-you-go.

    • false: subscription.

    true
    PublicNetworkBandwidth

    integer

    The public bandwidth for data transmission. Unit: Mbit/s. This parameter is supported only by gateways deployed on Alibaba Cloud.

    55
    StorageBundleId

    string

    The ID of the gateway cluster.

    sb-0001b2otrigeqkso***
    Ip

    string

    The public IP address.

    47.111.145.66
    LastErrorKey

    string

    The error keyword.

    ElasticNodes

    object

    ElasticNode

    array

    This parameter is deprecated.

    string

    This parameter is deprecated.

    VSwitchId

    string

    The ID of the vSwitch.

    vsw-bp1krhkgnahkb9stp0***
    CommonBuyInstanceId

    string

    The ID of the instance in the sales system. This parameter is returned only for subscription gateways.

    gw-0001b2onkdzvl3b***
    ExpiredTime

    integer

    The expiration time. This value is a UNIX timestamp. Unit: seconds.

    1532426471
    GatewayVersion

    string

    The gateway version.

    1.2.6
    DataLoadType

    string

    This parameter is deprecated.

    ElasticGateway

    boolean

    This parameter is deprecated.

    Category

    string

    The gateway category.

    • Default: Aliyun.

    Aliyun
    ActivatedTime

    integer

    The activation time. This value is a UNIX timestamp. Unit: seconds.

    1577179769
    TaskId

    string

    The task ID.

    t-000978oflgrd8ah6p***
    Location

    string

    The location of the gateway. Valid values:

    • Cloud: a gateway deployed on Alibaba Cloud.

    • On_Premise: a gateway deployed in a data center.

    Cloud
    GatewayRegionId

    string

    The region of the gateway.

    UntrustedEnvInstanceType

    string

    The actual gateway class in an untrusted environment (CloudBox).

    HighAvailability

    boolean

    Indicates whether the gateway is a cross-zone high availability (HA) gateway. The return values are as follows:

    • true: The gateway is a cross-zone HA gateway.

    • false: The gateway is not a cross-zone HA gateway.

    SecondaryVSwitchId

    string

    The ID of the vSwitch. This parameter is supported only by HA gateways.

    Code

    string

    The status code. A status code of 200 indicates that the request was successful.

    200
    Success

    boolean

    Indicates whether the request was successful.

    true

    Examples

    Success response

    JSON format

    {
  "TotalCount": 2,
  "RequestId": "2C4A8287-66F4-45F9-84E3-866E4232C763",
  "Message": "successful",
  "PageSize": 10,
  "PageNumber": 1,
  "Gateways": {
    "Gateway": [
      {
        "VpcId": "vpc-bp1p0usrgr5z9e7lwr***",
        "Status": "Running",
        "Type": "File",
        "Capacity": 0,
        "GatewayId": "gw-0001b2odzvl3b1mhi***",
        "IsReleaseAfterExpiration": false,
        "GatewayType": "File",
        "BuyURL": "https://common-buy-intl.alibabacloud.com/?commodityCode=hcs_sgw_csg_pre&request={\"gateway_id\":\"gw-0007va9bnidei3s8a***”,”directBuy\":\"false\",\"gateway_class\":\"standard\",\"cache_cloud_efficiency_size\":0}&regionId=cn-hangzhou#/buy",
        "EcsInstanceId": "gw-0001b2onkdzvl3b***",
        "MaxThroughput": 0,
        "GatewayClass": "Advanced",
        "InnerIp": "172.16.0.21",
        "Description": "",
        "Name": "fio-weekly***",
        "InnerIpv6Ip": "",
        "CreatedTime": 1577179604,
        "ExpireStatus": 0,
        "DataLoadInterval": 0,
        "RenewURL": "https://common-buy-intl.alibabacloud.com/?commodityCode=hcs_sgw_csg_pre&orderType=RENEW&instanceId=ca-0007va9bnideidndnu72#/renew",
        "IsPostPaid": true,
        "PublicNetworkBandwidth": 55,
        "StorageBundleId": "sb-0001b2otrigeqkso***",
        "Ip": "47.111.145.66",
        "LastErrorKey": "",
        "ElasticNodes": {
          "ElasticNode": [
            ""
          ]
        },
        "VSwitchId": "vsw-bp1krhkgnahkb9stp0***",
        "CommonBuyInstanceId": "gw-0001b2onkdzvl3b***",
        "ExpiredTime": 1532426471,
        "GatewayVersion": "1.2.6",
        "DataLoadType": "",
        "ElasticGateway": true,
        "Category": "Aliyun",
        "ActivatedTime": 1577179769,
        "TaskId": "t-000978oflgrd8ah6p***",
        "Location": "Cloud",
        "GatewayRegionId": "",
        "UntrustedEnvInstanceType": "",
        "HighAvailability": true,
        "SecondaryVSwitchId": ""
      }
    ]
  },
  "Code": "200",
  "Success": true
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 EmptyStorageBundleId You must enter a valid ID for the gateway cluster. You must enter a valid ID for the gateway cluster.
    400 BadPageSize The specified number of pages is invalid. The number ranges from 1 to 50. The specified number of pages is invalid. The number ranges from 1 to 50.
    400 BadPageNumber The specified page number is invalid. The page number must be greater than 0. The specified page number is invalid. The page number must be greater than 0.
    404 StorageBundleNotExist The name you specified for the gateway cluster does not exist. You must specify a valid parameter. The name you specified for the gateway cluster does not exist. You must specify a valid parameter.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.