Tag_Operations for the Amazon EC2 REST adapter


This topic illustrates the adapter requests and responses for Tag operations.

Create Tags operation

The Create Tags operation enables you to add or overwrite tags for the specified resources. Each resource can have a maximum of 10 tags. Each tag consists of a key and an optional value. Tag keys must be unique per resource.

The following figure shows a sample <items> XML element for the Create Tags operation. 

Sample <items> XML element for the Create Tags operation 

<items>
 <item>
   <parameters>
     <resources-set>
       <!--Zero or more repetition-->
       <item>
         <resource-id></resource-id>
       </item>
     </resources-set>
     <tag-set>
       <!--Zero or more repetition-->
       <item>
         <key></key>
         <value></value>
       </item>
     </tag-set>
   </parameters>
 </item>
</items>

The following table describes the elements for this adapter request. 

Adapter request elements for the Create Tags operation 

Element

Definition

Required

<access-key>

Specifies the Amazon Web Services (AWS) access key

You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Access Key is specified, the adapter ignores the value.
<secret-key>

Specifies the AWS secret access key

You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Secret Access Key is specified, the adapter ignores the value.
<region>

Specifies the region with which you want the adapter to communicate

Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions.

Valid values:

  • us-east-1
  • us-west-2 (default)
  • us-west-1
  • eu-west-1
  • ap-southeast-1
  • ap-northeast-1
  • ap-southeast-2
  • sa-east-1

No

<operation-name>

Contains the name of the operation: create-tags

Yes

<parameters>

Contains the elements required to execute the operation

Yes

<resources-set>

Specifies the set of resource IDs details to which you must apply the tags

Yes

<tag-set>

Specifies the tags that you must apply to the resources

Yes

The following figure shows a sample adapter request for the Create Tags operation. 

Sample adapter request for the Create Tags operation 

<amazon-ec2-rest-request>
   <access-key>AKIAI**********GROKA</access-key>
   <secret-key>6hXjoZZDvWx**********1y2Yte/jZfnY6WgKCdC</secret-key>
   <operation-name>create-tags</operation-name>
   <region>us-west-2</region>
   <parameters>
     <resources-set>
       <item>
         <resource-id>i-1a1c2213</resource-id>
       </item>
     </resources-set>
     <tag-set>
       <item>
         <key>Name</key>
         <value>Amazon Windows First</value>
       </item>
       <item>
         <key>Type</key>
         <value>WebServer</value>
       </item>
     </tag-set>
   </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample Create Tags operation. 

Sample adapter response for the Create Tags operation 

<amazon-ec2-rest-response>
 <metadata>
   <status>success</status>
 </metadata>
 <CreateTagsResponse>
   <return>true</return>
 </CreateTagsResponse>
</amazon-ec2-rest-response>

  Back to top 

Delete Tags operation

The Delete Tags operation enables you to delete a specific set of tags from a specific set of resources.

The following figure shows a sample <items> XML element for the Delete Tags operation. 

Sample <items> XML element for the Delete Tags operation 

<items>
 <item>
   <parameters>
     <resources-set>
       <!--Zero or more repetition-->
       <item>
         <resource-id></resource-id>
       </item>
     </resources-set>
     <tag-set>
       <!--Zero or more repetition-->
       <item>
         <key></key>
         <value></value>
       </item>
     </tag-set>
   </parameters>
 </item>
</items>

The following table describes the elements for this adapter request. 

Adapter request elements for the Delete Tags operation 

Element

Definition

Required

<access-key>

Specifies the Amazon Web Services (AWS) access key

You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Access Key is specified, the adapter ignores the value.
<secret-key>

Specifies the AWS secret access key

You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Secret Access Key is specified, the adapter ignores the value.
<region>

Specifies the region with which you want the adapter to communicate

Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions.

Valid values:

  • us-east-1
  • us-west-2 (default)
  • us-west-1
  • eu-west-1
  • ap-southeast-1
  • ap-northeast-1
  • ap-southeast-2
  • sa-east-1

No

<operation-name>

Contains the name of the operation: delete-tags

Yes

<parameters>

Contains the elements required to execute the operation

Yes

<resources-set>

Specifies the resource details from which to delete the tags

Yes

<tag-set>

Specifies the tags to remove from the resources

Yes

The following figure shows a sample adapter request for the Delete Tags operation. 

Sample adapter request for the Delete Tags operation 

