Filtering Resources by Region ID

You can use a filter in the IaaS APIs to identify resources provisioned in a cloud account of a particular region. By specifying the resources for which you want information such as network and security, compute, storage, and tags content, you limit the API response to provide only the information that you want.

You can also use filtering to identify and automatically update resources. For example, if you have automated builds on an vSphere private cloud account, you can use filtering to identify the image profiles associated with a region of the cloud account and automatically update those profiles in Automation.

Obtaining the externalRegionID and cloudAccountId

To get information about a resource that is in a region of a cloud account, you filter by its externalRegionId and its cloudAccountId. The following example shows how to obtain the IDs for a vSphere cloud account and use them to construct a generic query. It assumes that all general prerequisites and prerequisites for the Automation Assembler Infrastructure as a Service (IaaS) service have been satisfied. See Prerequisites for API Use Case Examples.

List vSphere cloud accounts.

curl -X GET "$url/iaas/api/cloud-accounts?apiVersion=$api_version&"'$filter='"cloudAccountType%20eq%20'vsphere'" -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token"  | jq "."

Examine the response to obtain the cloud account ID and region ID for the vSphere account that you want.

...
        },
        "name": "vc60",
        "description": "Created by User",
        "id": "e0f23c91d5ecca75-7f703c5265a63d87-7e3d8d60a55d1306cc791422547ead9153c3bdf1c802400819ad45a341cba1f3-c39814fe67b8247557cab2652647d",
        "updatedAt": "2022-04-02",
        "organizationId": "f670fdfc-66d6-4689-9793-d524e7066d1e",
        "orgId": "f670fdfc-66d6-4689-9793-d524e7066d1e",
        "_links": {
          "regions": {
            "hrefs": [
              "/iaas/api/regions/277e3cd9fe87527557cab268cae5a"
            ]
          },
...

Assign the cloud account ID and region ID variables.

cloud_account_id='e0f23c91d5ecca75-7f703c5265a63d87-7e3d8d60a55d1306cc791422547ead9153c3bdf1c802400819ad45a341cba1f3-c39814fe67b8247557cab2652647d'
region_id='277e3cd9fe87527557cab268cae5a'

List regions with the region ID and associated with the cloud account ID.

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/iaas/api/regions/?apiVersion=$api_version&"'$filter'"=id%20eq%20'"$region_id"'%20and%20cloudAccountId%20eq%20'"$cloud_account_id"'"  | jq "."

Examine the response to obtain the external region ID.

...
          {      
            "externalRegionId": "Datacenter:datacenter-2",
            "name": "VC60-Datacenter",
            "cloudAccountId": "e0f23c91d5ecca75-7f703c5265a63d87-7e3d8d60a55d1306cc791422547ead9153c3bdf1c802400819ad45a341cba1f3-c39814fe67b8247557cab2652647d",
            "id": "277e3cd9fe87527557cab268cae5a",
            "updatedAt": "2022-04-02",
...

Assign the external region ID variable.

external_region_id='Datacenter:datacenter-2'

Using the externalRegionId and cloudAccountId, you can construct a generic filter to use in any IaaS API that queries for resources.

$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"

Constructing a query for a VMC cloud account

The VMC cloud account consists of an AWS cloud account facade and associated internal vSphere and NSX cloud accounts. To construct the query for a resource in the VMC cloud account, you use the cloudAccountId of the associated vSphere cloud account and not the cloudAccountId of the VMC cloud account.

The following example shows how to obtain the cloudAccountId and externalRegionId and use them to construct a generic query. It assumes that you know the name of the VMC cloud account and that all general prerequisites and prerequisites for the Automation Assembler Infrastructure as a Service (IaaS) service have been satisfied. See Prerequisites for API Use Case Examples.

Assign the cloud account name variable.

cloud_account_name='<my_vmc_cloud_account>'

List VMC cloud accounts with your VMC cloud account name.

curl -X GET "$url/iaas/api/cloud-accounts?apiVersion=$api_version&"'$filter='"cloudAccountType%20eq%20'vmc'%20and%20name%20eq%20'$cloud_account_name'"  -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token"  | jq "."

Examine the response to obtain the cloud account ID for the associated vSphere cloud account.

Under _links, two associated cloud accounts are listed. The first cloud account is the vSphere cloud account. The second is the NSX cloud account.

...
       "_links": {
                "regions": {
                    "hrefs": [
                        "/iaas/api/regions/5a8da7fe-63d9-4f82-84e8-f47bfdfef43c"
                    ]
                },
                "associated-cloud-accounts": {
                    "hrefs": [
                        "/iaas/api/cloud-accounts/df59d7cd-d3ee-4bc3-bf4a-8a4027cefb05",
                        "/iaas/api/cloud-accounts/6993943b-82bc-4ec7-bad6-65f2f595da7e"
                    ]
                },
                "self": {
                    "href": "/iaas/api/cloud-accounts/95be1cc2-c70a-4311-9f18-6218786ac51b"
                }
            }

...

To assign the cloud account ID variable, use the associated vSphere cloud account.
```
assoc_cloud_account_id='df59d7cd-d3ee-4bc3-bf4a-8a4027cefb05'
```

List regions in the associated vSphere cloud account.

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/iaas/api/regions/?apiVersion=$api_version&"'$filter'"=cloudAccountId%20eq%20'"$assoc_cloud_account_id"'"  | jq "."

Examine the response to obtain the external region ID.

...
         {
            "externalRegionId": "Datacenter:datacenter-3",
            "cloudAccountId": "df59d7cd-d3ee-4bc3-bf4a-8a4027cefb05",
            "id": "e572c96b-9084-4c37-b74d-bf61f0b08e79",
            "updatedAt": "2022-04-02",
            "organizationId": "33a92056-18f0-469c-a088-9c8eae4e4888",
            "orgId": "33a92056-18f0-469c-a088-9c8eae4e4888",
            "_links": {
                "self": {
                    "href": "/iaas/api/regions/e572c96b-9084-4c37-b74d-bf61f0b08e79"
                },
                "cloud-account": {
                    "href": "/iaas/api/cloud-accounts/df59d7cd-d3ee-4bc3-bf4a-8a4027cefb05"
                }
            }
        }

...

Assign the external region ID variable.

external_region_id='Datacenter:datacenter-3'

Using the externalRegionId and cloudAccountId for the associated vSphere cloud account, you can construct a generic filter to use in any IaaS API that queries for resources in the VMC cloud account.

$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$assoc_cloud_account_id'"

Resource Query Examples

The following examples show how to incorporate the filter into resource queries.

Resource	Query
Security Group	$url/iaas/api/security-groups?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Security Group (NSX only)	$url/iaas/api/security-groups?$filter="externalRegionId%20eq%20'global'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Region	$url/iaas/api/regions?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Network	$url/iaas/api/networks?$filter="externalRegionId%20eq%20'$region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Network Domains	$url/iaas/api/network-domains?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Machine	$url/iaas/api/machines?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Load Balancer	$url/iaas/api/load-balancers?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Fabric vSphere Datastore	$url/iaas/api/fabric-vsphere-datastores?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Fabric Network vSphere	$url/iaas/api/fabric-networks-vsphere?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Fabric Network	$url/iaas/api/fabric-networks?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Fabric Compute	$url/iaas/api/fabric-computes?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Block Device	$url/iaas/api/block-devices?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Network Profile	$url/iaas/api/network-profiles?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Flavor Profile	$url/iaas/api/flavor-profiles?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Image Profiles	$url/iaas/api/image-profiles?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Storage Profiles	$url/iaas/api/storage-profiles?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Storage Profiles Azure	$url/iaas/api/storage-profiles-azure?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Storage Profiles AWS	$url/iaas/api/storage-profiles-aws?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"
Storage Profiles vSphere	$url/iaas/api/storage-profiles-vsphere?$filter="externalRegionId%20eq%20'$external_region_id'%20and%20cloudAccountId%20eq%20'$cloud_account_id'"