<amazon-ec2-rest-request>
   <access-key>AKIAI**********GROKA</access-key>
   <secret-key>6hXjoZZDvW**********n1y2Yte/jZfnY6WgKCdC</secret-key>
   <operation-name>delete-tags</operation-name>
   <region>us-west-2</region>
   <parameters>
     <resources-set>
       <item>
         <resource-id>i-1a1c2213</resource-id>
       </item>
     </resources-set>
     <tag-set>
       <item>
         <key>Type</key>
         <value>WebServer</value>
       </item>
     </tag-set>
   </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample Delete Tags operation. 

Sample adapter response for the Delete Tags operation 

<amazon-ec2-rest-response>
 <metadata>
   <status>success</status>
 </metadata>
 <DeleteTagsResponse>
   <return>true</return>
 </DeleteTagsResponse>
</amazon-ec2-rest-response>

 Back to top

Describe Tags operation

The Describe Tags operation enables you to list your tags. You can use filters to limit the results of the Describe Tags operation. For example, you can retrieve the tags for a particular resource type only. Further, you can specify multiple filters that limit the results to a specific resource type and retrieve tags with values that contain a specified string only. However, at least one of the specified values must match an existing tag to obtain results. The result includes information for a particular tag only if it matches all the specified filters. If there is no match, no special message is returned; the response is empty.

You can use wild card characters with the filters:

  • Use the asterisk (*) to match any number of characters.
  • Use the question mark (?) to match a single character.

If you want to use any special characters or metacharacters such as *, +, (, ^, [, and so on that have a special meaning in searches, escape the special character by preceding it with a backslash (\ ).

The following table shows the available filters:

Filter Name

Description

<key>

Specifies the tag key 

Valid value: Any string

<resource-id>

Specifies the resource ID 

Valid value: Any string

<resource-type>

Specifies the resource type 

Valid values:

  • customer-gateway
  • dhcp-options
  • image
  • instance
  • internet-gateway
  • network-acl
  • reserved-instances
  • route-table
  • security-group
  • snapshot
  • spot-instances-request
  • subnet
  • volume
  • vpn-connection
  • vpn-gateway
<value>

Specifies the tag value 

Valid value: Any string

The following figure shows a sample <items> XML element for the Describe Tags operation. 

Sample <items> XML element for the Describe Tags operation 

<items>
 <item>
   <parameters>
     <filter-set>
       <item>
         <name></name>
         <value-set>
       <item>
         <value></value>
       </item>
         </value-set>
       </item>
       <item>
         <name></name>
         <value-set>
           <item>
             <value></value>
           </item>
         </value-set>
       </item>
       <item>
         <name></name>
         <value-set>
           <item>
             <value></value>
           </item>
         </value-set>
       </item>
       <item>
         <name></name>
         <value-set>
           <item>
             <value></value>
           </item>
         </value-set>
       </item>
     </filter-set>
   </parameters>
 </item>
</items> 

The following table describes the elements for this adapter request. 

Adapter request elements for the Describe Tags operation 

Element

Definition

Required

<access-key>

Specifies the Amazon Web Services (AWS) access key

You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Access Key is specified, the adapter ignores the value.
<secret-key>

Specifies the AWS secret access key

You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Secret Access Key is specified, the adapter ignores the value.
<region>

Specifies the region with which you want the adapter to communicate

Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions.

Valid values:

  • us-east-1
  • us-west-2 (default)
  • us-west-1
  • eu-west-1
  • ap-southeast-1
  • ap-northeast-1
  • ap-southeast-2
  • sa-east-1

No

<operation-name>

Contains the name of the operation: describe-tags

Yes

<parameters>

Contains the elements required to execute the operation

Yes

<filter-set>

Specifies the filter used to retrieve the resources

Yes

The following figure shows a sample adapter request for the Describe Tags operation. 

Sample adapter request for the Describe Tags operation 

<amazon-ec2-rest-request>
   <access-key>AKIAI**********GROKA</access-key>
   <secret-key>6hXjoZZDvWx**********1y2Yte/jZfnY6WgKCdC</secret-key>
   <operation-name>describe-tags</operation-name>
   <region>us-west-2</region>
   <parameters>
     <filter-set>
       <item>
         <name>value</name>
         <value-set>
           <item>
             <value>WebServer</value>
           </item>
         </value-set>
       </item>
     </filter-set>
   </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample Describe Tags operation. 

Sample adapter response for the Describe Tags operation 

<amazon-ec2-rest-response>
 <metadata>
   <status>success</status>
 </metadata>
 <DescribeTagsResponse>
   <tagSet>
     <item>
       <resourceId>i-1a1c2213</resourceId>
       <resourceType>instance</resourceType>
       <key>Type</key>
       <value>WebServer</value>
     </item>
   </tagSet>
 </DescribeTagsResponse>
</amazon-ec2-rest-response>

Back to top

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*