Boto3 Readthedocs Io en Latest
Uploaded by
Mahesh NagasaiBoto3 Readthedocs Io en Latest
Uploaded by
Mahesh NagasaiBoto3 Documentation
Release 1.1.4
Amazon.com, Inc.
September 28, 2015
Contents
1 Quickstart 3
1.1 Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 A Sample Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 User Guide 9
2.1 User Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 API Reference 39
3.1 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.2 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4634
3.3 Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4647
4 Indices and tables 4655
Python Module Index 4657
i
ii
Boto3 Documentation, Release 1.1.4
Boto is the Amazon Web Services (AWS) SDK for Python, which allows Python developers to write software that
makes use of Amazon services like S3 and EC2. Boto provides an easy to use, object-oriented API as well as low-
level direct service access.
Contents 1
Boto3 Documentation, Release 1.1.4
2 Contents
CHAPTER 1
Quickstart
1.1 Quickstart
Getting started with Boto 3 is easy, but requires a few steps.
1.1.1 Installation
Install the latest Boto 3 release via pip:
pip install boto3
You may also install a specific version:
pip install boto3==1.0.0
Note: The latest development version can always be found on GitHub.
1.1.2 Configuration
Before you can begin using Boto 3, you should set up authentication credentials. Credentials for your AWS account
can be found in the IAM Console. You can create or use an existing user. Go to manage access keys and generate a
new set of keys.
If you have the AWS CLI installed, then you can use it to configure your credentials file:
aws configure
Alternatively, you can create the credential file yourself. By default, its location is at ~/.aws/credentials:
[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY
You may also want to set a default region. This can be done in the configuration file. By default, its location is at
~/.aws/config:
[default]
region=us-east-1
3
Boto3 Documentation, Release 1.1.4
Alternatively, you can pass a region_name when creating clients and resources.
This sets up credentials for the default profile as well as a default region to use when creating connections. See
Configuration for in-depth configuration sources and options.
1.1.3 Using Boto 3
To use Boto 3, you must first import it and tell it what service you are going to use:
import boto3
# Let's use Amazon S3
s3 = boto3.resource('s3')
Now that you have an s3 resource, you can make requests and process responses from the service. The following uses
the buckets collection to print out all bucket names:
# Print out bucket names
for bucket in s3.buckets.all():
print(bucket.name)
It’s also easy to upload and download binary data. For example, the following uploads a new file to S3. It assumes
that the bucket my-bucket already exists:
# Upload a new file
data = open('test.jpg', 'rb')
s3.Bucket('my-bucket').put_object(Key='test.jpg', Body=data)
Resources and Collections will be covered in more detail in the following sections, so don’t worry if you do not
completely understand the examples.
1.2 A Sample Tutorial
This tutorial will show you how to use Boto3 with an AWS service. In this sample tutorial, you will learn how to use
Boto3 with Amazon Simple Queue Service (SQS)
1.2.1 SQS
SQS allows you to queue and then process messages. This tutorial covers how to create a new queue, get and use
an existing queue, push new messages onto the queue, and process messages from the queue by using Resources and
Collections.
1.2.2 Creating a Queue
Queues are created with a name. You may also optionally set queue attributes, such as the number of seconds to wait
before an item may be processed. The examples below will use the queue name test. Before creating a queue, you
must first get the SQS service resource:
# Get the service resource
sqs = boto3.resource('sqs')
# Create the queue. This returns an SQS.Queue instance
queue = sqs.create_queue(QueueName='test', Attributes={'DelaySeconds': '5'})
4 Chapter 1. Quickstart
Boto3 Documentation, Release 1.1.4
# You can now access identifiers and attributes
print(queue.url)
print(queue.attributes.get('DelaySeconds'))
Reference: SQS.ServiceResource.create_queue()
Warning: The code above may throw an exception if you already have a queue named test.
1.2.3 Using an Existing Queue
It is possible to look up a queue by its name. If the queue does not exist, then an exception will be thrown:
# Get the service resource
sqs = boto3.resource('sqs')
# Get the queue. This returns an SQS.Queue instance
queue = sqs.get_queue_by_name(QueueName='test')
# You can now access identifiers and attributes
print(queue.url)
print(queue.attributes.get('DelaySeconds'))
It is also possible to list all of your existing queues:
# Print out each queue name, which is part of its ARN
for queue in sqs.queues.all():
print(queue.url)
Note: To get the name from a queue, you must use its ARN, which is available in the queue’s attributes attribute.
Using queue.attributes[’QueueArn’].split(’:’)[-1] will return its name.
Reference: SQS.ServiceResource.get_queue_by_name(), SQS.ServiceResource.queues
1.2.4 Sending Messages
Sending a message adds it to the end of the queue:
# Get the service resource
sqs = boto3.resource('sqs')
# Get the queue
queue = sqs.get_queue_by_name(QueueName='test')
# Create a new message
response = queue.send_message(MessageBody='world')
# The response is NOT a resource, but gives you a message ID and MD5
print(response.get('MessageId'))
print(response.get('MD5OfMessageBody'))
You can also create messages with custom attributes:
queue.send_message(MessageBody='boto3', MessageAttributes={
'Author': {
1.2. A Sample Tutorial 5
Boto3 Documentation, Release 1.1.4
'StringValue': 'Daniel',
'DataType': 'string'
}
})
Messages can also be sent in batches. For example, sending the two messages described above in a single request
would look like the following:
response = queue.send_messages(Entries=[
{
'Id': '1',
'MessageBody': 'world'
},
{
'Id': '2',
'MessageBody': 'boto3',
'MessageAttributes': {
'Author': {
'StringValue': 'Daniel',
'DataType': 'string'
}
}
}
])
# Print out any failures
print(response.get('Failed'))
In this case, the response contains lists of Successful and Failed messages, so you can retry failures if needed.
Reference: SQS.Queue.send_message(), SQS.Queue.send_messages()
1.2.5 Processing Messages
Messages are processed in batches:
# Get the service resource
sqs = boto3.resource('sqs')
# Get the queue
queue = sqs.get_queue_by_name(QueueName='test')
# Process messages by printing out body and optional author name
for message in queue.receive_messages(MessageAttributeNames=['Author']):
# Get the custom author message attribute if it was set
author_text = ''
if message.message_attributes is not None:
author_name = message.message_attributes.get('Author').get('StringValue')
if author_name:
author_text = ' ({0})'.format(author_name)
# Print out the body and author (if set)
print('Hello, {0}!{1}'.format(message.body, author_text))
# Let the queue know that the message is processed
message.delete()
6 Chapter 1. Quickstart
Boto3 Documentation, Release 1.1.4
Given only the messages that were sent in a batch with SQS.Queue.send_messages() in the previous section,
the above code will print out:
Hello, world!
Hello, boto3! (Daniel)
Reference: SQS.Queue.receive_messages(), SQS.Message.delete()
1.2. A Sample Tutorial 7
Boto3 Documentation, Release 1.1.4
8 Chapter 1. Quickstart
CHAPTER 2
User Guide
2.1 User Guides
2.1.1 Migration Guides
What’s New
Boto 3 is a ground-up rewrite of Boto. It uses a data-driven approach to generate classes at runtime from JSON
description files that are shared between SDKs in various languages. This includes descriptions for a high level, object
oriented interface similar to those availabe in previous versions of Boto.
Because Boto 3 is generated from these shared JSON files, we get fast updates to the latest services and features and
a consistent API across services. Community contributions to JSON description files in other SDKs also benefit Boto
3, just as contributions to Boto 3 benefit the other SDKs.
Major Features
Boto 3 consists of the following major features:
• Resources: a high level, object oriented interface
• Collections: a tool to iterate and manipulate groups of resources
• Clients: low level service connections
• Paginators: automatic paging of responses
• Waiters: a way to block until a certain state has been reached
Along with these major features, Boto 3 also provides sessions and per-session credentials & configuration, as well as
basic components like authentication, parameter & response handling, an event system for customizations and logic
to retry failed requests.
Botocore Boto 3 is built atop of a library called Botocore, which is shared by the AWS CLI. Botocore provides the
low level clients, session, and credential & configuration data. Boto 3 builds on top of Botocore by providing its own
session, resources and collections.
9
Boto3 Documentation, Release 1.1.4
Migrating from Boto 2.x
Current Boto users can begin using Boto 3 right away. The two modules can live side-by-side in the same project,
which means that a piecemeal approach can be used. New features can be written in Boto 3, or existing code can be
migrated over as needed, piece by piece.
High Level Concepts
Boto 2.x modules are typically split into two categories, those which include a high-level object-oriented interface
and those which include only a low-level interface which matches the underlying Amazon Web Services API. Some
modules are completely high-level (like Amazon S3 or EC2), some include high-level code on top of a low-level
connection (like Amazon DynamoDB), and others are 100% low-level (like Amazon Elastic Transcoder).
In Boto 3 this general low-level and high-level concept hasn’t changed much, but there are two important points to
understand.
Data Driven First, in Boto 3 classes are created at runtime from JSON data files that describe AWS APIs and
organizational structures built atop of them. These data files are loaded at runtime and can be modified and updated
without the need of installing an entirely new SDK release.
A side effect of having all the services generated from JSON files is that there is now consistency between all AWS ser-
vice modules. One important change is that all API call parameters must now be passed as keyword arguments, and
these keyword arguments take the form defined by the upstream service. Though there are exceptions, this typically
means UpperCamelCasing parameter names. You will see this in the service-specific migration guides linked to
below.
Resource Objects Second, while every service now uses the runtime-generated low-level client, some services
additionally have high-level generated objects that we refer to as Resources. The lower-level is comparable to
Boto 2.x layer 1 connection objects in that they provide a one to one mapping of API operations and return low-
level responses. The higher level is comparable to the high-level customizations from Boto 2.x: an S3 Key, an EC2
Instance, and a DynamoDB Table are all considered resources in Boto 3. Just like a Boto 2.x S3Connection‘s
list_buckets will return Bucket objects, the Boto 3 resource interface provides actions and collections that
return resources. Some services may also have hand-written customizations built on top of the runtime-generated
high-level resources (such as utilities for working with S3 multipart uploads).
import boto, boto3
# Low-level connections
conn = boto.connect_elastictranscoder()
client = boto3.client('elastictranscoder')
# High-level connections & resource objects
from boto.s3.bucket import Bucket
s3_conn = boto.connect_s3()
boto2_bucket = Bucket('mybucket')
s3 = boto3.resource('s3')
boto3_bucket = s3.Bucket('mybucket')
Installation & Configuration
The Quickstart guide provides instructions for installing Boto 3. You can also follow the instructions there to set up
new credential files, or you can continue to use your existing Boto 2.x credentials. Please note that Boto 3, the AWS
10 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
CLI, and several other SDKs all use the shared credentials file (usually at ~/.aws/credentials).
Once configured, you may begin using Boto 3:
import boto3
for bucket in boto3.resource('s3').buckets.all():
print(bucket.name)
See the tutorial_list and Boto 3 Documentation for more information.
The rest of this document will describe specific common usage scenarios of Boto 2 code and how to accomplish the
same tasks with Boto 3.
Services
Amazon S3 Boto 2.x contains a number of customizations to make working with Amazon S3 buckets and keys easy.
Boto 3 exposes these same objects through its resources interface in a unified and consistent way.
Creating the Connection Boto 3 has both low-level clients and higher-level resources. For Amazon S3, the higher-
level resources are the most similar to Boto 2.x’s s3 module:
# Boto 2.x
import boto
s3_connection = boto.connect_s3()
# Boto 3
import boto3
s3 = boto3.resource('s3')
Creating a Bucket Creating a bucket in Boto 2 and Boto 3 is very similar, except that in Boto 3 all action parameters
must be passed via keyword arguments and a bucket configuration must be specified manually:
# Boto 2.x
s3_connection.create_bucket('mybucket')
s3_connection.create_bucket('mybucket', location=Location.USWest)
# Boto 3
s3.create_bucket(Bucket='mybucket')
s3.create_bucket(Bucket='mybucket', CreateBucketConfiguration={
'LocationConstraint': 'us-west-1'})
Storing Data Storing data from a file, stream, or string is easy:
# Boto 2.x
from boto.s3.key import Key
key = Key('hello.txt')
key.set_contents_from_file('/tmp/hello.txt')
# Boto 3
s3.Object('mybucket', 'hello.txt').put(Body=open('/tmp/hello.txt', 'rb'))
2.1. User Guides 11
Boto3 Documentation, Release 1.1.4
Accessing a Bucket Getting a bucket is easy with Boto 3’s resources, however these do not automatically validate
whether a bucket exists:
# Boto 2.x
bucket = s3_connection.get_bucket('mybucket', validate=False)
exists = s3_connection.lookup('mybucket')
# Boto 3
import botocore
bucket = s3.Bucket('mybucket')
exists = True
try:
s3.meta.client.head_bucket(Bucket='mybucket')
except botocore.exceptions.ClientError as e:
# If a client error is thrown, then check that it was a 404 error.
# If it was a 404 error, then the bucket does not exist.
error_code = int(e.response['Error']['Code'])
if error_code == 404:
exists = False
Deleting a Bucket All of the keys in a bucket must be deleted before the bucket itself can be deleted:
# Boto 2.x
for key in bucket:
key.delete()
bucket.delete()
# Boto 3
for key in bucket.objects.all():
key.delete()
bucket.delete()
Iteration of Buckets and Keys Bucket and key objects are no longer iterable, but now provide collection attributes
which can be iterated:
# Boto 2.x
for bucket in s3_connection:
for key in bucket:
print(key.name)
# Boto 3
for bucket in s3.buckets.all():
for key in bucket.objects.all():
print(key.key)
Access Controls Getting and setting canned access control values in Boto 3 operates on an ACL resource object:
# Boto 2.x
bucket.set_acl('public-read')
key.set_acl('public-read')
# Boto 3
bucket.Acl().put(ACL='public-read')
obj.put(ACL='public-read')
It’s also possible to retrieve the policy grant information:
12 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
# Boto 2.x
acp = bucket.get_acl()
for grant in acp.acl.grants:
print(grant.display_name, grant.permission)
# Boto 3
acl = bucket.Acl()
for grant in acl.grants:
print(grant['DisplayName'], grant['Permission'])
Boto 3 lacks the grant shortcut methods present in Boto 2.x, but it is still fairly simple to add grantees:
# Boto 2.x
bucket.add_email_grant('READ', '[email protected]')
# Boto 3
bucket.Acl.put(GrantRead='[email protected]')
Key Metadata It’s possible to set arbitrary metadata on keys:
# Boto 2.x
key.set_metadata('meta1', 'This is my metadata value')
print(key.get_metadata('meta1'))
# Boto 3
key.put(Metadata={'meta1': 'This is my metadata value'})
print(key.metadata['meta1'])
Managing CORS Configuration Allows you to manage the cross-origin resource sharing configuration for S3
buckets:
# Boto 2.x
cors = bucket.get_cors()
config = CORSConfiguration()
config.add_rule('GET', '*')
bucket.set_cors(config)
bucket.delete_cors()
# Boto 3
cors = bucket.Cors()
config = {
'CORSRules': [
{
'AllowedMethods': ['GET'],
'AllowedOrigins': ['*']
}
]
}
cors.put(CORSConfiguration=config)
cors.delete()
2.1. User Guides 13
Boto3 Documentation, Release 1.1.4
Amazon EC2 Boto 2.x contains a number of customizations to make working with Amazon EC2 instances, storage
and networks easy. Boto 3 exposes these same objects through its resources interface in a unified and consistent way.
Creating the Connection Boto 3 has both low-level clients and higher-level resources. For Amazon EC2, the
higher-level resources are the most similar to Boto 2.x’s ec2 and vpc modules:
# Boto 2.x
import boto
ec2_connection = boto.connect_ec2()
vpc_connection = boto.connect_vpc()
# Boto 3
import boto3
ec2 = boto3.resource('ec2')
Launching New Instances Launching new instances requires an image ID and the number of instances to launch.
It can also take several optional parameters, such as the instance type and security group:
# Boto 2.x
ec2_connection.run_instances('<ami-image-id>')
# Boto 3
ec2.create_instances(ImageId='<ami-image-id>', MinCount=1, MaxCount=5)
Stopping & Terminating Instances Stopping and terminating multiple instances given a list of instance IDs uses
Boto 3 collection filtering:
ids = ['instance-id-1', 'instance-id-2', ...]
# Boto 2.x
ec2_connection.stop_instances(instance_ids=ids)
ec2_connection.terminate_instances(instance_ids=ids)
# Boto 3
ec2.instances.filter(InstanceIds=ids).stop()
ec2.instances.filter(InstanceIds=ids).terminate()
Checking What Instances Are Running Boto 3 collections come in handy when listing all your running instances
as well. Every collection exposes a filter method that allows you to pass additional parameters to the underlying
service API operation. The EC2 instances collection takes a parameter called Filters which is a list of names and
values, for example:
# Boto 2.x
reservations = ec2_connection.get_all_reservations(
filters={'instance-state-name': 'running'})
for reservation in reservations:
for instance in reservation.instances:
print(instance.instance_id, instance.instance_type)
# Boto 3
# Use the filter() method of the instances collection to retrieve
# all running EC2 instances.
instances = ec2.instances.filter(
Filters=[{'Name': 'instance-state-name', 'Values': ['running']}])
14 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
for instance in instances:
print(instance.id, instance.instance_type)
Checking Health Status Of Instances It is possible to get scheduled maintenance information for your running
instances. At the time of this writing Boto 3 does not have a status resource, so you must drop down to the low-level
client via ec2.meta.client:
# Boto 2.x
for status in ec2_connection.get_all_instance_statuses():
print(status)
# Boto 3
for status in ec2.meta.client.describe_instance_status()['InstanceStatuses']:
print(status)
Working with EBS Snapshots Snapshots provide a way to create a copy of an EBS volume, as well as make new
volumes from the snapshot which can be attached to an instance:
# Boto 2.x
snapshot = ec2_connection.create_snapshot('volume-id', 'Description')
volume = snapshot.create_volume('us-west-2')
ec2_connection.attach_volume(volume.id, 'instance-id', '/dev/sdy')
ec2_connection.delete_snapshot(snapshot.id)
# Boto 3
snapshot = ec2.create_snapshot(VolumeId='volume-id', Description='description')
volume = ec2.create_volume(SnapshotId=snapshot.id, AvailabilityZone='us-west-2a')
ec2.Instance('instance-id').attach_volume(VolumeId=volume.id, Device='/dev/sdy')
snapshot.delete()
Creating a VPC, Subnet, and Gateway Creating VPC resources in Boto 3 is very similar to Boto 2.x:
# Boto 2.x
vpc = vpc_connection.create_vpc('10.0.0.0/24')
subnet = vpc_connection.create_subnet(vpc.id, '10.0.0.0/25')
gateway = vpc_connection.create_internet_gateway()
# Boto 3
vpc = ec2.create_vpc(CidrBlock='10.0.0.0/24')
subnet = vpc.create_subnet(CidrBlock='10.0.0.0/25')
gateway = ec2.create_internet_gateway()
Attaching and Detaching an Elastic IP and Gateway Elastic IPs and gateways provide a way for instances inside
of a VPC to communicate with the outside world:
# Boto 2.x
ec2_connection.attach_internet_gateway(gateway.id, vpc.id)
ec2_connection.detach_internet_gateway(gateway.id, vpc.id)
from boto.ec2.address import Address
address = Address()
address.allocation_id = 'eipalloc-35cf685d'
address.associate('i-71b2f60b')
address.disassociate()
2.1. User Guides 15
Boto3 Documentation, Release 1.1.4
# Boto 3
gateway.attach_to_vpc(VpcId=vpc.id)
gateway.detach_from_vpc(VpcId=vpc.id)
address = ec2.VpcAddress('eipalloc-35cf685d')
address.associate('i-71b2f60b')
address.association.delete()
2.1.2 General Feature Guides
Resources
Overview
Resources represent an object-oriented interface to Amazon Web Services (AWS). They provide a higher-level abstrac-
tion than the raw, low-level calls made by service clients. To use resources, you invoke the resource() method of
a Session and pass in a service name:
# Get resources from the default session
sqs = boto3.resource('sqs')
s3 = boto3.resource('s3')
Every resource instance has a number of attributes and methods. These can conceptually be split up into identifiers,
attributes, actions, references, sub-resources, and collections. Each of these is described in further detail below and in
the following section.
Resources themselves can also be conceptually split into service resources (like sqs, s3, ec2, etc) and individual
resources (like sqs.Queue or s3.Bucket). Service resources do not have identifiers or attributes. The two share
the same components otherwise.
Identifiers & Attributes
An identifier is a unique value that is used to call actions on the resource. Resources must have at least one identifier,
except for the top-level service resources (e.g. sqs or s3). An identifier is set at instance creation-time, and failing to
provide all necessary identifiers during instantiation will result in an exception. Examples of identifiers:
# SQS Queue (url is an identifier)
queue = sqs.Queue(url='http://...')
print(queue.url)
# S3 Object (bucket_name and key are identifiers)
obj = s3.Object(bucket_name='boto3', key='test.py')
print(obj.bucket_name)
print(obj.key)
# Raises exception, missing identifier: key!
obj = s3.Object(bucket_name='boto3')
Identifiers may also be passed as positional arguments:
# SQS Queue
queue = sqs.Queue('http://...')
# S3 Object
16 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
obj = s3.Object('boto3', 'test.py')
# Raises exception, missing key!
obj = s3.Object('boto3')
Identifiers also play a role in resource instance equality. For two instances of a resource to be considered equal, their
identifiers must be equal:
>>> bucket1 = s3.Bucket('boto3')
>>> bucket2 = s3.Bucket('boto3')
>>> bucket3 = s3.Bucket('some-other-bucket')
>>> bucket1 == bucket2
True
>>> bucket1 == bucket3
False
Note: Only identifiers are taken into account for instance equality. Region, account ID and other data members are
not considered. When using temporary credentials or multiple regions in your code please keep this in mind.
Resources may also have attributes, which are lazy-loaded properties on the instance. They may be set at creation
time from the response of an action on another resource, or they may be set when accessed or via an explicit call to
the load or reload action. Examples of attributes:
# SQS Message
message.body
# S3 Object
obj.last_modified
obj.md5
Warning: Attributes may incur a load action when first accessed. If latency is a concern, then manually calling
load will allow you to control exactly when the load action (and thus latency) is invoked. The documentation for
each resource explicitly lists its attributes.
Additionally, attributes may be reloaded after an action has been performed on the resource. For example, if the
last_modified attribute of an S3 object is loaded and then a put action is called, then the next time you access
last_modified it will reload the object’s metadata.
Actions
An action is a method which makes a call to the service. Actions may return a low-level response, a new resource
instance or a list of new resource instances. Actions automatically set the resource identifiers as parameters, but allow
you to pass additional parameters via keyword arguments. Examples of actions:
# SQS Queue
messages = queue.receive_messages()
# SQS Message
for message in messages:
message.delete()
# S3 Object
obj = s3.Object(bucket_name='boto3', key='test.py')
response = obj.get()
data = response['Body'].read()
2.1. User Guides 17
Boto3 Documentation, Release 1.1.4
Examples of sending additional parameters:
# SQS Service
queue = sqs.get_queue_by_name(QueueName='test')
# SQS Queue
queue.send_message(MessageBody='hello')
Note: Parameters must be passed as keyword arguments. They will not work as positional arguments.
References
A reference is an attribute which may be None or a related resource instance. The resource instance does not share
identifiers with its reference resource, that is, it is not a strict parent to child relationship. In relational terms, these can
be considered many-to-one or one-to-one. Examples of references:
# EC2 Instance
instance.subnet
instance.vpc
In the above example, an EC2 instance may have exactly one associated subnet, and may have exactly one associated
VPC. The subnet does not require the instance ID to exist, hence it is not a parent to child relationship.
Sub-resources
A sub-resource is similar to a reference, but is a related class rather than an instance. Sub-resources, when instantiated,
share identifiers with their parent. It is a strict parent-child relationship. In relational terms, these can be considered
one-to-many. Examples of sub-resources:
# SQS
queue = sqs.Queue(url='...')
message = queue.Message(receipt_handle='...')
print(queue.url == message.queue_url)
print(message.receipt_handle)
# S3
obj = bucket.Object(key='new_file.txt')
print(obj.bucket_name)
print(obj.key)
Because an SQS message cannot exist without a queue, and an S3 object cannot exist without a bucket, these are parent
to child relationships.
Waiters
A waiter is similiar to an action. A waiter will poll the status of a resource and suspend execution until the resource
reaches the state that is being polling for or a failure occurs while polling. Waiters automatically set the resource
identifiers as parameters, but allow you to pass additional parameters via keyword arguments. Examples of waiters
include:
# S3: Wait for a bucket to exist.
bucket.wait_until_exists()
18 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
# EC2: Wait for an instance to reach the running state.
instance.wait_until_running()
Multithreading
It is recommended to create a resource instance for each thread in a multithreaded application rather than sharing a
single instance among the threads. For example:
import boto3
import boto3.session
import threading
class MyTask(threading.Thread):
def run(self):
session = boto3.session.Session()
s3 = session.resource('s3')
# ... do some work with S3 ...
In the example above, each thread would have its own Boto 3 session and its own instance of the S3 resource. This is
a good idea because resources contain shared data when loaded and calling actions, accessing properties, or manually
loading or reloading the resource can modify this data.
Collections
Overview
A collection provides an iterable interface to a group of resources. Collections behave similarly to Django QuerySets
and expose a similar API. A collection seamlessly handles pagination for you, making it possible to easily iterate over
all items from all pages of data. Example of a collection:
# SQS list all queues
sqs = boto3.resource('sqs')
for queue in sqs.queues.all():
print(queue.url)
When Collections Make Requests Collections can be created and manipulated without any request being made to
the underlying service. A collection makes a remote service request under the following conditions:
• Iteration:
for bucket in s3.buckets.all():
print(bucket.name)
• Conversion to list():
buckets = list(s3.buckets.all())
• Batch actions (see below):
s3.Bucket('my-bucket').objects.delete()
2.1. User Guides 19
Boto3 Documentation, Release 1.1.4
Filtering
Some collections support extra arguments to filter the returned data set, which are passed into the underlying service
operation. Use the filter() method to filter the results:
# S3 list all keys with the prefix '/photos'
s3 = boto3.resource('s3')
for bucket in s3.buckets.all():
for obj in bucket.objects.filter(Prefix='/photos'):
print('{0}:{1}'.format(bucket.name, obj.key))
Warning: Behind the scenes, the above example will call ListBuckets, ListObjects, and HeadObject
many times. If you have a large number of S3 objects then this could incur a significant cost.
Chainability
Collection methods are chainable. They return copies of the collection rather than modifying the collection, including
a deep copy of any associated operation parameters. For example, this allows you to build up multiple collections
from a base which they all have in common:
# EC2 find instances
ec2 = boto3.resource('ec2')
base = ec2.instances.filter(InstanceIds=['id1', 'id2', 'id3'])
filters = [{
'name': 'tenancy',
'value': 'dedicated'
}]
filtered1 = base.filter(Filters=filters)
# Note, this does NOT modify the filters in ``filtered1``!
filters.append({'name': 'instance-type', 'value': 't1.micro'})
filtered2 = base.filter(Filters=filters)
print('All instances:')
for instance in base:
print(instance.id)
print('Dedicated instances:')
for instance in filtered1:
print(instance.id)
print('Dedicated micro instances:')
for instance in filtered2:
print(instance.id)
Limiting Results
It is possible to limit the number of items returned from a collection by using either the limit() method:
# S3 iterate over first ten buckets
for bucket in s3.buckets.limit(10):
print(bucket.name)
20 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
In both cases, up to 10 items total will be returned. If you do not have 10 buckets, then all of your buckets will be
returned.
Controlling Page Size
Collections automatically handle paging through results, but you may want to control the number of items returned
from a single service operation call. You can do so using the page_size() method:
# S3 iterate over all objects 100 at a time
for obj in bucket.objects.page_size(100):
print(obj.key)
By default, S3 will return 1000 objects at a time, so the above code would let you process the items in smaller batches,
which could be beneficial for slow or unreliable internet connections.
Batch Actions
Some collections support batch actions, which are actions that operate on an entire page of results at a time. They will
automatically handle pagination:
# S3 delete everything in `my-bucket`
s3 = boto3.resource('s3')
s3.buckets('my-bucket').objects.delete()
Danger: The above example will completely erase all data in the my-bucket bucket! Please be careful with
batch actions.
Low-level Clients
Clients provide a low-level interface to AWS whose methods map close to 1:1 with service APIs. All service operations
are supported by clients. Clients are generated from a JSON service definition file.
Creating Clients
Clients are created in a similar fashion to resources:
import boto3
# Create a low-level client with the service name
sqs = boto3.client('sqs')
It is also possible to access the low-level client from an existing resource:
# Create the resource
sqs_resource = boto3.resource('sqs')
# Get the client from the resource
sqs = sqs_resource.meta.client
2.1. User Guides 21
Boto3 Documentation, Release 1.1.4
Service Operations
Service operations map to client methods of the same name and provide access to the same operation parameters via
keyword arguments:
# Make a call using the low-level client
response = sqs.send_message(QueueUrl='...', MessageBody='...')
As can be seen above, the method arguments map directly to the associated SQS API.
Note: The method names have been snake-cased for better looking Python code.
Parameters must be sent as keyword arguments. They will not work as positional arguments.
Handling Responses
Responses are returned as python dictionaries. It is up to you to traverse or otherwise process the response for the
data you need, keeping in mind that responses may not always include all of the expected data. In the example below,
response.get(’QueueUrls’, []) is used to ensure that a list is always returned, even when the response has
no key ’QueueUrls’:
# List all your queues
response = sqs.list_queues()
for url in response.get('QueueUrls', []):
print(url)
The response in the example above looks something like this:
{
"QueueUrls": [
"http://url1",
"http://url2",
"http://url3"
]
}
Waiters
Waiters use a client’s service operations to poll the status of an AWS resource and suspend execution until the AWS
resource reaches the state that the waiter is polling for or a failure occurs while polling. Using clients, you can learn
the name of each waiter that a client has access to:
import boto3
s3 = boto3.client('s3')
sqs = boto3.client('sqs')
# List all of the possible waiters for both clients
print("s3 waiters:")
s3.waiter_names
print("sqs waiters:")
sqs.waiter_names
Note if a client does not have any waiters, it will return an empty list when accessing its waiter_names attribute:
22 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
s3 waiters:
[u'bucket_exists', u'bucket_not_exists', u'object_exists', u'object_not_exists']
sqs waiters:
[]
Using a client’s get_waiter() method, you can obtain a specific waiter from its list of possible waiters:
# Retrieve waiter instance that will wait till a specified
# S3 bucket exists
s3_bucket_exists_waiter = s3.get_waiter('bucket_exists')
Then to actually start waiting, you must call the waiter’s wait() method with the method’s appropriate parameters
passed in:
# Begin waiting for the S3 bucket, mybucket, to exist
s3_bucket_exists_waiter.wait(Bucket='mybucket')
Session
A session manages state about a particular configuration. By default a session is created for you when needed. How-
ever it is possible and recommended to maintain your own session(s) in some scenarios. Sessions typically store:
• Credentials
• Region
• Other configurations
Default Session
The boto3 module acts as a proxy to the default session, which is created automatically when needed. Example
default session use:
# Using the default session
sqs = boto3.client('sqs')
s3 = boto3.resource('s3')
Custom Session
It is also possible to manage your own session and create clients or resources from it:
# Creating your own session
session = boto3.session.Session()
sqs = session.client('sqs')
s3 = session.resource('s3')
Configuration
Boto can be configured in multiple ways. Regardless of the source or sources that you choose, you must have AWS
credentials and a region set in order to make requests.
2.1. User Guides 23
Boto3 Documentation, Release 1.1.4
Interactive Configuration
If you have the AWS CLI, then you can use its interactive configure command to set up your credentials and
default region:
aws configure
Follow the prompts and it will generate configuration files in the correct locations for you.
Configuration Sources
There are multiple sources from which configuration data can be loaded. The general order in which they are checked
is as follows:
1. Method parameters
2. Environment variables
3. Configuration files
4. EC2 Instance metadata
If a configuration value is set in multiple places, then the first will be used according the the order above. For example,
if I have set a default region in both my environment variables and configuration file, then the environment variable is
used.
Available Options
The available options for various configuration sources are listed below.
Method Parameters When creating a session, client, or resource you can pass in credential and configuration op-
tions:
from boto3.session import Session
session = Session(aws_access_key_id='<YOUR ACCESS KEY ID>',
aws_secret_access_key='<YOUR SECRET KEY>',
region_name='<REGION NAME>')
ec2 = session.resource('ec2')
ec2_us_west_2 = session.resource('ec2', region_name='us-west-2')
# List all of my EC2 instances in my default region.
print('Default region:')
for instance in ec2.instances.all():
print(instance.id)
# List all of my EC2 instances in us-west-2.
print('US West 2 region:')
for instance in ec2_us_west_2.instances.all():
print(instance.id)
For a list of all options, look at the Session documentation.
24 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
Environment Variables
AWS_ACCESS_KEY_ID The access key for your AWS account.
AWS_SECRET_ACCESS_KEY The secret key for your AWS account.
AWS_DEFAULT_REGION The default region to use, e.g. us-east-1.
AWS_PROFILE The default credential and configuration profile to use, if any.
Configuration Files There are two configuration files that Boto checks. The first is the shared credential file, which
holds only credentials and is shared between various SDKs and tools like Boto and the AWS CLI. By default, this file
is located at ~/.aws/credentials:
[default]
# The access key for your AWS account
aws_access_key_id=<YOUR ACCESS KEY ID>
# The secret key for your AWS account
aws_secret_access_key=<YOUR SECRET KEY>
Credentials can also be set for individual profiles:
[dev-profile]
# The access key for your dev-profile account
aws_access_key_id=<YOUR ACCESS KEY ID>
# The secret key for your dev-profile account
aws_secret_access_key=<YOUR SECRET KEY>
The second configuration file stores all settings which are not credentials. Its default location is ~/.aws/config:
[default]
# The default region when making requests
region=<REGION NAME>
It also supports profiles, but these are prefixed with the word profile because this file supports sections other than
profiles:
[profile dev-profile]
# The default region when using the dev-profile account
region=<REGION NAME>
Extensibility Guide
All of Boto3’s resource and client classes are generated at runtime. This means that you cannot directly inherit and
then extend the functionality of these classes because they do not exist until the program actually starts running.
However it is still possible to extend the functionality of classes through Boto3’s event system.
An Introduction to the Event System
Boto3’s event system allows users to register a function to a specific event. Then once the running program reaches a
line that emits that specific event, Boto3 will call every function registered to the event in the order in which they were
registered. When Boto3 calls each of these registered functions, it will call each of them with a specific set of keyword
arguments that are associated with that event. Then once the registered function is called, the function may modify the
keyword arguments passed to that function or return a value. Here is an example of how the event system works:
2.1. User Guides 25
Boto3 Documentation, Release 1.1.4
import boto3
s3 = boto3.client('s3')
# Access the event system on the S3 client
event_system = s3.meta.events
# Create a function
def add_my_bucket(params, **kwargs):
# Add the name of the bucket you want to default to.
if 'Bucket' not in params:
params['Bucket'] = 'mybucket'
# Register the function to an event
event_system.register('provide-client-params.s3.ListObjects', add_my_bucket)
response = s3.list_objects()
In this example, the handler add_my_bucket is registered such that the handler will inject the value ’mybucket
for the Bucket parameter whenever the the list_objects client call is made without the Bucket parameter.
Note that if the same list_objects call is made without the Bucket parameter and the registered handler, it will
result in a validation error.
Here are the takeaways from this example:
• All clients have their own event system that you can use to fire events and register functions. You can access the
event system through the meta.events attribute on the client.
• All functions registered to the event system must have **kwargs in the function signature. This is because
emitting an event can have any number of keyword arguments emitted along side it, and so if your function is
called without **kwargs, its signature will have to match every keyword argument emitted by the event. This
also allows for more keyword arguments to be added to the emitted event in the future without breaking existing
handlers.
• To register a function to an event, call the register method on the event system with the name of the event
you want to register the function to and the function handle. Note that if you register the event after the event is
emitted, the function will not be called unless the event is emitted again. In the example, the add_my_bucket
handler was registered to the ’provide-client-params.s3.ListObjects’ event, which is an event
that can be used to inject and modify parameters passed in by the client method. To read more about the event
refer to provide-client-params
A Hierarchical Structure
The event system also provides a hierarchy for registering events such that you can register a function to a set of events
depending on the event name heirarchy.
An event name can have its own heirachy by specifying . in its name. For example, take the event name
’general.specific.more_specific’. When this event is emitted, the registered functions will be called
in the order from most specific to least specific registration. So in this example, the functions will be called in the
following order:
1. Functions registered to ’general.specific.more_specific’
2. Functions registered to ’general.specific’
3. Functions registered to ’general’
Here is a deeper example of how the event system works with respect to its hierarchial structure:
26 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
import boto3
s3 = boto3.client('s3')
# Access the event system on the S3 client
event_system = s3.meta.events
def add_my_general_bucket(params, **kwargs):
if 'Bucket' not in params:
params['Bucket'] = 'mybucket'
def add_my_specific_bucket(params, **kwargs):
if 'Bucket' not in params:
params['Bucket'] = 'myspecificbucket'
event_system.register('provide-client-params.s3', add_my_general_bucket)
event_system.register('provide-client-params.s3.ListObjects', add_my_specific_bucket)
list_obj_response = s3.list_objects()
put_obj_response = s3.put_object(Key='mykey', Body=b'my body')
In this example, the list_objects method call will use the ’myspecificbucket’ for the
bucket instead of ’mybucket’ because the add_my_specific_bucket method was registered
to the ’provide-client-params.s3.ListObjects’ event which is more specific than the
’provide-client-params.s3’ event. Thus, the add_my_specific_bucket function is called be-
fore the add_my_general_bucket function is called when the event is emitted.
However for the put_object call, the bucket used is ’mybucket’. This is because the event emit-
ted for the put_object client call is ’provide-client-params.s3.PutObject’ and the
add_my_general_bucket method is called via its registration to ’provide-client-params.s3’.
The ’provide-client-params.s3.ListObjects’ event is never emitted so the registered
add_my_specific_bucket function is never called.
Wildcard Matching
Another aspect of Boto3’s event system is that it has the capability to do wildcard matching using the ’*’ notation.
Here is an example of using wildcards in the event system:
import boto3
s3 = boto3.client('s3')
# Access the event system on the S3 client
event_system = s3.meta.events
def add_my_wildcard_bucket(params, **kwargs):
if 'Bucket' not in params:
params['Bucket'] = 'mybucket'
event_system.register('provide-client-params.s3.*', add_my_wildcard_bucket)
response = s3.list_objects()
The ’*’ allows you to register to a group of events without having to know the actual name of the event. This is useful
when you have to apply the same handler in multiple places. Also note that if the wildcard is used, it must be isolated. It
does not handle globbing with additional characters. So in the previous example, if the my_wildcard_function
was registered to ’provide-client-params.s3.*objects’, the handler would not be called because it will
consider ’provide-client-params.s3.*objects’ to be a specific event.
2.1. User Guides 27
Boto3 Documentation, Release 1.1.4
The wildcard also respects the hierarchical structure of the event system. If another handler was regis-
tered to the ’provide-client-params.s3’ event, the add_my_wildcard_bucket would be called
first because it is registered to ’provide-client-params.s3.*’ which is more specific than the event
’provide-client.s3’.
Isolation of Event Systems
The event system in Boto3 has the notion of isolation: all clients maintain their own set of registered handlers. For
example if a handler is registered to one client’s event system, it will not be registered to another client’s event system:
import boto3
client1 = boto3.client('s3')
client2 = boto3.client('s3')
def add_my_bucket(params, **kwargs):
if 'Bucket' not in params:
params['Bucket'] = 'mybucket'
def add_my_other_bucket(params, **kwargs):
if 'Bucket' not in params:
params['Bucket'] = 'myotherbucket'
client1.meta.events.register(
'provide-client-params.s3.ListObjects', add_my_bucket)
client2.meta.events.register(
'provide-client-params.s3.ListObjects', add_my_other_bucket)
client1_response = client1.list_objects()
client2_response = client2.list_objects()
Thanks to the isolation of clients’ event systems, client1 will inject ’mybucket’ for its list_objects
method call while client2 will inject ’myotherbucket’ for its list_objects method call because
add_my_bucket was registered to client1 while add_my_other_bucket was registered to client2.
Boto3 Specific Events
Boto3 emits a set of events that users can register to customize clients or resources and modify the behavior of method
calls.
Here is the list of events that users of boto3 can register handlers to:
• ’creating-client-class
• ’creating-resource-class
• ’provide-client-params’
creating-client-class
Full Event Name ’creating-client-class.service-name’
Note: service-name refers to the value used to instantiate a client i.e.
boto3.client(’service-name’)
28 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
Description This event is emitted upon creation of the client class for a service. The client class for a
service is not created until the first instantiation of the client class. Use this event for adding methods
to the client class or adding classes for the client class to inherit from.
Keyword Arguments Emitted
type class_attributes dict
param class_attributes A dictionary where the keys are the names of the attributes of the
class and the values are the actual attributes of the class.
type base_classes list
param base_classes A list of classes that the client class will inherit from where the order
of inheritance is the same as the order of the list.
Expected Return Value Do not return anything.
Example Here is an example of how to add a method to the client class:
from boto3.session import Session
def custom_method(self):
print('This is my custom method')
def add_custom_method(class_attributes, **kwargs):
class_attributes['my_method'] = custom_method
session = Session()
session.events.register('creating-client-class.s3', add_custom_method)
client = session.client('s3')
client.my_method()
This should output:
This is my custom method
Here is an example of how to add a new class for the client class to inherit from:
from boto3.session import Session
class MyClass(object):
def __init__(self, *args, **kwargs):
super(MyClass, self).__init__(*args, **kwargs)
print('Client instantiated!')
def add_custom_class(base_classes, **kwargs):
base_classes.insert(0, MyClass)
session = Session()
session.events.register('creating-client-class.s3', add_custom_class)
client = session.client('s3')
This should output:
Client instantiated!
creating-resource-class
2.1. User Guides 29
Boto3 Documentation, Release 1.1.4
Full Event Name ’creating-resource-class.service-name.resource-name’
Note: service-name refers to the value used to instantiate a service resource i.e.
boto3.resource(’service-name’) and resource-name refers to the name of the re-
source class.
Description This event is emitted upon creation of the resource class. The resource class is not created
until the first instantiation of the resource class. Use this event for adding methods to the resource
class or adding classes for the resource class to inherit from.
Keyword Arguments Emitted
type class_attributes dict
param class_attributes A dictionary where the keys are the names of the attributes of the
class and the values are the actual attributes of the class.
type base_classes list
param base_classes A list of classes that the resource class will inherit from where the
order of inheritance is the same as the order of the list.
Expected Return Value Do not return anything.
Example Here is an example of how to add a method to a resource class:
from boto3.session import Session
def custom_method(self):
print('This is my custom method')
def add_custom_method(class_attributes, **kwargs):
class_attributes['my_method'] = custom_method
session = Session()
session.events.register('creating-resource-class.s3.ServiceResource',
add_custom_method)
resource = session.resource('s3')
resource.my_method()
This should output:
This is my custom method
Here is an example of how to add a new class for a resource class to inherit from:
from boto3.session import Session
class MyClass(object):
def __init__(self, *args, **kwargs):
super(MyClass, self).__init__(*args, **kwargs)
print('Resource instantiated!')
def add_custom_class(base_classes, **kwargs):
base_classes.insert(0, MyClass)
session = Session()
session.events.register('creating-resource-class.s3.ServiceResource',
add_custom_class)
resource = session.resource('s3')
30 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
This should output:
Resource instantiated!
provide-client-params
Full Event Name ’provide-client.service-name.operation-name’
Note: service-name refers to the value used to instantiate a client i.e.
boto3.client(’service-name’). operation-name refers to the underlying API
operation of the corresponding client method. To access the operation API name, retrieve the value
from the client.meta.method_to_api_mapping dictionary using the name of the desired
client method as the key.
Description This event is emitted before validation of the parameters passed to client method. Use this
event to inject or modify parameters prior to the parameters being validated and built into a request
that is sent over the wire.
Keyword Arguments Emitted
type params dict
param params A dictionary where the keys are the names of the parameters passed
through the client method and the values are the values of those parameters.
type model botocore.model.OperationModel
param model A model representing the underlying API operation of the client method.
Expected Return Value Do not return anything or return a new dictionary of parameters to use when
making the request.
Example Here is an example of how to inject a parameter using the event:
import boto3
s3 = boto3.client('s3')
# Access the event system on the S3 client
event_system = s3.meta.events
# Create a function
def add_my_bucket(params, **kwargs):
# Add the name of the bucket you want to default to.
if 'Bucket' not in params:
params['Bucket'] = 'mybucket'
# Register the function to an event
event_system.register('provide-client-params.s3.ListObjects', add_my_bucket)
response = s3.list_objects()
2.1.3 Service Feature Guides
DynamoDB
By following this guide, you will learn how to use the DynamoDB.ServiceResource and DynamoDB.Table
resources in order to create tables, write items to tables, modify existing items, retrieve items, and query/filter the
items in the table.
2.1. User Guides 31
Boto3 Documentation, Release 1.1.4
Creating a New Table
In order to create a new table, use the DynamoDB.ServiceResource.create_table() method:
import boto3
# Get the service resource.
dynamodb = boto3.resource('dynamodb')
# Create the DynamoDB table.
table = dynamodb.create_table(
TableName='users',
KeySchema=[
{
'AttributeName': 'username',
'KeyType': 'HASH'
},
{
'AttributeName': 'last_name',
'KeyType': 'RANGE'
}
],
AttributeDefinitions=[
{
'AttributeName': 'username',
'AttributeType': 'S'
},
{
'AttributeName': 'last_name',
'AttributeType': 'S'
},
],
ProvisionedThroughput={
'ReadCapacityUnits': 5,
'WriteCapacityUnits': 5
}
)
# Wait until the table exists.
table.meta.client.get_waiter('table_exists').wait(TableName='users')
# Print out some data about the table.
print(table.item_count)
Expected Output:
0
This creates a table named users that respectively has the hash and range primary keys username and
last_name. This method will return a DynamoDB.Table resource to call additional methods on the created
table.
Using an Existing Table
It is also possible to create a DynamoDB.Table resource from an existing table:
32 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
import boto3
# Get the service resource.
dynamodb = boto3.resource('dynamodb')
# Instantiate a table resource object without actually
# creating a DynamoDB table. Note that the attributes of this table
# are lazy-loaded: a request is not made nor are the attribute
# values populated until the attributes
# on the table resource are accessed or its load() method is called.
table = dynamodb.Table('users')
# Print out some data about the table.
# This will cause a request to be made to DynamoDB and its attribute
# values will be set based on the response.
print(table.creation_date_time)
Expected Output (Pleas note that probably the actual times will not match up):
2015-06-26 12:42:45.149000-07:00
Creating a New Item
Once you have a DynamoDB.Table resource you can add new items to the table using
DynamoDB.Table.put_item():
table.put_item(
Item={
'username': 'janedoe',
'first_name': 'Jane',
'last_name': 'Doe',
'age': 25,
'account_type': 'standard_user',
}
)
For all of the valid types that can be used for an item, refer to Valid DynamoDB Types.
Getting an Item
You can then retrieve the object using DynamoDB.Table.get_item():
response = table.get_item(
Key={
'username': 'janedoe',
'last_name': 'Doe'
}
)
item = response['Item']
print(item)
Expected Output:
{u'username': u'janedoe',
u'first_name': u'Jane',
u'last_name': u'Doe',
2.1. User Guides 33
Boto3 Documentation, Release 1.1.4
u'account_type': u'standard_user',
u'age': Decimal('25')}
Updating Item
Using the retrieved item, you can update attributes of the item in the table:
item['age'] = 26
table.put_item(Item=item)
Then if you retrieve the item again, it will be updated appropriately:
response = table.get_item(
Key={
'username': 'janedoe',
'last_name': 'Doe'
}
)
item = response['Item']
print(item)
Expected Output:
{u'username': u'janedoe',
u'first_name': u'Jane',
u'last_name': u'Doe',
u'account_type': u'standard_user',
u'age': Decimal('26')}
Deleting Item
You can also delete the item using DynamoDB.Table.delete_item():
table.delete_item(
Key={
'username': 'janedoe',
'last_name': 'Doe'
}
)
Batch Writing
If you are loading a lot of data at a time, you can make use of DyanmoDB.Table.batch_writer() so you can
both speed up the process and reduce the number of write requests made to the service.
This method returns a handle to a batch writer object that will automatically handle buffering and sending items in
batches. In addition, the batch writer will also automatically handle any unprocessed items and resend them as needed.
All you need to do is call put_item for any items you want to add, and delete_item for any items you want to
delete:
with table.batch_writer() as batch:
batch.put_item(
Item={
'account_type': 'standard_user',
'username': 'johndoe',
34 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
'first_name': 'John',
'last_name': 'Doe',
'age': 25,
'address': {
'road': '1 Jefferson Street',
'city': 'Los Angeles',
'state': 'CA',
'zipcode': 90001
}
}
)
batch.put_item(
Item={
'account_type': 'super_user',
'username': 'janedoering',
'first_name': 'Jane',
'last_name': 'Doering',
'age': 40,
'address': {
'road': '2 Washington Avenue',
'city': 'Seattle',
'state': 'WA',
'zipcode': 98109
}
}
)
batch.put_item(
Item={
'account_type': 'standard_user',
'username': 'bobsmith',
'first_name': 'Bob',
'last_name': 'Smith',
'age': 18,
'address': {
'road': '3 Madison Lane',
'city': 'Louisville',
'state': 'KY',
'zipcode': 40213
}
}
)
batch.put_item(
Item={
'account_type': 'super_user',
'username': 'alicedoe',
'first_name': 'Alice',
'last_name': 'Doe',
'age': 27,
'address': {
'road': '1 Jefferson Street',
'city': 'Los Angeles',
'state': 'CA',
'zipcode': 90001
}
}
)
The batch writer is even able to handle a very large amount of writes to the table.
2.1. User Guides 35
Boto3 Documentation, Release 1.1.4
with table.batch_writer() as batch:
for i in range(50):
batch.put_item(
Item={
'account_type': 'anonymous',
'username': 'user' + str(i),
'first_name': 'unknown',
'last_name': 'unknown'
}
)
Querying and Scanning
With the table full of items, you can then query or scan the items in the table using the DynamoDB.Table.query()
or DynamoDB.Table.scan() methods respectively. To add conditions to scanning and querying the table, you
will need to import the boto3.dynamodb.conditions.Key and boto3.dynamodb.conditions.Attr
classes. The boto3.dynamodb.conditions.Key should be used when the condition is related to the key of the
item. The boto3.dynamodb.conditions.Attr should be used when the condition is related to an attribute of
the item:
from boto3.dynamodb.conditions import Key, Attr
This queries for all of the users whose username key equals johndoe:
response = table.query(
KeyConditionExpression=Key('username').eq('johndoe')
)
items = response['Items']
print(items)
Expected Output:
[{u'username': u'johndoe',
u'first_name': u'John',
u'last_name': u'Doe',
u'account_type': u'standard_user',
u'age': Decimal('25'),
u'address': {u'city': u'Los Angeles',
u'state': u'CA',
u'zipcode': Decimal('90001'),
u'road': u'1 Jefferson Street'}}]
Similiarly you can scan the table based on attributes of the items. For example, this scans for all the users whose age
is less than 27:
response = table.scan(
FilterExpression=Attr('age').lt(27)
)
items = response['Items']
print(items)
Expected Output:
[{u'username': u'johndoe',
u'first_name': u'John',
u'last_name': u'Doe',
u'account_type': u'standard_user',
36 Chapter 2. User Guide
Boto3 Documentation, Release 1.1.4
u'age': Decimal('25'),
u'address': {u'city': u'Los Angeles',
u'state': u'CA',
u'zipcode': Decimal('90001'),
u'road': u'1 Jefferson Street'}},
{u'username': u'bobsmith',
u'first_name': u'Bob',
u'last_name': u'Smith',
u'account_type': u'standard_user',
u'age': Decimal('18'),
u'address': {u'city': u'Louisville',
u'state': u'KY',
u'zipcode': Decimal('40213'),
u'road': u'3 Madison Lane'}}]
You are also able to chain conditions together using the logical operators: & (and), | (or), and ~ (not). For example,
this scans for all users whose first_name starts with J and whose account_type is super_user:
response = table.scan(
FilterExpression=Attr('first_name').begins_with('J') & Attr('account_type').eq('super_user')
)
items = response['Items']
print(items)
Expected Output:
[{u'username': u'janedoering',
u'first_name': u'Jane',
u'last_name': u'Doering',
u'account_type': u'super_user',
u'age': Decimal('40'),
u'address': {u'city': u'Seattle',
u'state': u'WA',
u'zipcode': Decimal('98109'),
u'road': u'2 Washington Avenue'}}]
You can even scan based on conditions of a nested attribute. For example this scans for all users whose state in their
address is CA:
response = table.scan(
FilterExpression=Attr('address.state').eq('CA')
)
items = response['Items']
print(items)
Expected Output:
[{u'username': u'johndoe',
u'first_name': u'John',
u'last_name': u'Doe',
u'account_type': u'standard_user',
u'age': Decimal('25'),
u'address': {u'city': u'Los Angeles',
u'state': u'CA',
u'zipcode': Decimal('90001'),
u'road': u'1 Jefferson Street'}},
{u'username': u'alicedoe',
u'first_name': u'Alice',
u'last_name': u'Doe',
2.1. User Guides 37
Boto3 Documentation, Release 1.1.4
u'account_type': u'super_user',
u'age': Decimal('27'),
u'address': {u'city': u'Los Angeles',
u'state': u'CA',
u'zipcode': Decimal('90001'),
u'road': u'1 Jefferson Street'}}]
For more information on the various conditions you can use for queries and scans, refer to DynamoDB Conditions.
Deleting a Table
Finally, if you want to delete your table call DynamoDB.Table.delete():
table.delete()
38 Chapter 2. User Guide
CHAPTER 3
API Reference
3.1 Services
3.1.1 Available Services
AutoScaling
Table of Contents
• AutoScaling
– Client
– Paginators
Client
class AutoScaling.Client
A low-level client representing Auto Scaling:
import boto3
client = boto3.client('autoscaling')
These are the available methods:
•attach_instances()
•attach_load_balancers()
•can_paginate()
•complete_lifecycle_action()
•create_auto_scaling_group()
•create_launch_configuration()
•create_or_update_tags()
•delete_auto_scaling_group()
•delete_launch_configuration()
39
Boto3 Documentation, Release 1.1.4
•delete_lifecycle_hook()
•delete_notification_configuration()
•delete_policy()
•delete_scheduled_action()
•delete_tags()
•describe_account_limits()
•describe_adjustment_types()
•describe_auto_scaling_groups()
•describe_auto_scaling_instances()
•describe_auto_scaling_notification_types()
•describe_launch_configurations()
•describe_lifecycle_hook_types()
•describe_lifecycle_hooks()
•describe_load_balancers()
•describe_metric_collection_types()
•describe_notification_configurations()
•describe_policies()
•describe_scaling_activities()
•describe_scaling_process_types()
•describe_scheduled_actions()
•describe_tags()
•describe_termination_policy_types()
•detach_instances()
•detach_load_balancers()
•disable_metrics_collection()
•enable_metrics_collection()
•enter_standby()
•execute_policy()
•exit_standby()
•generate_presigned_url()
•get_paginator()
•get_waiter()
•put_lifecycle_hook()
•put_notification_configuration()
•put_scaling_policy()
•put_scheduled_update_group_action()
40 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
•record_lifecycle_action_heartbeat()
•resume_processes()
•set_desired_capacity()
•set_instance_health()
•suspend_processes()
•terminate_instance_in_auto_scaling_group()
•update_auto_scaling_group()
attach_instances(**kwargs)
Attaches one or more EC2 instances to the specified Auto Scaling group.
For more information, see Attach EC2 Instances to Your Auto Scaling Group in the Auto Scaling Developer
Guide .
Request Syntax
response = client.attach_instances(
InstanceIds=[
'string',
],
AutoScalingGroupName='string'
)
Parameters
• InstanceIds (list) – One or more EC2 instance IDs.
– (string) –
• AutoScalingGroupName (string) – [REQUIRED]
The name of the group.
Returns None
attach_load_balancers(**kwargs)
Attaches one or more load balancers to the specified Auto Scaling group.
To describe the load balancers for an Auto Scaling group, use DescribeLoadBalancers . To detach the load
balancer from the Auto Scaling group, use DetachLoadBalancers .
For more information, see Attach a Load Balancer to Your Auto Scaling Group in the Auto Scaling Devel-
oper Guide .
Request Syntax
response = client.attach_load_balancers(
AutoScalingGroupName='string',
LoadBalancerNames=[
'string',
]
)
Parameters
• AutoScalingGroupName (string) – The name of the group.
• LoadBalancerNames (list) – One or more load balancer names.
3.1. Services 41
Boto3 Documentation, Release 1.1.4
– (string) –
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
complete_lifecycle_action(**kwargs)
Completes the lifecycle action for the associated token initiated under the given lifecycle hook with the
specified result.
This operation is a part of the basic sequence for adding a lifecycle hook to an Auto Scaling group:
•Create a notification target. A target can be either an Amazon SQS queue or an Amazon SNS topic.
•Create an IAM role. This role allows Auto Scaling to publish lifecycle notifications to the designated
SQS queue or SNS topic.
•Create the lifecycle hook. You can create a hook that acts when instances launch or when instances
terminate.
•If necessary, record the lifecycle action heartbeat to keep the instance in a pending state.
•Complete the lifecycle action .
For more information, see Auto Scaling Pending State and Auto Scaling Terminating State in the Auto
Scaling Developer Guide .
Request Syntax
response = client.complete_lifecycle_action(
LifecycleHookName='string',
AutoScalingGroupName='string',
LifecycleActionToken='string',
LifecycleActionResult='string'
)
Parameters
• LifecycleHookName (string) – [REQUIRED]
The name of the lifecycle hook.
• AutoScalingGroupName (string) – [REQUIRED]
The name of the group for the lifecycle hook.
42 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• LifecycleActionToken (string) – [REQUIRED]
A universally unique identifier (UUID) that identifies a specific lifecycle action associated
with an instance. Auto Scaling sends this token to the notification target you specified
when you created the lifecycle hook.
• LifecycleActionResult (string) – [REQUIRED]
The action for the group to take. This parameter can be either CONTINUE or ABANDON .
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
create_auto_scaling_group(**kwargs)
Creates an Auto Scaling group with the specified name and attributes.
If you exceed your maximum limit of Auto Scaling groups, which by default is 20 per region, the call fails.
For information about viewing and updating this limit, see DescribeAccountLimits .
For more information, see Auto Scaling Groups in the Auto Scaling Developer Guide .
Request Syntax
response = client.create_auto_scaling_group(
AutoScalingGroupName='string',
LaunchConfigurationName='string',
InstanceId='string',
MinSize=123,
MaxSize=123,
DesiredCapacity=123,
DefaultCooldown=123,
AvailabilityZones=[
'string',
],
LoadBalancerNames=[
'string',
],
HealthCheckType='string',
HealthCheckGracePeriod=123,
PlacementGroup='string',
VPCZoneIdentifier='string',
TerminationPolicies=[
'string',
],
Tags=[
{
'ResourceId': 'string',
'ResourceType': 'string',
'Key': 'string',
'Value': 'string',
'PropagateAtLaunch': True|False
},
3.1. Services 43
Boto3 Documentation, Release 1.1.4
]
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name of the group. This name must be unique within the scope of your AWS account.
• LaunchConfigurationName (string) – The name of the launch configuration. Alterna-
tively, use the InstanceId parameter to specify an EC2 instance instead of a launch
configuration.
• InstanceId (string) – The ID of the EC2 instance used to create a launch configuration for
the group. Alternatively, use the LaunchConfigurationName parameter to specify a
launch configuration instead of an EC2 instance.
When you specify an ID of an instance, Auto Scaling creates a new launch configuration
and associates it with the group. This launch configuration derives its attributes from the
specified instance, with the exception of the block device mapping.
For more information, see Create an Auto Scaling Group from an EC2 Instance in the Auto
Scaling Developer Guide .
• MinSize (integer) – [REQUIRED]
The minimum size of the group.
• MaxSize (integer) – [REQUIRED]
The maximum size of the group.
• DesiredCapacity (integer) – The number of EC2 instances that should be running in the
group. This number must be greater than or equal to the minimum size of the group and
less than or equal to the maximum size of the group.
• DefaultCooldown (integer) – The amount of time, in seconds, after a scaling activity
completes before another scaling activity can start.
If this parameter is not specified, the default value is 300. For more information, see
Understanding Auto Scaling Cooldowns in the Auto Scaling Developer Guide .
• AvailabilityZones (list) – One or more Availability Zones for the group. This parameter
is optional if you specify subnets using the VPCZoneIdentifier parameter.
– (string) –
• LoadBalancerNames (list) – One or more load balancers.
For more information, see Load Balance Your Auto Scaling Group in the Auto Scaling
Developer Guide .
– (string) –
• HealthCheckType (string) – The service to use for the health checks. The valid values
are EC2 and ELB .
By default, health checks use Amazon EC2 instance status checks to determine the health
of an instance. For more information, see Health Checks .
• HealthCheckGracePeriod (integer) – The amount of time, in seconds, after an EC2 in-
stance comes into service that Auto Scaling starts checking its health. During this time,
any health check failures for the instance are ignored.
44 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
This parameter is required if you are adding an ELB health check. Frequently, new in-
stances need to warm up, briefly, before they can pass a health check. To provide ample
warm-up time, set the health check grace period of the group to match the expected startup
period of your application.
For more information, see Add an Elastic Load Balancing Health Check to Your Auto
Scaling Group in the Auto Scaling Developer Guide .
• PlacementGroup (string) – The name of the placement group into which you’ll launch
your instances, if any. For more information, see Placement Groups in the Amazon Elastic
Compute Cloud User Guide .
• VPCZoneIdentifier (string) – A comma-separated list of subnet identifiers for your vir-
tual private cloud (VPC).
If you specify subnets and Availability Zones with this call, ensure that the subnets’ Avail-
ability Zones match the Availability Zones specified.
For more information, see Auto Scaling and Amazon Virtual Private Cloud in the Auto
Scaling Developer Guide .
• TerminationPolicies (list) – One or more termination policies used to select the instance
to terminate. These policies are executed in the order that they are listed.
For more information, see Choosing a Termination Policy for Your Auto Scaling Group in
the Auto Scaling Developer Guide .
– (string) –
• Tags (list) – The tag to be created or updated. Each tag should be defined by its re-
source type, resource ID, key, value, and a propagate flag. Valid values: key=*value* ,
value=*value* , propagate=*true* or false . Value and propagate are optional parameters.
For more information, see Tagging Auto Scaling Groups and Instances in the Auto Scaling
Developer Guide .
– (dict) –
Describes a tag for an Auto Scaling group.
* ResourceId (string) –
The name of the group.
* ResourceType (string) –
The type of resource. The only supported value is auto-scaling-group .
* Key (string) – [REQUIRED]
The tag key.
* Value (string) –
The tag value.
* PropagateAtLaunch (boolean) –
Determines whether the tag is added to new instances as they are launched in the
group.
Returns None
create_launch_configuration(**kwargs)
Creates a launch configuration.
3.1. Services 45
Boto3 Documentation, Release 1.1.4
If you exceed your maximum limit of launch configurations, which by default is 100 per region, the call
fails. For information about viewing and updating this limit, see DescribeAccountLimits .
For more information, see Launch Configurations in the Auto Scaling Developer Guide .
Request Syntax
response = client.create_launch_configuration(
LaunchConfigurationName='string',
ImageId='string',
KeyName='string',
SecurityGroups=[
'string',
],
ClassicLinkVPCId='string',
ClassicLinkVPCSecurityGroups=[
'string',
],
UserData='string',
InstanceId='string',
InstanceType='string',
KernelId='string',
RamdiskId='string',
BlockDeviceMappings=[
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'VolumeType': 'string',
'DeleteOnTermination': True|False,
'Iops': 123
},
'NoDevice': True|False
},
],
InstanceMonitoring={
'Enabled': True|False
},
SpotPrice='string',
IamInstanceProfile='string',
EbsOptimized=True|False,
AssociatePublicIpAddress=True|False,
PlacementTenancy='string'
)
Parameters
• LaunchConfigurationName (string) – [REQUIRED]
The name of the launch configuration. This name must be unique within the scope of
your AWS account.
• ImageId (string) – The ID of the Amazon Machine Image (AMI) to use to launch
your EC2 instances. For more information, see Finding an AMI in the Amazon Elastic
Compute Cloud User Guide .
• KeyName (string) – The name of the key pair. For more information, see Amazon
EC2 Key Pairs in the Amazon Elastic Compute Cloud User Guide .
46 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• SecurityGroups (list) – One or more security groups with which to associate the
instances.
If your instances are launched in EC2-Classic, you can either specify security group
names or the security group IDs. For more information about security groups for EC2-
Classic, see Amazon EC2 Security Groups in the Amazon Elastic Compute Cloud
User Guide .
If your instances are launched into a VPC, specify security group IDs. For more
information, see Security Groups for Your VPC in the Amazon Virtual Private Cloud
User Guide .
– (string) –
• ClassicLinkVPCId (string) – The ID of a ClassicLink-enabled VPC to link your
EC2-Classic instances to. This parameter is supported only if you are launching EC2-
Classic instances. For more information, see ClassicLink in the Amazon Elastic Com-
pute Cloud User Guide .
• ClassicLinkVPCSecurityGroups (list) – The IDs of one or more security groups
for the VPC specified in ClassicLinkVPCId . This parameter is required if
ClassicLinkVPCId is specified, and is not supported otherwise. For more in-
formation, see ClassicLink in the Amazon Elastic Compute Cloud User Guide .
– (string) –
• UserData (string) – The user data to make available to the launched EC2 instances.
For more information, see Instance Metadata and User Data in the Amazon Elastic
Compute Cloud User Guide .
At this time, launch configurations don’t support compressed (zipped) user data files.
This value will be base64 encoded automatically. Do not base64 encode this
value prior to performing the operation.
• InstanceId (string) – The ID of the EC2 instance to use to create the launch configu-
ration.
The new launch configuration derives attributes from the instance, with the exception
of the block device mapping.
To create a launch configuration with a block device mapping or override any other
instance attributes, specify them as part of the same request.
For more information, see Create a Launch Configuration Using an EC2 Instance in
the Auto Scaling Developer Guide .
• InstanceType (string) – The instance type of the EC2 instance. For information about
available instance types, see Available Instance Types in the Amazon Elastic Cloud
Compute User Guide.
• KernelId (string) – The ID of the kernel associated with the AMI.
• RamdiskId (string) – The ID of the RAM disk associated with the AMI.
• BlockDeviceMappings (list) – One or more mappings that specify how block devices
are exposed to the instance. For more information, see Block Device Mapping in the
Amazon Elastic Compute Cloud User Guide .
– (dict) –
Describes a block device mapping.
3.1. Services 47
Boto3 Documentation, Release 1.1.4
* VirtualName (string) –
The name of the virtual device, ephemeral0 to ephemeral3 .
* DeviceName (string) – [REQUIRED]
The device name exposed to the EC2 instance (for example, /dev/sdh or
xvdh ).
* Ebs (dict) –
The information about the Amazon EBS volume.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The volume size, in gigabytes.
Valid values: If the volume type is io1 , the minimum size of the volume
is 10 GiB. If you specify SnapshotId and VolumeSize , VolumeSize
must be equal to or larger than the size of the snapshot.
Default: If you create a volume from a snapshot and you don’t specify a vol-
ume size, the default is the size of the snapshot.
Required: Required when the volume type is io1 .
· VolumeType (string) –
The volume type.
Valid values: standard | io1 | gp2
Default: standard
· DeleteOnTermination (boolean) –
Indicates whether to delete the volume on instance termination.
Default: true
· Iops (integer) –
For Provisioned IOPS (SSD) volumes only. The number of I/O operations per
second (IOPS) to provision for the volume.
Valid values: Range is 100 to 4000.
Default: None
* NoDevice (boolean) –
Suppresses a device mapping.
If this parameter is true for the root device, the instance might fail the EC2 health
check. Auto Scaling launches a replacement instance if the instance fails the
health check.
• InstanceMonitoring (dict) – Enables detailed monitoring if it is disabled. Detailed
monitoring is enabled by default.
When detailed monitoring is enabled, Amazon CloudWatch generates metrics every
minute and your account is charged a fee. When you disable detailed monitoring,
by specifying False , CloudWatch generates metrics every 5 minutes. For more
48 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
information, see Monitor Your Auto Scaling Instances in the Auto Scaling Developer
Guide .
– Enabled (boolean) –
If True , instance monitoring is enabled.
• SpotPrice (string) – The maximum hourly price to be paid for any Spot Instance
launched to fulfill the request. Spot Instances are launched when the price you spec-
ify exceeds the current Spot market price. For more information, see Launch Spot
Instances in Your Auto Scaling Group in the Auto Scaling Developer Guide .
• IamInstanceProfile (string) – The name or the Amazon Resource Name (ARN) of
the instance profile associated with the IAM role for the instance.
EC2 instances launched with an IAM role will automatically have AWS security cre-
dentials available. You can use IAM roles with Auto Scaling to automatically enable
applications running on your EC2 instances to securely access other AWS resources.
For more information, see Launch Auto Scaling Instances with an IAM Role in the
Auto Scaling Developer Guide .
• EbsOptimized (boolean) – Indicates whether the instance is optimized for Amazon
EBS I/O. By default, the instance is not optimized for EBS I/O. The optimization
provides dedicated throughput to Amazon EBS and an optimized configuration stack
to provide optimal I/O performance. This optimization is not available with all in-
stance types. Additional usage charges apply. For more information, see Amazon
EBS-Optimized Instances in the Amazon Elastic Compute Cloud User Guide .
• AssociatePublicIpAddress (boolean) – Used for groups that launch instances into a
virtual private cloud (VPC). Specifies whether to assign a public IP address to each
instance. For more information, see Auto Scaling and Amazon Virtual Private Cloud
in the Auto Scaling Developer Guide .
If you specify a value for this parameter, be sure to specify at least one subnet using
the VPCZoneIdentifier parameter when you create your group.
Default: If the instance is launched into a default subnet, the default is true . If
the instance is launched into a nondefault subnet, the default is false . For more
information, see Supported Platforms in the Amazon Elastic Compute Cloud User
Guide .
• PlacementTenancy (string) – The tenancy of the instance. An instance with a tenancy
of dedicated runs on single-tenant hardware and can only be launched into a VPC.
You must set the value of this parameter to dedicated if want to launch Dedicated
Instances into a shared tenancy VPC (VPC with instance placement tenancy attribute
set to default ).
If you specify a value for this parameter, be sure to specify at least one subnet using
the VPCZoneIdentifier parameter when you create your group.
For more information, see Auto Scaling and Amazon Virtual Private Cloud in the Auto
Scaling Developer Guide .
Valid values: default | dedicated
Returns None
create_or_update_tags(**kwargs)
Creates or updates tags for the specified Auto Scaling group.
3.1. Services 49
Boto3 Documentation, Release 1.1.4
A tag is defined by its resource ID, resource type, key, value, and propagate flag. The value and the
propagate flag are optional parameters. The only supported resource type is auto-scaling-group ,
and the resource ID must be the name of the group. The PropagateAtLaunch flag determines whether
the tag is added to instances launched in the group. Valid values are true or false .
When you specify a tag with a key that already exists, the operation overwrites the previous tag definition,
and you do not get an error message.
For more information, see Tagging Auto Scaling Groups and Instances in the Auto Scaling Developer
Guide .
Request Syntax
response = client.create_or_update_tags(
Tags=[
{
'ResourceId': 'string',
'ResourceType': 'string',
'Key': 'string',
'Value': 'string',
'PropagateAtLaunch': True|False
},
]
)
Parameters Tags (list) – [REQUIRED]
One or more tags.
• (dict) –
Describes a tag for an Auto Scaling group.
– ResourceId (string) –
The name of the group.
– ResourceType (string) –
The type of resource. The only supported value is auto-scaling-group
.
– Key (string) – [REQUIRED]
The tag key.
– Value (string) –
The tag value.
– PropagateAtLaunch (boolean) –
Determines whether the tag is added to new instances as they are launched in
the group.
Returns None
delete_auto_scaling_group(**kwargs)
Deletes the specified Auto Scaling group.
The group must have no instances and no scaling activities in progress.
To remove all instances before calling DeleteAutoScalingGroup , call UpdateAutoScalingGroup
to set the minimum and maximum size of the Auto Scaling group to zero.
50 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.delete_auto_scaling_group(
AutoScalingGroupName='string',
ForceDelete=True|False
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name of the group to delete.
• ForceDelete (boolean) – Specifies that the group will be deleted along with all
instances associated with the group, without waiting for all instances to be termi-
nated. This parameter also deletes any lifecycle actions associated with the group.
Returns None
delete_launch_configuration(**kwargs)
Deletes the specified launch configuration.
The launch configuration must not be attached to an Auto Scaling group. When this call completes, the
launch configuration is no longer available for use.
Request Syntax
response = client.delete_launch_configuration(
LaunchConfigurationName='string'
)
Parameters LaunchConfigurationName (string) – [REQUIRED]
The name of the launch configuration.
Returns None
delete_lifecycle_hook(**kwargs)
Deletes the specified lifecycle hook.
If there are any outstanding lifecycle actions, they are completed first (ABANDON for launching instances,
CONTINUE for terminating instances).
Request Syntax
response = client.delete_lifecycle_hook(
LifecycleHookName='string',
AutoScalingGroupName='string'
)
Parameters
• LifecycleHookName (string) – [REQUIRED]
The name of the lifecycle hook.
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group for the lifecycle hook.
Return type dict
3.1. Services 51
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{}
Response Structure
• (dict) –
delete_notification_configuration(**kwargs)
Deletes the specified notification.
Request Syntax
response = client.delete_notification_configuration(
AutoScalingGroupName='string',
TopicARN='string'
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group.
• TopicARN (string) – [REQUIRED]
The Amazon Resource Name (ARN) of the Amazon Simple Notification Service
(SNS) topic.
Returns None
delete_policy(**kwargs)
Deletes the specified Auto Scaling policy.
Request Syntax
response = client.delete_policy(
AutoScalingGroupName='string',
PolicyName='string'
)
Parameters
• AutoScalingGroupName (string) – The name of the Auto Scaling group.
• PolicyName (string) – [REQUIRED]
The name or Amazon Resource Name (ARN) of the policy.
Returns None
delete_scheduled_action(**kwargs)
Deletes the specified scheduled action.
Request Syntax
response = client.delete_scheduled_action(
AutoScalingGroupName='string',
ScheduledActionName='string'
)
52 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• AutoScalingGroupName (string) – The name of the Auto Scaling group.
• ScheduledActionName (string) – [REQUIRED]
The name of the action to delete.
Returns None
delete_tags(**kwargs)
Deletes the specified tags.
Request Syntax
response = client.delete_tags(
Tags=[
{
'ResourceId': 'string',
'ResourceType': 'string',
'Key': 'string',
'Value': 'string',
'PropagateAtLaunch': True|False
},
]
)
Parameters Tags (list) – [REQUIRED]
Each tag should be defined by its resource type, resource ID, key, value, and a propagate
flag. Valid values are: Resource type = auto-scaling-group , Resource ID = AutoScal-
ingGroupName , key=*value* , value=*value* , propagate=*true* or false .
• (dict) –
Describes a tag for an Auto Scaling group.
– ResourceId (string) –
The name of the group.
– ResourceType (string) –
The type of resource. The only supported value is auto-scaling-group
.
– Key (string) – [REQUIRED]
The tag key.
– Value (string) –
The tag value.
– PropagateAtLaunch (boolean) –
Determines whether the tag is added to new instances as they are launched in
the group.
Returns None
describe_account_limits()
Describes the current Auto Scaling resource limits for your AWS account.
3.1. Services 53
Boto3 Documentation, Release 1.1.4
For information about requesting an increase in these limits, see AWS Service Limits in the Amazon Web
Services General Reference .
Request Syntax
response = client.describe_account_limits()
Return type dict
Returns
Response Syntax
{
'MaxNumberOfAutoScalingGroups': 123,
'MaxNumberOfLaunchConfigurations': 123
}
Response Structure
• (dict) –
– MaxNumberOfAutoScalingGroups (integer) –
The maximum number of groups allowed for your AWS account. The default
limit is 20 per region.
– MaxNumberOfLaunchConfigurations (integer) –
The maximum number of launch configurations allowed for your AWS ac-
count. The default limit is 100 per region.
describe_adjustment_types()
Describes the policy adjustment types for use with PutScalingPolicy .
Request Syntax
response = client.describe_adjustment_types()
Return type dict
Returns
Response Syntax
{
'AdjustmentTypes': [
{
'AdjustmentType': 'string'
},
]
}
Response Structure
• (dict) –
– AdjustmentTypes (list) –
The policy adjustment types.
* (dict) –
Describes a policy adjustment type.
54 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
For more information, see Dynamic Scaling in the Auto Scaling Developer
Guide .
· AdjustmentType (string) –
The policy adjustment type. The valid values are ChangeInCapacity
, ExactCapacity , and PercentChangeInCapacity .
describe_auto_scaling_groups(**kwargs)
Describes one or more Auto Scaling groups. If a list of names is not provided, the call describes all Auto
Scaling groups.
Request Syntax
response = client.describe_auto_scaling_groups(
AutoScalingGroupNames=[
'string',
],
NextToken='string',
MaxRecords=123
)
Parameters
• AutoScalingGroupNames (list) – The group names.
– (string) –
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
• MaxRecords (integer) – The maximum number of items to return with this call.
Return type dict
Returns
Response Syntax
{
'AutoScalingGroups': [
{
'AutoScalingGroupName': 'string',
'AutoScalingGroupARN': 'string',
'LaunchConfigurationName': 'string',
'MinSize': 123,
'MaxSize': 123,
'DesiredCapacity': 123,
'DefaultCooldown': 123,
'AvailabilityZones': [
'string',
],
'LoadBalancerNames': [
'string',
],
'HealthCheckType': 'string',
'HealthCheckGracePeriod': 123,
'Instances': [
{
'InstanceId': 'string',
'AvailabilityZone': 'string',
'LifecycleState': 'Pending'|'Pending:Wait'|'Pending:Proceed'|'Q
3.1. Services 55
Boto3 Documentation, Release 1.1.4
'HealthStatus': 'string',
'LaunchConfigurationName': 'string'
},
],
'CreatedTime': datetime(2015, 1, 1),
'SuspendedProcesses': [
{
'ProcessName': 'string',
'SuspensionReason': 'string'
},
],
'PlacementGroup': 'string',
'VPCZoneIdentifier': 'string',
'EnabledMetrics': [
{
'Metric': 'string',
'Granularity': 'string'
},
],
'Status': 'string',
'Tags': [
{
'ResourceId': 'string',
'ResourceType': 'string',
'Key': 'string',
'Value': 'string',
'PropagateAtLaunch': True|False
},
],
'TerminationPolicies': [
'string',
]
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– AutoScalingGroups (list) –
The groups.
* (dict) –
Describes an Auto Scaling group.
· AutoScalingGroupName (string) –
The name of the group.
· AutoScalingGroupARN (string) –
The Amazon Resource Name (ARN) of the group.
· LaunchConfigurationName (string) –
The name of the associated launch configuration.
· MinSize (integer) –
56 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The minimum size of the group.
· MaxSize (integer) –
The maximum size of the group.
· DesiredCapacity (integer) –
The desired size of the group.
· DefaultCooldown (integer) –
The number of seconds after a scaling activity completes before any fur-
ther scaling activities can start.
· AvailabilityZones (list) –
One or more Availability Zones for the group.
· (string) –
· LoadBalancerNames (list) –
One or more load balancers associated with the group.
· (string) –
· HealthCheckType (string) –
The service of interest for the health status check, which can be either
EC2 for Amazon EC2 or ELB for Elastic Load Balancing.
· HealthCheckGracePeriod (integer) –
The amount of time that Auto Scaling waits before checking an instance’s
health status. The grace period begins when an instance comes into ser-
vice.
· Instances (list) –
The EC2 instances associated with the group.
· (dict) –
Describes an EC2 instance.
· InstanceId (string) –
The ID of the instance.
· AvailabilityZone (string) –
The Availability Zone in which the instance is running.
· LifecycleState (string) –
A description of the current lifecycle state. Note that the Quarantined
state is not used.
· HealthStatus (string) –
The health status of the instance.
· LaunchConfigurationName (string) –
The launch configuration associated with the instance.
· CreatedTime (datetime) –
The date and time the group was created.
3.1. Services 57
Boto3 Documentation, Release 1.1.4
· SuspendedProcesses (list) –
The suspended processes associated with the group.
· (dict) –
Describes an Auto Scaling process that has been suspended. For more
information, see ProcessType .
· ProcessName (string) –
The name of the suspended process.
· SuspensionReason (string) –
The reason that the process was suspended.
· PlacementGroup (string) –
The name of the placement group into which you’ll launch your instances,
if any. For more information, see Placement Groups .
· VPCZoneIdentifier (string) –
One or more subnet IDs, if applicable, separated by commas.
If you specify VPCZoneIdentifier and AvailabilityZones ,
ensure that the Availability Zones of the subnets match the values for
AvailabilityZones .
· EnabledMetrics (list) –
The metrics enabled for the group.
· (dict) –
Describes an enabled metric.
· Metric (string) –
The name of the metric.
· GroupMinSize
· GroupMaxSize
· GroupDesiredCapacity
· GroupInServiceInstances
· GroupPendingInstances
· GroupStandbyInstances
· GroupTerminatingInstances
· GroupTotalInstances
· Granularity (string) –
The granularity of the metric. The only valid value is 1Minute .
· Status (string) –
The current state of the group when DeleteAutoScalingGroup is in
progress.
· Tags (list) –
The tags for the group.
58 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes a tag for an Auto Scaling group.
· ResourceId (string) –
The name of the group.
· ResourceType (string) –
The type of resource. The only supported value is
auto-scaling-group .
· Key (string) –
The tag key.
· Value (string) –
The tag value.
· PropagateAtLaunch (boolean) –
Determines whether the tag is added to new instances as they are launched
in the group.
· TerminationPolicies (list) –
The termination policies for the group.
· (string) –
– NextToken (string) –
The token to use when requesting the next set of items. If there are no addi-
tional items to return, the string is empty.
describe_auto_scaling_instances(**kwargs)
Describes one or more Auto Scaling instances. If a list is not provided, the call describes all instances.
Request Syntax
response = client.describe_auto_scaling_instances(
InstanceIds=[
'string',
],
MaxRecords=123,
NextToken='string'
)
Parameters
• InstanceIds (list) – One or more Auto Scaling instances to describe, up to 50
instances. If you omit this parameter, all Auto Scaling instances are described.
If you specify an ID that does not exist, it is ignored with no error.
– (string) –
• MaxRecords (integer) – The maximum number of items to return with this call.
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
Return type dict
Returns
Response Syntax
3.1. Services 59
Boto3 Documentation, Release 1.1.4
{
'AutoScalingInstances': [
{
'InstanceId': 'string',
'AutoScalingGroupName': 'string',
'AvailabilityZone': 'string',
'LifecycleState': 'string',
'HealthStatus': 'string',
'LaunchConfigurationName': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– AutoScalingInstances (list) –
The instances.
* (dict) –
Describes an EC2 instance associated with an Auto Scaling group.
· InstanceId (string) –
The ID of the instance.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group associated with the in-
stance.
· AvailabilityZone (string) –
The Availability Zone for the instance.
· LifecycleState (string) –
The lifecycle state for the instance. For more information, see
Auto Scaling Instance States in the Auto Scaling Developer
Guide .
· HealthStatus (string) –
The health status of this instance. “Healthy” means that the
instance is healthy and should remain in service. “Unhealthy”
means that the instance is unhealthy and Auto Scaling should
terminate and replace it.
· LaunchConfigurationName (string) –
The launch configuration associated with the instance.
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_auto_scaling_notification_types()
Describes the notification types that are supported by Auto Scaling.
Request Syntax
response = client.describe_auto_scaling_notification_types()
Return type dict
60 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'AutoScalingNotificationTypes': [
'string',
]
}
Response Structure
• (dict) –
– AutoScalingNotificationTypes (list) –
One or more of the following notification types:
* autoscaling:EC2_INSTANCE_LAUNCH
* autoscaling:EC2_INSTANCE_LAUNCH_ERROR
* autoscaling:EC2_INSTANCE_TERMINATE
* autoscaling:EC2_INSTANCE_TERMINATE_ERROR
* autoscaling:TEST_NOTIFICATION
* (string) –
describe_launch_configurations(**kwargs)
Describes one or more launch configurations. If you omit the list of names, then the call describes all
launch configurations.
Request Syntax
response = client.describe_launch_configurations(
LaunchConfigurationNames=[
'string',
],
NextToken='string',
MaxRecords=123
)
Parameters
• LaunchConfigurationNames (list) – The launch configuration names.
– (string) –
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
• MaxRecords (integer) – The maximum number of items to return with this call.
The default is 100.
Return type dict
Returns
Response Syntax
{
'LaunchConfigurations': [
{
'LaunchConfigurationName': 'string',
'LaunchConfigurationARN': 'string',
'ImageId': 'string',
'KeyName': 'string',
'SecurityGroups': [
'string',
3.1. Services 61
Boto3 Documentation, Release 1.1.4
],
'ClassicLinkVPCId': 'string',
'ClassicLinkVPCSecurityGroups': [
'string',
],
'UserData': 'string',
'InstanceType': 'string',
'KernelId': 'string',
'RamdiskId': 'string',
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'VolumeType': 'string',
'DeleteOnTermination': True|False,
'Iops': 123
},
'NoDevice': True|False
},
],
'InstanceMonitoring': {
'Enabled': True|False
},
'SpotPrice': 'string',
'IamInstanceProfile': 'string',
'CreatedTime': datetime(2015, 1, 1),
'EbsOptimized': True|False,
'AssociatePublicIpAddress': True|False,
'PlacementTenancy': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– LaunchConfigurations (list) –
The launch configurations.
* (dict) –
Describes a launch configuration.
· LaunchConfigurationName (string) –
The name of the launch configuration.
· LaunchConfigurationARN (string) –
The Amazon Resource Name (ARN) of the launch configura-
tion.
· ImageId (string) –
The ID of the Amazon Machine Image (AMI).
· KeyName (string) –
The name of the key pair.
· SecurityGroups (list) –
62 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The security groups to associate with the instances.
· (string) –
· ClassicLinkVPCId (string) –
The ID of a ClassicLink-enabled VPC to link your EC2-
Classic instances to. This parameter can only be used if you
are launching EC2-Classic instances. For more information,
see ClassicLink in the Amazon Elastic Compute Cloud User
Guide .
· ClassicLinkVPCSecurityGroups (list) –
The IDs of one or more security groups for the VPC speci-
fied in ClassicLinkVPCId . This parameter is required if
ClassicLinkVPCId is specified, and cannot be used oth-
erwise. For more information, see ClassicLink in the Amazon
Elastic Compute Cloud User Guide .
· (string) –
· UserData (string) –
The user data available to the instances.
· InstanceType (string) –
The instance type for the instances.
· KernelId (string) –
The ID of the kernel associated with the AMI.
· RamdiskId (string) –
The ID of the RAM disk associated with the AMI.
· BlockDeviceMappings (list) –
A block device mapping, which specifies the block devices
for the instance.
· (dict) –
Describes a block device mapping.
· VirtualName (string) –
The name of the virtual device, ephemeral0 to
ephemeral3 .
· DeviceName (string) –
The device name exposed to the EC2 instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
The information about the Amazon EBS volume.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The volume size, in gigabytes.
Valid values: If the volume type is io1 , the minimum size
of the volume is 10 GiB. If you specify SnapshotId and
VolumeSize , VolumeSize must be equal to or larger
than the size of the snapshot.
Default: If you create a volume from a snapshot and you don’t
specify a volume size, the default is the size of the snapshot.
3.1. Services 63
Boto3 Documentation, Release 1.1.4
Required: Required when the volume type is io1 .
· VolumeType (string) –
The volume type.
Valid values: standard | io1 | gp2
Default: standard
· DeleteOnTermination (boolean) –
Indicates whether to delete the volume on instance termina-
tion.
Default: true
· Iops (integer) –
For Provisioned IOPS (SSD) volumes only. The number of
I/O operations per second (IOPS) to provision for the volume.
Valid values: Range is 100 to 4000.
Default: None
· NoDevice (boolean) –
Suppresses a device mapping.
If this parameter is true for the root device, the instance might
fail the EC2 health check. Auto Scaling launches a replace-
ment instance if the instance fails the health check.
· InstanceMonitoring (dict) –
Controls whether instances in this group are launched with
detailed monitoring.
· Enabled (boolean) –
If True , instance monitoring is enabled.
· SpotPrice (string) –
The price to bid when launching Spot Instances.
· IamInstanceProfile (string) –
The name or Amazon Resource Name (ARN) of the instance
profile associated with the IAM role for the instance.
· CreatedTime (datetime) –
The creation date and time for the launch configuration.
· EbsOptimized (boolean) –
Controls whether the instance is optimized for EBS I/O
(true ) or not (false ).
· AssociatePublicIpAddress (boolean) –
Specifies whether the instances are associated with a public
IP address (true ) or not (false ).
· PlacementTenancy (string) –
The tenancy of the instance, either default or dedicated
. An instance with dedicated tenancy runs in an isolated,
single-tenant hardware and can only be launched into a VPC.
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
64 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
describe_lifecycle_hook_types()
Describes the available types of lifecycle hooks.
Request Syntax
response = client.describe_lifecycle_hook_types()
Return type dict
Returns
Response Syntax
{
'LifecycleHookTypes': [
'string',
]
}
Response Structure
• (dict) –
– LifecycleHookTypes (list) –
One or more of the following notification types:
* autoscaling:EC2_INSTANCE_LAUNCHING
* autoscaling:EC2_INSTANCE_TERMINATING
* (string) –
describe_lifecycle_hooks(**kwargs)
Describes the lifecycle hooks for the specified Auto Scaling group.
Request Syntax
response = client.describe_lifecycle_hooks(
AutoScalingGroupName='string',
LifecycleHookNames=[
'string',
]
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name of the group.
• LifecycleHookNames (list) – The names of one or more lifecycle hooks.
– (string) –
Return type dict
Returns
Response Syntax
{
'LifecycleHooks': [
{
'LifecycleHookName': 'string',
'AutoScalingGroupName': 'string',
'LifecycleTransition': 'string',
'NotificationTargetARN': 'string',
'RoleARN': 'string',
3.1. Services 65
Boto3 Documentation, Release 1.1.4
'NotificationMetadata': 'string',
'HeartbeatTimeout': 123,
'GlobalTimeout': 123,
'DefaultResult': 'string'
},
]
}
Response Structure
• (dict) –
– LifecycleHooks (list) –
The lifecycle hooks for the specified group.
* (dict) –
Describes a lifecycle hook, which tells Auto Scaling that you want
to perform an action when an instance launches or terminates. When
you have a lifecycle hook in place, the Auto Scaling group will ei-
ther:
· Pause the instance after it launches, but before it is put into
service
· Pause the instance as it terminates, but before it is fully termi-
nated
For more information, see Auto Scaling Pending State and Auto
Scaling Terminating State in the Auto Scaling Developer Guide .
· LifecycleHookName (string) –
The name of the lifecycle hook.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group for the lifecycle hook.
· LifecycleTransition (string) –
The state of the EC2 instance to which you want to attach
the lifecycle hook. For a list of lifecycle hook types, see De-
scribeLifecycleHookTypes .
· NotificationTargetARN (string) –
The ARN of the notification target that Auto Scaling uses to
notify you when an instance is in the transition state for the
lifecycle hook. This ARN target can be either an SQS queue
or an SNS topic. The notification message sent to the target
includes the following:
· Lifecycle action token
· User account ID
· Name of the Auto Scaling group
· Lifecycle hook name
· EC2 instance ID
· Lifecycle transition
· Notification metadata
· RoleARN (string) –
The ARN of the IAM role that allows the Auto Scaling group
to publish to the specified notification target.
· NotificationMetadata (string) –
Additional information that you want to include any time
Auto Scaling sends a message to the notification target.
66 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· HeartbeatTimeout (integer) –
The amount of time that can elapse before the lifecycle hook
times out. When the lifecycle hook times out, Auto Scaling
performs the action defined in the DefaultResult param-
eter. You can prevent the lifecycle hook from timing out by
calling RecordLifecycleActionHeartbeat .
· GlobalTimeout (integer) –
The maximum length of time an instance can remain in
a Pending:Wait or Terminating:Wait state. Cur-
rently, the maximum is set to 48 hours.
· DefaultResult (string) –
Defines the action the Auto Scaling group should take when
the lifecycle hook timeout elapses or if an unexpected failure
occurs. The valid values are CONTINUE and ABANDON . The
default value is CONTINUE .
describe_load_balancers(**kwargs)
Describes the load balancers for the specified Auto Scaling group.
Request Syntax
response = client.describe_load_balancers(
AutoScalingGroupName='string',
NextToken='string',
MaxRecords=123
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name of the group.
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
• MaxRecords (integer) – The maximum number of items to return with this call.
Return type dict
Returns
Response Syntax
{
'LoadBalancers': [
{
'LoadBalancerName': 'string',
'State': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– LoadBalancers (list) –
The load balancers.
* (dict) –
Describes the state of a load balancer.
3.1. Services 67
Boto3 Documentation, Release 1.1.4
· LoadBalancerName (string) –
The name of the load balancer.
· State (string) –
The state of the load balancer.
· Adding - The instances in the group are being registered
with the load balancer.
· Added - All instances in the group are registered with the
load balancer.
· InService - At least one instance in the group passed an
ELB health check.
· Removing - The instances are being deregistered from the
load balancer. If connection draining is enabled, Elastic
Load Balancing waits for in-flight requests to complete be-
fore deregistering the instances.
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_metric_collection_types()
Describes the available CloudWatch metrics for Auto Scaling.
Note that the GroupStandbyInstances metric is not returned by default. You must explicitly request
this metric when calling EnableMetricsCollection .
Request Syntax
response = client.describe_metric_collection_types()
Return type dict
Returns
Response Syntax
{
'Metrics': [
{
'Metric': 'string'
},
],
'Granularities': [
{
'Granularity': 'string'
},
]
}
Response Structure
• (dict) –
– Metrics (list) –
One or more metrics.
* (dict) –
Describes a metric.
· Metric (string) –
The metric.
68 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· GroupMinSize
· GroupMaxSize
· GroupDesiredCapacity
· GroupInServiceInstances
· GroupPendingInstances
· GroupStandbyInstances
· GroupTerminatingInstances
· GroupTotalInstances
– Granularities (list) –
The granularities for the metrics.
* (dict) –
Describes a granularity of a metric.
· Granularity (string) –
The granularity. The only valid value is 1Minute .
describe_notification_configurations(**kwargs)
Describes the notification actions associated with the specified Auto Scaling group.
Request Syntax
response = client.describe_notification_configurations(
AutoScalingGroupNames=[
'string',
],
NextToken='string',
MaxRecords=123
)
Parameters
• AutoScalingGroupNames (list) – The name of the group.
– (string) –
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
• MaxRecords (integer) – The maximum number of items to return with this call.
Return type dict
Returns
Response Syntax
{
'NotificationConfigurations': [
{
'AutoScalingGroupName': 'string',
'TopicARN': 'string',
'NotificationType': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– NotificationConfigurations (list) –
The notification configurations.
3.1. Services 69
Boto3 Documentation, Release 1.1.4
* (dict) –
Describes a notification.
· AutoScalingGroupName (string) –
The name of the group.
· TopicARN (string) –
The Amazon Resource Name (ARN) of the Amazon Simple
Notification Service (SNS) topic.
· NotificationType (string) –
The types of events for an action to start.
· autoscaling:EC2_INSTANCE_LAUNCH
· autoscaling:EC2_INSTANCE_LAUNCH_ERROR
· autoscaling:EC2_INSTANCE_TERMINATE
· autoscaling:EC2_INSTANCE_TERMINATE_ERROR
· autoscaling:TEST_NOTIFICATION
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_policies(**kwargs)
Describes the policies for the specified Auto Scaling group.
Request Syntax
response = client.describe_policies(
AutoScalingGroupName='string',
PolicyNames=[
'string',
],
PolicyTypes=[
'string',
],
NextToken='string',
MaxRecords=123
)
Parameters
• AutoScalingGroupName (string) – The name of the group.
• PolicyNames (list) – One or more policy names or policy ARNs to be described.
If you omit this list, all policy names are described. If an group name is provided,
the results are limited to that group. This list is limited to 50 items. If you specify
an unknown policy name, it is ignored with no error.
– (string) –
• PolicyTypes (list) – One or more policy types. Valid values are
SimpleScaling and StepScaling .
– (string) –
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
• MaxRecords (integer) – The maximum number of items to be returned with
each call.
Return type dict
Returns
Response Syntax
70 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'ScalingPolicies': [
{
'AutoScalingGroupName': 'string',
'PolicyName': 'string',
'PolicyARN': 'string',
'PolicyType': 'string',
'AdjustmentType': 'string',
'MinAdjustmentStep': 123,
'MinAdjustmentMagnitude': 123,
'ScalingAdjustment': 123,
'Cooldown': 123,
'StepAdjustments': [
{
'MetricIntervalLowerBound': 123.0,
'MetricIntervalUpperBound': 123.0,
'ScalingAdjustment': 123
},
],
'MetricAggregationType': 'string',
'EstimatedInstanceWarmup': 123,
'Alarms': [
{
'AlarmName': 'string',
'AlarmARN': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– ScalingPolicies (list) –
The scaling policies.
* (dict) –
Describes a scaling policy.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group associated with this scal-
ing policy.
· PolicyName (string) –
The name of the scaling policy.
· PolicyARN (string) –
The Amazon Resource Name (ARN) of the policy.
· PolicyType (string) –
The policy type. Valid values are SimpleScaling and
StepScaling .
· AdjustmentType (string) –
The adjustment type, which specifies how
ScalingAdjustment is interpreted. Valid values
are ChangeInCapacity , ExactCapacity , and
3.1. Services 71
Boto3 Documentation, Release 1.1.4
PercentChangeInCapacity .
· MinAdjustmentStep (integer) –
Available for backward compatibility. Use
MinAdjustmentMagnitude instead.
· MinAdjustmentMagnitude (integer) –
The minimum number of instances to scale. If the value
of AdjustmentType is PercentChangeInCapacity
, the scaling policy changes the DesiredCapacity of the
Auto Scaling group by at least this many instances. Other-
wise, the error is ValidationError .
· ScalingAdjustment (integer) –
The amount by which to scale, based on the specified adjust-
ment type. A positive value adds to the current capacity while
a negative number removes from the current capacity.
· Cooldown (integer) –
The amount of time, in seconds, after a scaling activity com-
pletes before any further trigger-related scaling activities can
start.
· StepAdjustments (list) –
A set of adjustments that enable you to scale based on the size
of the alarm breach.
· (dict) –
Describes an adjustment based on the difference between the
value of the aggregated CloudWatch metric and the breach
threshold that you’ve defined for the alarm.
For the following examples, suppose that you have an alarm
with a breach threshold of 50:
· If you want the adjustment to be triggered when the metric is
greater than or equal to 50 and less than 60, specify a lower
bound of 0 and an upper bound of 10.
· If you want the adjustment to be triggered when the metric is
greater than 40 and less than or equal to 50, specify a lower
bound of -10 and an upper bound of 0.
There are a few rules for the step adjustments for your step
policy:
· The ranges of your step adjustments can’t overlap or have a
gap.
· At most one step adjustment can have a null lower bound. If
one step adjustment has a negative lower bound, then there
must be a step adjustment with a null lower bound.
· At most one step adjustment can have a null upper bound. If
one step adjustment has a positive upper bound, then there
must be a step adjustment with a null upper bound.
· The upper and lower bound can’t be null in the same step
adjustment.
· MetricIntervalLowerBound (float) –
The lower bound for the difference between the alarm thresh-
old and the CloudWatch metric. If the metric value is above
the breach threshold, the lower bound is inclusive (the metric
must be greater than or equal to the threshold plus the lower
72 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
bound). Otherwise, it is exclusive (the metric must be greater
than the threshold plus the lower bound). A null value indi-
cates negative infinity.
· MetricIntervalUpperBound (float) –
The upper bound for the difference between the alarm thresh-
old and the CloudWatch metric. If the metric value is above
the breach threshold, the upper bound is exclusive (the metric
must be less than the threshold plus the upper bound). Oth-
erwise, it is inclusive (the metric must be less than or equal
to the threshold plus the upper bound). A null value indicates
positive infinity.
The upper bound must be greater than the lower bound.
· ScalingAdjustment (integer) –
The amount by which to scale, based on the specified adjust-
ment type. A positive value adds to the current capacity while
a negative number removes from the current capacity.
· MetricAggregationType (string) –
The aggregation type for the CloudWatch metrics. Valid val-
ues are Minimum , Maximum , and Average .
· EstimatedInstanceWarmup (integer) –
The estimated time, in seconds, until a newly launched in-
stance can contribute to the CloudWatch metrics.
· Alarms (list) –
The CloudWatch alarms related to the policy.
· (dict) –
Describes an alarm.
· AlarmName (string) –
The name of the alarm.
· AlarmARN (string) –
The Amazon Resource Name (ARN) of the alarm.
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_scaling_activities(**kwargs)
Describes one or more scaling activities for the specified Auto Scaling group. If you omit the
ActivityIds , the call returns all activities from the past six weeks. Activities are sorted by the
start time. Activities still in progress appear first on the list.
Request Syntax
response = client.describe_scaling_activities(
ActivityIds=[
'string',
],
AutoScalingGroupName='string',
MaxRecords=123,
NextToken='string'
)
Parameters
3.1. Services 73
Boto3 Documentation, Release 1.1.4
• ActivityIds (list) – The activity IDs of the desired scaling activities. If this
list is omitted, all activities are described. If the AutoScalingGroupName
parameter is provided, the results are limited to that group. The list of requested
activities cannot contain more than 50 items. If unknown activities are requested,
they are ignored with no error.
– (string) –
• AutoScalingGroupName (string) – The name of the group.
• MaxRecords (integer) – The maximum number of items to return with this call.
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
Return type dict
Returns
Response Syntax
{
'Activities': [
{
'ActivityId': 'string',
'AutoScalingGroupName': 'string',
'Description': 'string',
'Cause': 'string',
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanc
'StatusMessage': 'string',
'Progress': 123,
'Details': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– Activities (list) –
The scaling activities.
* (dict) –
Describes scaling activity, which is a long-running process that rep-
resents a change to your Auto Scaling group, such as changing its
size or replacing an instance.
· ActivityId (string) –
The ID of the activity.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group.
· Description (string) –
A friendly, more verbose description of the activity.
· Cause (string) –
The reason the activity began.
· StartTime (datetime) –
The start time of the activity.
· EndTime (datetime) –
74 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The end time of the activity.
· StatusCode (string) –
The current status of the activity.
· StatusMessage (string) –
A friendly, more verbose description of the activity status.
· Progress (integer) –
A value between 0 and 100 that indicates the progress of the
activity.
· Details (string) –
The details about the activity.
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_scaling_process_types()
Describes the scaling process types for use with ResumeProcesses and SuspendProcesses .
Request Syntax
response = client.describe_scaling_process_types()
Return type dict
Returns
Response Syntax
{
'Processes': [
{
'ProcessName': 'string'
},
]
}
Response Structure
• (dict) –
– Processes (list) –
The names of the process types.
* (dict) –
Describes a process type.
For more information, see Auto Scaling Processes in the Auto Scal-
ing Developer Guide .
· ProcessName (string) –
The name of the process.
· Launch
· Terminate
· AddToLoadBalancer
· AlarmNotification
· AZRebalance
· HealthCheck
· ReplaceUnhealthy
· ScheduledActions
3.1. Services 75
Boto3 Documentation, Release 1.1.4
describe_scheduled_actions(**kwargs)
Describes the actions scheduled for your Auto Scaling group that haven’t run. To describe the actions that
have already run, use DescribeScalingActivities .
Request Syntax
response = client.describe_scheduled_actions(
AutoScalingGroupName='string',
ScheduledActionNames=[
'string',
],
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
NextToken='string',
MaxRecords=123
)
Parameters
• AutoScalingGroupName (string) – The name of the group.
• ScheduledActionNames (list) – Describes one or more scheduled actions. If
you omit this list, the call describes all scheduled actions. If you specify an
unknown scheduled action it is ignored with no error.
You can describe up to a maximum of 50 instances with a single call. If there are
more items to return, the call returns a token. To get the next set of items, repeat
the call with the returned token in the NextToken parameter.
– (string) –
• StartTime (datetime) – The earliest scheduled start time to return. If scheduled
action names are provided, this parameter is ignored.
• EndTime (datetime) – The latest scheduled start time to return. If scheduled
action names are provided, this parameter is ignored.
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
• MaxRecords (integer) – The maximum number of items to return with this call.
Return type dict
Returns
Response Syntax
{
'ScheduledUpdateGroupActions': [
{
'AutoScalingGroupName': 'string',
'ScheduledActionName': 'string',
'ScheduledActionARN': 'string',
'Time': datetime(2015, 1, 1),
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'Recurrence': 'string',
'MinSize': 123,
'MaxSize': 123,
'DesiredCapacity': 123
},
],
'NextToken': 'string'
}
Response Structure
76 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• (dict) –
– ScheduledUpdateGroupActions (list) –
The scheduled actions.
* (dict) –
Describes a scheduled update to an Auto Scaling group.
· AutoScalingGroupName (string) –
The name of the group.
· ScheduledActionName (string) –
The name of the scheduled action.
· ScheduledActionARN (string) –
The Amazon Resource Name (ARN) of the scheduled action.
· Time (datetime) –
This parameter is deprecated; use StartTime instead.
· StartTime (datetime) –
The date and time that the action is scheduled to begin. This
date and time can be up to one month in the future.
When StartTime and EndTime are specified with
Recurrence , they form the boundaries of when the recur-
ring action will start and stop.
· EndTime (datetime) –
The date and time that the action is scheduled to end. This
date and time can be up to one month in the future.
· Recurrence (string) –
The recurring schedule for the action.
· MinSize (integer) –
The minimum size of the group.
· MaxSize (integer) –
The maximum size of the group.
· DesiredCapacity (integer) –
The number of instances you prefer to maintain in the group.
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_tags(**kwargs)
Describes the specified tags.
You can use filters to limit the results. For example, you can query for the tags for a specific Auto Scaling
group. You can specify multiple values for a filter. A tag must match at least one of the specified values
for it to be included in the results.
You can also specify multiple filters. The result includes information for a particular tag only if it matches
all the filters. If there’s no match, no special message is returned.
Request Syntax
response = client.describe_tags(
Filters=[
{
3.1. Services 77
Boto3 Documentation, Release 1.1.4
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxRecords=123
)
Parameters
• Filters (list) – A filter used to scope the tags to return.
– (dict) –
Describes a filter.
* Name (string) –
The name of the filter. The valid values are:
"auto-scaling-group" , "key" , "value" , and
"propagate-at-launch" .
* Values (list) –
The value of the filter.
· (string) –
• NextToken (string) – The token for the next set of items to return. (You received
this token from a previous call.)
• MaxRecords (integer) – The maximum number of items to return with this call.
Return type dict
Returns
Response Syntax
{
'Tags': [
{
'ResourceId': 'string',
'ResourceType': 'string',
'Key': 'string',
'Value': 'string',
'PropagateAtLaunch': True|False
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– Tags (list) –
The tags.
* (dict) –
Describes a tag for an Auto Scaling group.
· ResourceId (string) –
The name of the group.
· ResourceType (string) –
The type of resource. The only supported value is
auto-scaling-group .
78 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Key (string) –
The tag key.
· Value (string) –
The tag value.
· PropagateAtLaunch (boolean) –
Determines whether the tag is added to new instances as they
are launched in the group.
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_termination_policy_types()
Describes the termination policies supported by Auto Scaling.
Request Syntax
response = client.describe_termination_policy_types()
Return type dict
Returns
Response Syntax
{
'TerminationPolicyTypes': [
'string',
]
}
Response Structure
• (dict) –
– TerminationPolicyTypes (list) –
The termination policies supported by Auto Scaling (OldestInstance
, OldestLaunchConfiguration , NewestInstance ,
ClosestToNextInstanceHour , and Default ).
* (string) –
detach_instances(**kwargs)
Removes one or more instances from the specified Auto Scaling group. After the instances are detached,
you can manage them independently from the rest of the Auto Scaling group.
For more information, see Detach EC2 Instances from Your Auto Scaling Group in the Auto Scaling
Developer Guide .
Request Syntax
response = client.detach_instances(
InstanceIds=[
'string',
],
AutoScalingGroupName='string',
ShouldDecrementDesiredCapacity=True|False
)
Parameters
• InstanceIds (list) – One or more instance IDs.
3.1. Services 79
Boto3 Documentation, Release 1.1.4
– (string) –
• AutoScalingGroupName (string) – [REQUIRED]
The name of the group.
• ShouldDecrementDesiredCapacity (boolean) – [REQUIRED]
If True , the Auto Scaling group decrements the desired capacity value by the
number of instances detached.
Return type dict
Returns
Response Syntax
{
'Activities': [
{
'ActivityId': 'string',
'AutoScalingGroupName': 'string',
'Description': 'string',
'Cause': 'string',
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanc
'StatusMessage': 'string',
'Progress': 123,
'Details': 'string'
},
]
}
Response Structure
• (dict) –
– Activities (list) –
The activities related to detaching the instances from the Auto Scaling
group.
* (dict) –
Describes scaling activity, which is a long-running process that rep-
resents a change to your Auto Scaling group, such as changing its
size or replacing an instance.
· ActivityId (string) –
The ID of the activity.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group.
· Description (string) –
A friendly, more verbose description of the activity.
· Cause (string) –
The reason the activity began.
· StartTime (datetime) –
The start time of the activity.
· EndTime (datetime) –
The end time of the activity.
· StatusCode (string) –
80 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The current status of the activity.
· StatusMessage (string) –
A friendly, more verbose description of the activity status.
· Progress (integer) –
A value between 0 and 100 that indicates the progress of the
activity.
· Details (string) –
The details about the activity.
detach_load_balancers(**kwargs)
Removes one or more load balancers from the specified Auto Scaling group.
When you detach a load balancer, it enters the Removing state while deregistering the instances in the
group. When all instances are deregistered, then you can no longer describe the load balancer using
DescribeLoadBalancers . Note that the instances remain running.
Request Syntax
response = client.detach_load_balancers(
AutoScalingGroupName='string',
LoadBalancerNames=[
'string',
]
)
Parameters
• AutoScalingGroupName (string) – The name of the group.
• LoadBalancerNames (list) – One or more load balancer names.
– (string) –
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
disable_metrics_collection(**kwargs)
Disables monitoring of the specified metrics for the specified Auto Scaling group.
Request Syntax
response = client.disable_metrics_collection(
AutoScalingGroupName='string',
Metrics=[
'string',
]
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name or Amazon Resource Name (ARN) of the group.
• Metrics (list) – One or more metrics. If you omit this parameter, all metrics are
disabled.
3.1. Services 81
Boto3 Documentation, Release 1.1.4
– GroupMinSize
– GroupMaxSize
– GroupDesiredCapacity
– GroupInServiceInstances
– GroupPendingInstances
– GroupStandbyInstances
– GroupTerminatingInstances
– GroupTotalInstances
– (string) –
Returns None
enable_metrics_collection(**kwargs)
Enables monitoring of the specified metrics for the specified Auto Scaling group.
You can only enable metrics collection if InstanceMonitoring in the launch configuration for the
group is set to True .
Request Syntax
response = client.enable_metrics_collection(
AutoScalingGroupName='string',
Metrics=[
'string',
],
Granularity='string'
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name or ARN of the Auto Scaling group.
• Metrics (list) – One or more metrics. If you omit this parameter, all metrics are
enabled.
– GroupMinSize
– GroupMaxSize
– GroupDesiredCapacity
– GroupInServiceInstances
– GroupPendingInstances
– GroupStandbyInstances
– GroupTerminatingInstances
– GroupTotalInstances
Note that the GroupStandbyInstances metric is not enabled by default.
You must explicitly request this metric.
– (string) –
• Granularity (string) – [REQUIRED]
The granularity to associate with the metrics to collect. The only valid value is
1Minute .
Returns None
enter_standby(**kwargs)
Moves the specified instances into Standby mode.
For more information, see Auto Scaling InService State in the Auto Scaling Developer Guide .
Request Syntax
82 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.enter_standby(
InstanceIds=[
'string',
],
AutoScalingGroupName='string',
ShouldDecrementDesiredCapacity=True|False
)
Parameters
• InstanceIds (list) – One or more instances to move into Standby mode. You
must specify at least one instance ID.
– (string) –
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group.
• ShouldDecrementDesiredCapacity (boolean) – [REQUIRED]
Specifies whether the instances moved to Standby mode count as part of the
Auto Scaling group’s desired capacity. If set, the desired capacity for the Auto
Scaling group decrements by the number of instances moved to Standby mode.
Return type dict
Returns
Response Syntax
{
'Activities': [
{
'ActivityId': 'string',
'AutoScalingGroupName': 'string',
'Description': 'string',
'Cause': 'string',
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanc
'StatusMessage': 'string',
'Progress': 123,
'Details': 'string'
},
]
}
Response Structure
• (dict) –
– Activities (list) –
The activities related to moving instances into Standby mode.
* (dict) –
Describes scaling activity, which is a long-running process that rep-
resents a change to your Auto Scaling group, such as changing its
size or replacing an instance.
· ActivityId (string) –
The ID of the activity.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group.
3.1. Services 83
Boto3 Documentation, Release 1.1.4
· Description (string) –
A friendly, more verbose description of the activity.
· Cause (string) –
The reason the activity began.
· StartTime (datetime) –
The start time of the activity.
· EndTime (datetime) –
The end time of the activity.
· StatusCode (string) –
The current status of the activity.
· StatusMessage (string) –
A friendly, more verbose description of the activity status.
· Progress (integer) –
A value between 0 and 100 that indicates the progress of the
activity.
· Details (string) –
The details about the activity.
execute_policy(**kwargs)
Executes the specified policy.
Request Syntax
response = client.execute_policy(
AutoScalingGroupName='string',
PolicyName='string',
HonorCooldown=True|False,
MetricValue=123.0,
BreachThreshold=123.0
)
Parameters
• AutoScalingGroupName (string) – The name or Amazon Resource Name
(ARN) of the Auto Scaling group.
• PolicyName (string) – [REQUIRED]
The name or ARN of the policy.
• HonorCooldown (boolean) – If this parameter is true, Auto Scaling waits for
the cooldown period to complete before executing the policy. Otherwise, Auto
Scaling executes the policy without waiting for the cooldown period to complete.
This parameter is not supported if the policy type is StepScaling .
For more information, see Understanding Auto Scaling Cooldowns in the Auto
Scaling Developer Guide .
• MetricValue (float) – The metric value to compare to BreachThreshold
. This enables you to execute a policy of type StepScaling and determine
which step adjustment to use. For example, if the breach threshold is 50 and you
want to use a step adjustment with a lower bound of 0 and an upper bound of 10,
you can set the metric value to 59.
If you specify a metric value that doesn’t correspond to a step adjustment for the
policy, the call returns an error.
84 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
This parameter is required if the policy type is StepScaling and not sup-
ported otherwise.
• BreachThreshold (float) – The breach threshold for the alarm.
This parameter is required if the policy type is StepScaling and not sup-
ported otherwise.
Returns None
exit_standby(**kwargs)
Moves the specified instances out of Standby mode.
For more information, see Auto Scaling InService State in the Auto Scaling Developer Guide .
Request Syntax
response = client.exit_standby(
InstanceIds=[
'string',
],
AutoScalingGroupName='string'
)
Parameters
• InstanceIds (list) – One or more instance IDs. You must specify at least one
instance ID.
– (string) –
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group.
Return type dict
Returns
Response Syntax
{
'Activities': [
{
'ActivityId': 'string',
'AutoScalingGroupName': 'string',
'Description': 'string',
'Cause': 'string',
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanc
'StatusMessage': 'string',
'Progress': 123,
'Details': 'string'
},
]
}
Response Structure
• (dict) –
– Activities (list) –
The activities related to moving instances out of Standby mode.
* (dict) –
3.1. Services 85
Boto3 Documentation, Release 1.1.4
Describes scaling activity, which is a long-running process that rep-
resents a change to your Auto Scaling group, such as changing its
size or replacing an instance.
· ActivityId (string) –
The ID of the activity.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group.
· Description (string) –
A friendly, more verbose description of the activity.
· Cause (string) –
The reason the activity began.
· StartTime (datetime) –
The start time of the activity.
· EndTime (datetime) –
The end time of the activity.
· StatusCode (string) –
The current status of the activity.
· StatusMessage (string) –
A friendly, more verbose description of the activity status.
· Progress (integer) –
A value between 0 and 100 that indicates the progress of the
activity.
· Details (string) –
The details about the activity.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
86 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
put_lifecycle_hook(**kwargs)
Creates or updates a lifecycle hook for the specified Auto Scaling Group.
A lifecycle hook tells Auto Scaling that you want to perform an action on an instance that is not actively
in service; for example, either when the instance launches or before the instance terminates.
This operation is a part of the basic sequence for adding a lifecycle hook to an Auto Scaling group:
•Create a notification target. A target can be either an Amazon SQS queue or an Amazon SNS topic.
•Create an IAM role. This role allows Auto Scaling to publish lifecycle notifications to the desig-
nated SQS queue or SNS topic.
•Create the lifecycle hook. You can create a hook that acts when instances launch or when
instances terminate.
•If necessary, record the lifecycle action heartbeat to keep the instance in a pending state.
•Complete the lifecycle action.
For more information, see Auto Scaling Pending State and Auto Scaling Terminating State in the Auto
Scaling Developer Guide .
If you exceed your maximum limit of lifecycle hooks, which by default is 50 per region, the call fails.
For information about updating this limit, see AWS Service Limits in the Amazon Web Services General
Reference .
Request Syntax
response = client.put_lifecycle_hook(
LifecycleHookName='string',
AutoScalingGroupName='string',
LifecycleTransition='string',
RoleARN='string',
NotificationTargetARN='string',
NotificationMetadata='string',
HeartbeatTimeout=123,
DefaultResult='string'
)
Parameters
• LifecycleHookName (string) – [REQUIRED]
The name of the lifecycle hook.
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group to which you want to assign the lifecycle
hook.
• LifecycleTransition (string) – The instance state to which you want to attach
the lifecycle hook. For a list of lifecycle hook types, see DescribeLifecycle-
HookTypes .
This parameter is required for new lifecycle hooks, but optional when updating
existing hooks.
• RoleARN (string) – The ARN of the IAM role that allows the Auto Scaling
group to publish to the specified notification target.
This parameter is required for new lifecycle hooks, but optional when updating
existing hooks.
• NotificationTargetARN (string) – The ARN of the notification target that Auto
Scaling will use to notify you when an instance is in the transition state for the
lifecycle hook. This ARN target can be either an SQS queue or an SNS topic.
This parameter is required for new lifecycle hooks, but optional when updating
existing hooks.
3.1. Services 87
Boto3 Documentation, Release 1.1.4
The notification message sent to the target will include:
– LifecycleActionToken . The Lifecycle action token.
– AccountId . The user account ID.
– AutoScalingGroupName . The name of the Auto Scaling group.
– LifecycleHookName . The lifecycle hook name.
– EC2InstanceId . The EC2 instance ID.
– LifecycleTransition . The lifecycle transition.
– NotificationMetadata . The notification metadata.
This operation uses the JSON format when sending notifications to an Amazon
SQS queue, and an email key/value pair format when sending notifications to an
Amazon SNS topic.
When you call this operation, a test message is sent to the notifica-
tion target. This test message contains an additional key/value pair:
Event:autoscaling:TEST_NOTIFICATION .
• NotificationMetadata (string) – Contains additional information that you want
to include any time Auto Scaling sends a message to the notification target.
• HeartbeatTimeout (integer) – Defines the amount of time, in seconds, that can
elapse before the lifecycle hook times out. When the lifecycle hook times out,
Auto Scaling performs the action defined in the DefaultResult parameter.
You can prevent the lifecycle hook from timing out by calling RecordLifecy-
cleActionHeartbeat . The default value for this parameter is 3600 seconds (1
hour).
• DefaultResult (string) – Defines the action the Auto Scaling group should take
when the lifecycle hook timeout elapses or if an unexpected failure occurs. The
value for this parameter can be either CONTINUE or ABANDON . The default
value for this parameter is ABANDON .
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
put_notification_configuration(**kwargs)
Configures an Auto Scaling group to send notifications when specified events take place. Subscribers to
this topic can have messages for events delivered to an endpoint such as a web server or email address.
For more information see Getting Notifications When Your Auto Scaling Group Changes in the Auto
Scaling Developer Guide .
This configuration overwrites an existing configuration.
Request Syntax
response = client.put_notification_configuration(
AutoScalingGroupName='string',
TopicARN='string',
NotificationTypes=[
'string',
]
)
Parameters
88 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group.
• TopicARN (string) – [REQUIRED]
The Amazon Resource Name (ARN) of the Amazon Simple Notification Service
(SNS) topic.
• NotificationTypes (list) – [REQUIRED]
The type of event that will cause the notification to be sent. For details about
notification types supported by Auto Scaling, see DescribeAutoScalingNotifica-
tionTypes .
– (string) –
Returns None
put_scaling_policy(**kwargs)
Creates or updates a policy for an Auto Scaling group. To update an existing policy, use the existing
policy name and set the parameters you want to change. Any existing parameter not changed in an update
to an existing policy is not changed in this update request.
If you exceed your maximum limit of step adjustments, which by default is 20 per region, the call fails.
For information about updating this limit, see AWS Service Limits in the Amazon Web Services General
Reference .
Request Syntax
response = client.put_scaling_policy(
AutoScalingGroupName='string',
PolicyName='string',
PolicyType='string',
AdjustmentType='string',
MinAdjustmentStep=123,
MinAdjustmentMagnitude=123,
ScalingAdjustment=123,
Cooldown=123,
MetricAggregationType='string',
StepAdjustments=[
{
'MetricIntervalLowerBound': 123.0,
'MetricIntervalUpperBound': 123.0,
'ScalingAdjustment': 123
},
],
EstimatedInstanceWarmup=123
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name or ARN of the group.
• PolicyName (string) – [REQUIRED]
The name of the policy.
• PolicyType (string) – The policy type. Valid values are SimpleScaling
and StepScaling . If the policy type is null, the value is treated as
SimpleScaling .
• AdjustmentType (string) – [REQUIRED]
The adjustment type. Valid values are ChangeInCapacity ,
ExactCapacity , and PercentChangeInCapacity .
3.1. Services 89
Boto3 Documentation, Release 1.1.4
For more information, see Dynamic Scaling in the Auto Scaling Developer Guide
.
• MinAdjustmentStep (integer) – Available for backward compatibility. Use
MinAdjustmentMagnitude instead.
• MinAdjustmentMagnitude (integer) – The minimum number of instances to
scale. If the value of AdjustmentType is PercentChangeInCapacity
, the scaling policy changes the DesiredCapacity of the Auto Scaling group
by at least this many instances. Otherwise, the error is ValidationError .
• ScalingAdjustment (integer) – The amount by which to scale, based on the
specified adjustment type. A positive value adds to the current capacity while a
negative number removes from the current capacity.
This parameter is required if the policy type is SimpleScaling and not sup-
ported otherwise.
• Cooldown (integer) – The amount of time, in seconds, after a scaling activity
completes and before the next scaling activity can start. If this parameter is not
specified, the default cooldown period for the group applies.
This parameter is not supported unless the policy type is SimpleScaling .
For more information, see Understanding Auto Scaling Cooldowns in the Auto
Scaling Developer Guide .
• MetricAggregationType (string) – The aggregation type for the CloudWatch
metrics. Valid values are Minimum , Maximum , and Average . If the aggre-
gation type is null, the value is treated as Average .
This parameter is not supported if the policy type is SimpleScaling .
• StepAdjustments (list) – A set of adjustments that enable you to scale based on
the size of the alarm breach.
This parameter is required if the policy type is StepScaling and not sup-
ported otherwise.
– (dict) –
Describes an adjustment based on the difference between the value of the
aggregated CloudWatch metric and the breach threshold that you’ve de-
fined for the alarm.
For the following examples, suppose that you have an alarm with a breach
threshold of 50:
* If you want the adjustment to be triggered when the metric is greater
than or equal to 50 and less than 60, specify a lower bound of 0 and
an upper bound of 10.
* If you want the adjustment to be triggered when the metric is greater
than 40 and less than or equal to 50, specify a lower bound of -10
and an upper bound of 0.
There are a few rules for the step adjustments for your step policy:
* The ranges of your step adjustments can’t overlap or have a gap.
* At most one step adjustment can have a null lower bound. If one
step adjustment has a negative lower bound, then there must be a
step adjustment with a null lower bound.
* At most one step adjustment can have a null upper bound. If one
step adjustment has a positive upper bound, then there must be a
step adjustment with a null upper bound.
* The upper and lower bound can’t be null in the same step adjust-
ment.
* MetricIntervalLowerBound (float) –
90 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The lower bound for the difference between the alarm threshold and
the CloudWatch metric. If the metric value is above the breach
threshold, the lower bound is inclusive (the metric must be greater
than or equal to the threshold plus the lower bound). Otherwise, it
is exclusive (the metric must be greater than the threshold plus the
lower bound). A null value indicates negative infinity.
* MetricIntervalUpperBound (float) –
The upper bound for the difference between the alarm threshold
and the CloudWatch metric. If the metric value is above the breach
threshold, the upper bound is exclusive (the metric must be less than
the threshold plus the upper bound). Otherwise, it is inclusive (the
metric must be less than or equal to the threshold plus the upper
bound). A null value indicates positive infinity.
The upper bound must be greater than the lower bound.
* ScalingAdjustment (integer) – [REQUIRED]
The amount by which to scale, based on the specified adjustment
type. A positive value adds to the current capacity while a negative
number removes from the current capacity.
• EstimatedInstanceWarmup (integer) – The estimated time, in seconds, until a
newly launched instance can contribute to the CloudWatch metrics. The default
is to use the value specified for the default cooldown period for the group.
This parameter is not supported if the policy type is SimpleScaling .
Return type dict
Returns
Response Syntax
{
'PolicyARN': 'string'
}
Response Structure
• (dict) –
– PolicyARN (string) –
The Amazon Resource Name (ARN) of the policy.
put_scheduled_update_group_action(**kwargs)
Creates or updates a scheduled scaling action for an Auto Scaling group. When updating a scheduled
scaling action, if you leave a parameter unspecified, the corresponding value remains unchanged in the
affected Auto Scaling group.
For more information, see Scheduled Scaling in the Auto Scaling Developer Guide .
Request Syntax
response = client.put_scheduled_update_group_action(
AutoScalingGroupName='string',
ScheduledActionName='string',
Time=datetime(2015, 1, 1),
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
Recurrence='string',
MinSize=123,
MaxSize=123,
3.1. Services 91
Boto3 Documentation, Release 1.1.4
DesiredCapacity=123
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name or Amazon Resource Name (ARN) of the Auto Scaling group.
• ScheduledActionName (string) – [REQUIRED]
The name of this scaling action.
• Time (datetime) – This parameter is deprecated; use StartTime instead.
The time for this action to start. If both Time and StartTime are specified,
their values must be identical.
• StartTime (datetime) – The time for this action to start, in “YYYY-
MM-DDThh:mm:ssZ” format in UTC/GMT only (for example,
2014-06-01T00:00:00Z ).
If you try to schedule your action in the past, Auto Scaling returns an error
message.
When StartTime and EndTime are specified with Recurrence , they form
the boundaries of when the recurring action starts and stops.
• EndTime (datetime) – The time for this action to end.
• Recurrence (string) – The time when recurring future actions will start. Start
time is specified by the user following the Unix cron syntax format. For more
information, see Cron in Wikipedia.
When StartTime and EndTime are specified with Recurrence , they form
the boundaries of when the recurring action will start and stop.
• MinSize (integer) – The minimum size for the Auto Scaling group.
• MaxSize (integer) – The maximum size for the Auto Scaling group.
• DesiredCapacity (integer) – The number of EC2 instances that should be run-
ning in the group.
Returns None
record_lifecycle_action_heartbeat(**kwargs)
Records a heartbeat for the lifecycle action associated with a specific token. This extends the timeout by
the length of time defined by the HeartbeatTimeout parameter of PutLifecycleHook .
This operation is a part of the basic sequence for adding a lifecycle hook to an Auto Scaling group:
•Create a notification target. A target can be either an Amazon SQS queue or an Amazon SNS topic.
•Create an IAM role. This role allows Auto Scaling to publish lifecycle notifications to the desig-
nated SQS queue or SNS topic.
•Create the lifecycle hook. You can create a hook that acts when instances launch or when instances
terminate.
•If necessary, record the lifecycle action heartbeat to keep the instance in a pending state.
•Complete the lifecycle action.
For more information, see Auto Scaling Pending State and Auto Scaling Terminating State in the Auto
Scaling Developer Guide .
Request Syntax
response = client.record_lifecycle_action_heartbeat(
LifecycleHookName='string',
AutoScalingGroupName='string',
LifecycleActionToken='string'
)
92 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• LifecycleHookName (string) – [REQUIRED]
The name of the lifecycle hook.
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group for the hook.
• LifecycleActionToken (string) – [REQUIRED]
A token that uniquely identifies a specific lifecycle action associated with an
instance. Auto Scaling sends this token to the notification target you specified
when you created the lifecycle hook.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
resume_processes(**kwargs)
Resumes the specified suspended Auto Scaling processes for the specified Auto Scaling group. To re-
sume specific processes, use the ScalingProcesses parameter. To resume all processes, omit the
ScalingProcesses parameter. For more information, see Suspend and Resume Auto Scaling Pro-
cesses in the Auto Scaling Developer Guide .
Request Syntax
response = client.resume_processes(
AutoScalingGroupName='string',
ScalingProcesses=[
'string',
]
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name or Amazon Resource Name (ARN) of the Auto Scaling group.
• ScalingProcesses (list) – One or more of the following processes:
– Launch
– Terminate
– HealthCheck
– ReplaceUnhealthy
– AZRebalance
– AlarmNotification
– ScheduledActions
– AddToLoadBalancer
– (string) –
Returns None
set_desired_capacity(**kwargs)
Sets the size of the specified Auto Scaling group.
For more information about desired capacity, see What Is Auto Scaling? in the Auto Scaling Developer
Guide .
3.1. Services 93
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.set_desired_capacity(
AutoScalingGroupName='string',
DesiredCapacity=123,
HonorCooldown=True|False
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group.
• DesiredCapacity (integer) – [REQUIRED]
The number of EC2 instances that should be running in the Auto Scaling group.
• HonorCooldown (boolean) – By default, SetDesiredCapacity overrides
any cooldown period associated with the Auto Scaling group. Specify True to
make Auto Scaling to wait for the cool-down period associated with the Auto
Scaling group to complete before initiating a scaling activity to set your Auto
Scaling group to its new capacity.
Returns None
set_instance_health(**kwargs)
Sets the health status of the specified instance.
For more information, see Health Checks in the Auto Scaling Developer Guide .
Request Syntax
response = client.set_instance_health(
InstanceId='string',
HealthStatus='string',
ShouldRespectGracePeriod=True|False
)
Parameters
• InstanceId (string) – [REQUIRED]
The ID of the EC2 instance.
• HealthStatus (string) – [REQUIRED]
The health status of the instance. Set to Healthy if you want the instance to
remain in service. Set to Unhealthy if you want the instance to be out of
service. Auto Scaling will terminate and replace the unhealthy instance.
• ShouldRespectGracePeriod (boolean) – If the Auto Scaling group of the spec-
ified instance has a HealthCheckGracePeriod specified for the group, by
default, this call will respect the grace period. Set this to False , if you do not
want the call to respect the grace period associated with the group.
For more information, see the HealthCheckGracePeriod parameter de-
scription for CreateAutoScalingGroup .
Returns None
suspend_processes(**kwargs)
Suspends the specified Auto Scaling processes for the specified Auto Scaling group. To suspend
specific processes, use the ScalingProcesses parameter. To suspend all processes, omit the
ScalingProcesses parameter.
Note that if you suspend either the Launch or Terminate process types, it can prevent other process
types from functioning properly.
94 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
To resume processes that have been suspended, use ResumeProcesses .
For more information, see Suspend and Resume Auto Scaling Processes in the Auto Scaling Developer
Guide .
Request Syntax
response = client.suspend_processes(
AutoScalingGroupName='string',
ScalingProcesses=[
'string',
]
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name or Amazon Resource Name (ARN) of the Auto Scaling group.
• ScalingProcesses (list) – One or more of the following processes:
– Launch
– Terminate
– HealthCheck
– ReplaceUnhealthy
– AZRebalance
– AlarmNotification
– ScheduledActions
– AddToLoadBalancer
– (string) –
Returns None
terminate_instance_in_auto_scaling_group(**kwargs)
Terminates the specified instance and optionally adjusts the desired group size.
This call simply makes a termination request. The instances is not terminated immediately.
Request Syntax
response = client.terminate_instance_in_auto_scaling_group(
InstanceId='string',
ShouldDecrementDesiredCapacity=True|False
)
Parameters
• InstanceId (string) – [REQUIRED]
The ID of the EC2 instance.
• ShouldDecrementDesiredCapacity (boolean) – [REQUIRED]
If true , terminating this instance also decrements the size of the Auto Scaling
group.
Return type dict
Returns
Response Syntax
{
'Activity': {
'ActivityId': 'string',
'AutoScalingGroupName': 'string',
3.1. Services 95
Boto3 Documentation, Release 1.1.4
'Description': 'string',
'Cause': 'string',
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanceId'
'StatusMessage': 'string',
'Progress': 123,
'Details': 'string'
}
}
Response Structure
• (dict) –
– Activity (dict) –
A scaling activity.
* ActivityId (string) –
The ID of the activity.
* AutoScalingGroupName (string) –
The name of the Auto Scaling group.
* Description (string) –
A friendly, more verbose description of the activity.
* Cause (string) –
The reason the activity began.
* StartTime (datetime) –
The start time of the activity.
* EndTime (datetime) –
The end time of the activity.
* StatusCode (string) –
The current status of the activity.
* StatusMessage (string) –
A friendly, more verbose description of the activity status.
* Progress (integer) –
A value between 0 and 100 that indicates the progress of the activity.
* Details (string) –
The details about the activity.
update_auto_scaling_group(**kwargs)
Updates the configuration for the specified Auto Scaling group.
To update an Auto Scaling group with a launch configuration with InstanceMonitoring set to
False , you must first disable the collection of group metrics. Otherwise, you will get an error. If
you have previously enabled the collection of group metrics, you can disable it using DisableMetricsCol-
lection .
The new settings are registered upon the completion of this call. Any launch configuration settings take
effect on any triggers after this call returns. Scaling activities that are currently in progress aren’t affected.
Note the following:
•If you specify a new value for MinSize without specifying a value for DesiredCapacity , and
the new MinSize is larger than the current size of the group, we implicitly call SetDesiredCapacity
to set the size of the group to the new value of MinSize .
96 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
•If you specify a new value for MaxSize without specifying a value for DesiredCapacity ,
and the new MaxSize is smaller than the current size of the group, we implicitly call SetDesired-
Capacity to set the size of the group to the new value of MaxSize .
•All other optional parameters are left unchanged if not specified.
Request Syntax
response = client.update_auto_scaling_group(
AutoScalingGroupName='string',
LaunchConfigurationName='string',
MinSize=123,
MaxSize=123,
DesiredCapacity=123,
DefaultCooldown=123,
AvailabilityZones=[
'string',
],
HealthCheckType='string',
HealthCheckGracePeriod=123,
PlacementGroup='string',
VPCZoneIdentifier='string',
TerminationPolicies=[
'string',
]
)
Parameters
• AutoScalingGroupName (string) – [REQUIRED]
The name of the Auto Scaling group.
• LaunchConfigurationName (string) – The name of the launch configuration.
• MinSize (integer) – The minimum size of the Auto Scaling group.
• MaxSize (integer) – The maximum size of the Auto Scaling group.
• DesiredCapacity (integer) – The number of EC2 instances that should be run-
ning in the Auto Scaling group. This number must be greater than or equal to
the minimum size of the group and less than or equal to the maximum size of the
group.
• DefaultCooldown (integer) – The amount of time, in seconds, after a scaling ac-
tivity completes before another scaling activity can start. For more information,
see Understanding Auto Scaling Cooldowns .
• AvailabilityZones (list) – One or more Availability Zones for the group.
– (string) –
• HealthCheckType (string) – The type of health check for the instances in the
Auto Scaling group. The health check type can either be EC2 for Amazon EC2
or ELB for Elastic Load Balancing.
• HealthCheckGracePeriod (integer) – The amount of time, in seconds, that
Auto Scaling waits before checking the health status of an instance. The grace
period begins when the instance passes the system status and instance status
checks from Amazon EC2. For more information, see ‘ .
• PlacementGroup (string) – The name of the placement group into which you’ll
launch your instances, if any. For more information, see Placement Groups .
• VPCZoneIdentifier (string) – The ID of the subnet, if you are launching into a
VPC. You can specify several subnets in a comma-separated list.
When you specify VPCZoneIdentifier with AvailabilityZones ,
ensure that the subnets’ Availability Zones match the values you specify for
AvailabilityZones .
3.1. Services 97
Boto3 Documentation, Release 1.1.4
For more information, see Auto Scaling and Amazon Virtual Private Cloud in
the Auto Scaling Developer Guide .
• TerminationPolicies (list) – A standalone termination policy or a list of termi-
nation policies used to select the instance to terminate. The policies are executed
in the order that they are listed.
For more information, see Choosing a Termination Policy for Your Auto Scaling
Group in the Auto Scaling Developer Guide .
– (string) –
Returns None
Paginators
The available paginators are:
• AutoScaling.Paginator.DescribeAutoScalingGroups
• AutoScaling.Paginator.DescribeAutoScalingInstances
• AutoScaling.Paginator.DescribeLaunchConfigurations
• AutoScaling.Paginator.DescribeNotificationConfigurations
• AutoScaling.Paginator.DescribePolicies
• AutoScaling.Paginator.DescribeScalingActivities
• AutoScaling.Paginator.DescribeScheduledActions
• AutoScaling.Paginator.DescribeTags
class AutoScaling.Paginator.DescribeAutoScalingGroups
paginator = client.get_paginator('describe_auto_scaling_groups')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
AutoScaling.Client.describe_auto_scaling_groups().
Request Syntax
response_iterator = paginator.paginate(
AutoScalingGroupNames=[
'string',
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• AutoScalingGroupNames (list) – The group names.
– (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
98 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'AutoScalingGroups': [
{
'AutoScalingGroupName': 'string',
'AutoScalingGroupARN': 'string',
'LaunchConfigurationName': 'string',
'MinSize': 123,
'MaxSize': 123,
'DesiredCapacity': 123,
'DefaultCooldown': 123,
'AvailabilityZones': [
'string',
],
'LoadBalancerNames': [
'string',
],
'HealthCheckType': 'string',
'HealthCheckGracePeriod': 123,
'Instances': [
{
'InstanceId': 'string',
'AvailabilityZone': 'string',
'LifecycleState': 'Pending'|'Pending:Wait'|'Pending:Proceed'|'
'HealthStatus': 'string',
'LaunchConfigurationName': 'string'
},
],
'CreatedTime': datetime(2015, 1, 1),
'SuspendedProcesses': [
{
'ProcessName': 'string',
'SuspensionReason': 'string'
},
],
'PlacementGroup': 'string',
'VPCZoneIdentifier': 'string',
'EnabledMetrics': [
{
'Metric': 'string',
'Granularity': 'string'
},
],
3.1. Services 99
Boto3 Documentation, Release 1.1.4
'Status': 'string',
'Tags': [
{
'ResourceId': 'string',
'ResourceType': 'string',
'Key': 'string',
'Value': 'string',
'PropagateAtLaunch': True|False
},
],
'TerminationPolicies': [
'string',
]
},
],
Response Structure
• (dict) –
– AutoScalingGroups (list) –
The groups.
* (dict) –
Describes an Auto Scaling group.
· AutoScalingGroupName (string) –
The name of the group.
· AutoScalingGroupARN (string) –
The Amazon Resource Name (ARN) of the group.
· LaunchConfigurationName (string) –
The name of the associated launch configuration.
· MinSize (integer) –
The minimum size of the group.
· MaxSize (integer) –
The maximum size of the group.
· DesiredCapacity (integer) –
The desired size of the group.
· DefaultCooldown (integer) –
The number of seconds after a scaling activity completes be-
fore any further scaling activities can start.
· AvailabilityZones (list) –
One or more Availability Zones for the group.
· (string) –
· LoadBalancerNames (list) –
One or more load balancers associated with the group.
· (string) –
· HealthCheckType (string) –
The service of interest for the health status check, which can
be either EC2 for Amazon EC2 or ELB for Elastic Load Bal-
ancing.
100 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· HealthCheckGracePeriod (integer) –
The amount of time that Auto Scaling waits before checking
an instance’s health status. The grace period begins when an
instance comes into service.
· Instances (list) –
The EC2 instances associated with the group.
· (dict) –
Describes an EC2 instance.
· InstanceId (string) –
The ID of the instance.
· AvailabilityZone (string) –
The Availability Zone in which the instance is running.
· LifecycleState (string) –
A description of the current lifecycle state. Note that the
Quarantined state is not used.
· HealthStatus (string) –
The health status of the instance.
· LaunchConfigurationName (string) –
The launch configuration associated with the instance.
· CreatedTime (datetime) –
The date and time the group was created.
· SuspendedProcesses (list) –
The suspended processes associated with the group.
· (dict) –
Describes an Auto Scaling process that has been suspended.
For more information, see ProcessType .
· ProcessName (string) –
The name of the suspended process.
· SuspensionReason (string) –
The reason that the process was suspended.
· PlacementGroup (string) –
The name of the placement group into which you’ll launch
your instances, if any. For more information, see Placement
Groups .
· VPCZoneIdentifier (string) –
One or more subnet IDs, if applicable, separated by commas.
If you specify VPCZoneIdentifier and
AvailabilityZones , ensure that the Availability Zones
of the subnets match the values for AvailabilityZones
.
· EnabledMetrics (list) –
The metrics enabled for the group.
· (dict) –
Describes an enabled metric.
3.1. Services 101
Boto3 Documentation, Release 1.1.4
· Metric (string) –
The name of the metric.
· GroupMinSize
· GroupMaxSize
· GroupDesiredCapacity
· GroupInServiceInstances
· GroupPendingInstances
· GroupStandbyInstances
· GroupTerminatingInstances
· GroupTotalInstances
· Granularity (string) –
The granularity of the metric. The only valid value is
1Minute .
· Status (string) –
The current state of the group when DeleteAutoScalingGroup
is in progress.
· Tags (list) –
The tags for the group.
· (dict) –
Describes a tag for an Auto Scaling group.
· ResourceId (string) –
The name of the group.
· ResourceType (string) –
The type of resource. The only supported value is
auto-scaling-group .
· Key (string) –
The tag key.
· Value (string) –
The tag value.
· PropagateAtLaunch (boolean) –
Determines whether the tag is added to new instances as they
are launched in the group.
· TerminationPolicies (list) –
The termination policies for the group.
· (string) –
class AutoScaling.Paginator.DescribeAutoScalingInstances
paginator = client.get_paginator('describe_auto_scaling_instances')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
AutoScaling.Client.describe_auto_scaling_instances().
Request Syntax
response_iterator = paginator.paginate(
InstanceIds=[
102 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string',
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• InstanceIds (list) – One or more Auto Scaling instances to describe, up to 50
instances. If you omit this parameter, all Auto Scaling instances are described.
If you specify an ID that does not exist, it is ignored with no error.
– (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'AutoScalingInstances': [
{
'InstanceId': 'string',
'AutoScalingGroupName': 'string',
'AvailabilityZone': 'string',
'LifecycleState': 'string',
'HealthStatus': 'string',
'LaunchConfigurationName': 'string'
},
],
Response Structure
• (dict) –
– AutoScalingInstances (list) –
The instances.
* (dict) –
Describes an EC2 instance associated with an Auto Scaling group.
· InstanceId (string) –
The ID of the instance.
3.1. Services 103
Boto3 Documentation, Release 1.1.4
· AutoScalingGroupName (string) –
The name of the Auto Scaling group associated with the in-
stance.
· AvailabilityZone (string) –
The Availability Zone for the instance.
· LifecycleState (string) –
The lifecycle state for the instance. For more information, see
Auto Scaling Instance States in the Auto Scaling Developer
Guide .
· HealthStatus (string) –
The health status of this instance. “Healthy” means that the
instance is healthy and should remain in service. “Unhealthy”
means that the instance is unhealthy and Auto Scaling should
terminate and replace it.
· LaunchConfigurationName (string) –
The launch configuration associated with the instance.
class AutoScaling.Paginator.DescribeLaunchConfigurations
paginator = client.get_paginator('describe_launch_configurations')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
AutoScaling.Client.describe_launch_configurations().
Request Syntax
response_iterator = paginator.paginate(
LaunchConfigurationNames=[
'string',
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• LaunchConfigurationNames (list) – The launch configuration names.
– (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
104 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'LaunchConfigurations': [
{
'LaunchConfigurationName': 'string',
'LaunchConfigurationARN': 'string',
'ImageId': 'string',
'KeyName': 'string',
'SecurityGroups': [
'string',
],
'ClassicLinkVPCId': 'string',
'ClassicLinkVPCSecurityGroups': [
'string',
],
'UserData': 'string',
'InstanceType': 'string',
'KernelId': 'string',
'RamdiskId': 'string',
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'VolumeType': 'string',
'DeleteOnTermination': True|False,
'Iops': 123
},
'NoDevice': True|False
},
],
'InstanceMonitoring': {
'Enabled': True|False
},
'SpotPrice': 'string',
'IamInstanceProfile': 'string',
'CreatedTime': datetime(2015, 1, 1),
'EbsOptimized': True|False,
'AssociatePublicIpAddress': True|False,
'PlacementTenancy': 'string'
},
],
Response Structure
• (dict) –
– LaunchConfigurations (list) –
The launch configurations.
* (dict) –
3.1. Services 105
Boto3 Documentation, Release 1.1.4
Describes a launch configuration.
· LaunchConfigurationName (string) –
The name of the launch configuration.
· LaunchConfigurationARN (string) –
The Amazon Resource Name (ARN) of the launch configura-
tion.
· ImageId (string) –
The ID of the Amazon Machine Image (AMI).
· KeyName (string) –
The name of the key pair.
· SecurityGroups (list) –
The security groups to associate with the instances.
· (string) –
· ClassicLinkVPCId (string) –
The ID of a ClassicLink-enabled VPC to link your EC2-
Classic instances to. This parameter can only be used if you
are launching EC2-Classic instances. For more information,
see ClassicLink in the Amazon Elastic Compute Cloud User
Guide .
· ClassicLinkVPCSecurityGroups (list) –
The IDs of one or more security groups for the VPC speci-
fied in ClassicLinkVPCId . This parameter is required if
ClassicLinkVPCId is specified, and cannot be used oth-
erwise. For more information, see ClassicLink in the Amazon
Elastic Compute Cloud User Guide .
· (string) –
· UserData (string) –
The user data available to the instances.
· InstanceType (string) –
The instance type for the instances.
· KernelId (string) –
The ID of the kernel associated with the AMI.
· RamdiskId (string) –
The ID of the RAM disk associated with the AMI.
· BlockDeviceMappings (list) –
A block device mapping, which specifies the block devices
for the instance.
· (dict) –
Describes a block device mapping.
· VirtualName (string) –
The name of the virtual device, ephemeral0 to
ephemeral3 .
· DeviceName (string) –
The device name exposed to the EC2 instance (for example,
/dev/sdh or xvdh ).
106 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Ebs (dict) –
The information about the Amazon EBS volume.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The volume size, in gigabytes.
Valid values: If the volume type is io1 , the minimum size
of the volume is 10 GiB. If you specify SnapshotId and
VolumeSize , VolumeSize must be equal to or larger
than the size of the snapshot.
Default: If you create a volume from a snapshot and you don’t
specify a volume size, the default is the size of the snapshot.
Required: Required when the volume type is io1 .
· VolumeType (string) –
The volume type.
Valid values: standard | io1 | gp2
Default: standard
· DeleteOnTermination (boolean) –
Indicates whether to delete the volume on instance termina-
tion.
Default: true
· Iops (integer) –
For Provisioned IOPS (SSD) volumes only. The number of
I/O operations per second (IOPS) to provision for the volume.
Valid values: Range is 100 to 4000.
Default: None
· NoDevice (boolean) –
Suppresses a device mapping.
If this parameter is true for the root device, the instance might
fail the EC2 health check. Auto Scaling launches a replace-
ment instance if the instance fails the health check.
· InstanceMonitoring (dict) –
Controls whether instances in this group are launched with
detailed monitoring.
· Enabled (boolean) –
If True , instance monitoring is enabled.
· SpotPrice (string) –
The price to bid when launching Spot Instances.
· IamInstanceProfile (string) –
The name or Amazon Resource Name (ARN) of the instance
profile associated with the IAM role for the instance.
· CreatedTime (datetime) –
The creation date and time for the launch configuration.
3.1. Services 107
Boto3 Documentation, Release 1.1.4
· EbsOptimized (boolean) –
Controls whether the instance is optimized for EBS I/O
(true ) or not (false ).
· AssociatePublicIpAddress (boolean) –
Specifies whether the instances are associated with a public
IP address (true ) or not (false ).
· PlacementTenancy (string) –
The tenancy of the instance, either default or dedicated
. An instance with dedicated tenancy runs in an isolated,
single-tenant hardware and can only be launched into a VPC.
class AutoScaling.Paginator.DescribeNotificationConfigurations
paginator = client.get_paginator('describe_notification_configurations')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
AutoScaling.Client.describe_notification_configurations().
Request Syntax
response_iterator = paginator.paginate(
AutoScalingGroupNames=[
'string',
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• AutoScalingGroupNames (list) – The name of the group.
– (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
108 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'NotificationConfigurations': [
{
'AutoScalingGroupName': 'string',
'TopicARN': 'string',
'NotificationType': 'string'
},
],
Response Structure
• (dict) –
– NotificationConfigurations (list) –
The notification configurations.
* (dict) –
Describes a notification.
· AutoScalingGroupName (string) –
The name of the group.
· TopicARN (string) –
The Amazon Resource Name (ARN) of the Amazon Simple
Notification Service (SNS) topic.
· NotificationType (string) –
The types of events for an action to start.
· autoscaling:EC2_INSTANCE_LAUNCH
· autoscaling:EC2_INSTANCE_LAUNCH_ERROR
· autoscaling:EC2_INSTANCE_TERMINATE
· autoscaling:EC2_INSTANCE_TERMINATE_ERROR
· autoscaling:TEST_NOTIFICATION
class AutoScaling.Paginator.DescribePolicies
paginator = client.get_paginator('describe_policies')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
AutoScaling.Client.describe_policies().
Request Syntax
response_iterator = paginator.paginate(
AutoScalingGroupName='string',
PolicyNames=[
'string',
],
PolicyTypes=[
'string',
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
3.1. Services 109
Boto3 Documentation, Release 1.1.4
}
)
Parameters
• AutoScalingGroupName (string) – The name of the group.
• PolicyNames (list) – One or more policy names or policy ARNs to be described.
If you omit this list, all policy names are described. If an group name is provided,
the results are limited to that group. This list is limited to 50 items. If you specify
an unknown policy name, it is ignored with no error.
– (string) –
• PolicyTypes (list) – One or more policy types. Valid values are
SimpleScaling and StepScaling .
– (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'ScalingPolicies': [
{
'AutoScalingGroupName': 'string',
'PolicyName': 'string',
'PolicyARN': 'string',
'PolicyType': 'string',
'AdjustmentType': 'string',
'MinAdjustmentStep': 123,
'MinAdjustmentMagnitude': 123,
'ScalingAdjustment': 123,
'Cooldown': 123,
'StepAdjustments': [
{
'MetricIntervalLowerBound': 123.0,
'MetricIntervalUpperBound': 123.0,
'ScalingAdjustment': 123
},
],
'MetricAggregationType': 'string',
'EstimatedInstanceWarmup': 123,
'Alarms': [
{
'AlarmName': 'string',
'AlarmARN': 'string'
},
110 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
]
},
],
Response Structure
• (dict) –
– ScalingPolicies (list) –
The scaling policies.
* (dict) –
Describes a scaling policy.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group associated with this scal-
ing policy.
· PolicyName (string) –
The name of the scaling policy.
· PolicyARN (string) –
The Amazon Resource Name (ARN) of the policy.
· PolicyType (string) –
The policy type. Valid values are SimpleScaling and
StepScaling .
· AdjustmentType (string) –
The adjustment type, which specifies how
ScalingAdjustment is interpreted. Valid values
are ChangeInCapacity , ExactCapacity , and
PercentChangeInCapacity .
· MinAdjustmentStep (integer) –
Available for backward compatibility. Use
MinAdjustmentMagnitude instead.
· MinAdjustmentMagnitude (integer) –
The minimum number of instances to scale. If the value
of AdjustmentType is PercentChangeInCapacity
, the scaling policy changes the DesiredCapacity of the
Auto Scaling group by at least this many instances. Other-
wise, the error is ValidationError .
· ScalingAdjustment (integer) –
The amount by which to scale, based on the specified adjust-
ment type. A positive value adds to the current capacity while
a negative number removes from the current capacity.
· Cooldown (integer) –
The amount of time, in seconds, after a scaling activity com-
pletes before any further trigger-related scaling activities can
start.
· StepAdjustments (list) –
A set of adjustments that enable you to scale based on the size
of the alarm breach.
3.1. Services 111
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes an adjustment based on the difference between the
value of the aggregated CloudWatch metric and the breach
threshold that you’ve defined for the alarm.
For the following examples, suppose that you have an alarm
with a breach threshold of 50:
· If you want the adjustment to be triggered when the metric is
greater than or equal to 50 and less than 60, specify a lower
bound of 0 and an upper bound of 10.
· If you want the adjustment to be triggered when the metric is
greater than 40 and less than or equal to 50, specify a lower
bound of -10 and an upper bound of 0.
There are a few rules for the step adjustments for your step
policy:
· The ranges of your step adjustments can’t overlap or have a
gap.
· At most one step adjustment can have a null lower bound. If
one step adjustment has a negative lower bound, then there
must be a step adjustment with a null lower bound.
· At most one step adjustment can have a null upper bound. If
one step adjustment has a positive upper bound, then there
must be a step adjustment with a null upper bound.
· The upper and lower bound can’t be null in the same step
adjustment.
· MetricIntervalLowerBound (float) –
The lower bound for the difference between the alarm thresh-
old and the CloudWatch metric. If the metric value is above
the breach threshold, the lower bound is inclusive (the metric
must be greater than or equal to the threshold plus the lower
bound). Otherwise, it is exclusive (the metric must be greater
than the threshold plus the lower bound). A null value indi-
cates negative infinity.
· MetricIntervalUpperBound (float) –
The upper bound for the difference between the alarm thresh-
old and the CloudWatch metric. If the metric value is above
the breach threshold, the upper bound is exclusive (the metric
must be less than the threshold plus the upper bound). Oth-
erwise, it is inclusive (the metric must be less than or equal
to the threshold plus the upper bound). A null value indicates
positive infinity.
The upper bound must be greater than the lower bound.
· ScalingAdjustment (integer) –
The amount by which to scale, based on the specified adjust-
ment type. A positive value adds to the current capacity while
a negative number removes from the current capacity.
· MetricAggregationType (string) –
The aggregation type for the CloudWatch metrics. Valid val-
ues are Minimum , Maximum , and Average .
· EstimatedInstanceWarmup (integer) –
The estimated time, in seconds, until a newly launched in-
112 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
stance can contribute to the CloudWatch metrics.
· Alarms (list) –
The CloudWatch alarms related to the policy.
· (dict) –
Describes an alarm.
· AlarmName (string) –
The name of the alarm.
· AlarmARN (string) –
The Amazon Resource Name (ARN) of the alarm.
class AutoScaling.Paginator.DescribeScalingActivities
paginator = client.get_paginator('describe_scaling_activities')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
AutoScaling.Client.describe_scaling_activities().
Request Syntax
response_iterator = paginator.paginate(
ActivityIds=[
'string',
],
AutoScalingGroupName='string',
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• ActivityIds (list) – The activity IDs of the desired scaling activities. If this
list is omitted, all activities are described. If the AutoScalingGroupName
parameter is provided, the results are limited to that group. The list of requested
activities cannot contain more than 50 items. If unknown activities are requested,
they are ignored with no error.
– (string) –
• AutoScalingGroupName (string) – The name of the group.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
3.1. Services 113
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'Activities': [
{
'ActivityId': 'string',
'AutoScalingGroupName': 'string',
'Description': 'string',
'Cause': 'string',
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'StatusCode': 'WaitingForSpotInstanceRequestId'|'WaitingForSpotInstanc
'StatusMessage': 'string',
'Progress': 123,
'Details': 'string'
},
],
Response Structure
• (dict) –
– Activities (list) –
The scaling activities.
* (dict) –
Describes scaling activity, which is a long-running process that rep-
resents a change to your Auto Scaling group, such as changing its
size or replacing an instance.
· ActivityId (string) –
The ID of the activity.
· AutoScalingGroupName (string) –
The name of the Auto Scaling group.
· Description (string) –
A friendly, more verbose description of the activity.
· Cause (string) –
The reason the activity began.
· StartTime (datetime) –
The start time of the activity.
· EndTime (datetime) –
The end time of the activity.
· StatusCode (string) –
The current status of the activity.
· StatusMessage (string) –
A friendly, more verbose description of the activity status.
· Progress (integer) –
A value between 0 and 100 that indicates the progress of the
activity.
114 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Details (string) –
The details about the activity.
class AutoScaling.Paginator.DescribeScheduledActions
paginator = client.get_paginator('describe_scheduled_actions')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
AutoScaling.Client.describe_scheduled_actions().
Request Syntax
response_iterator = paginator.paginate(
AutoScalingGroupName='string',
ScheduledActionNames=[
'string',
],
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• AutoScalingGroupName (string) – The name of the group.
• ScheduledActionNames (list) – Describes one or more scheduled actions. If
you omit this list, the call describes all scheduled actions. If you specify an
unknown scheduled action it is ignored with no error.
You can describe up to a maximum of 50 instances with a single call. If there are
more items to return, the call returns a token. To get the next set of items, repeat
the call with the returned token in the NextToken parameter.
– (string) –
• StartTime (datetime) – The earliest scheduled start time to return. If scheduled
action names are provided, this parameter is ignored.
• EndTime (datetime) – The latest scheduled start time to return. If scheduled
action names are provided, this parameter is ignored.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
3.1. Services 115
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'ScheduledUpdateGroupActions': [
{
'AutoScalingGroupName': 'string',
'ScheduledActionName': 'string',
'ScheduledActionARN': 'string',
'Time': datetime(2015, 1, 1),
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'Recurrence': 'string',
'MinSize': 123,
'MaxSize': 123,
'DesiredCapacity': 123
},
],
Response Structure
• (dict) –
– ScheduledUpdateGroupActions (list) –
The scheduled actions.
* (dict) –
Describes a scheduled update to an Auto Scaling group.
· AutoScalingGroupName (string) –
The name of the group.
· ScheduledActionName (string) –
The name of the scheduled action.
· ScheduledActionARN (string) –
The Amazon Resource Name (ARN) of the scheduled action.
· Time (datetime) –
This parameter is deprecated; use StartTime instead.
· StartTime (datetime) –
The date and time that the action is scheduled to begin. This
date and time can be up to one month in the future.
When StartTime and EndTime are specified with
Recurrence , they form the boundaries of when the recur-
ring action will start and stop.
· EndTime (datetime) –
The date and time that the action is scheduled to end. This
date and time can be up to one month in the future.
· Recurrence (string) –
The recurring schedule for the action.
· MinSize (integer) –
The minimum size of the group.
116 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· MaxSize (integer) –
The maximum size of the group.
· DesiredCapacity (integer) –
The number of instances you prefer to maintain in the group.
class AutoScaling.Paginator.DescribeTags
paginator = client.get_paginator('describe_tags')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
AutoScaling.Client.describe_tags().
Request Syntax
response_iterator = paginator.paginate(
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• Filters (list) – A filter used to scope the tags to return.
– (dict) –
Describes a filter.
* Name (string) –
The name of the filter. The valid values are:
"auto-scaling-group" , "key" , "value" , and
"propagate-at-launch" .
* Values (list) –
The value of the filter.
· (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
3.1. Services 117
Boto3 Documentation, Release 1.1.4
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'Tags': [
{
'ResourceId': 'string',
'ResourceType': 'string',
'Key': 'string',
'Value': 'string',
'PropagateAtLaunch': True|False
},
],
Response Structure
• (dict) –
– Tags (list) –
The tags.
* (dict) –
Describes a tag for an Auto Scaling group.
· ResourceId (string) –
The name of the group.
· ResourceType (string) –
The type of resource. The only supported value is
auto-scaling-group .
· Key (string) –
The tag key.
· Value (string) –
The tag value.
· PropagateAtLaunch (boolean) –
Determines whether the tag is added to new instances as they
are launched in the group.
CloudFormation
118 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Table of Contents
• CloudFormation
– Client
– Paginators
– Service Resource
– Event
– Stack
– StackResource
– StackResourceSummary
Client
class CloudFormation.Client
A low-level client representing AWS CloudFormation:
import boto3
client = boto3.client('cloudformation')
These are the available methods:
•can_paginate()
•cancel_update_stack()
•create_stack()
•delete_stack()
•describe_stack_events()
•describe_stack_resource()
•describe_stack_resources()
•describe_stacks()
•estimate_template_cost()
•generate_presigned_url()
•get_paginator()
•get_stack_policy()
•get_template()
•get_template_summary()
•get_waiter()
•list_stack_resources()
•list_stacks()
•set_stack_policy()
•signal_resource()
•update_stack()
•validate_template()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
cancel_update_stack(**kwargs)
Cancels an update on the specified stack. If the call completes successfully, the stack will roll back the
3.1. Services 119
Boto3 Documentation, Release 1.1.4
update and revert to the previous stack configuration.
Note: Only stacks that are in the UPDATE_IN_PROGRESS state can be canceled.
Request Syntax
response = client.cancel_update_stack(
StackName='string'
)
Parameters StackName (string) – [REQUIRED]
The name or the unique stack ID that is associated with the stack.
Returns None
create_stack(**kwargs)
Creates a stack as specified in the template. After the call completes successfully, the stack creation starts.
You can check the status of the stack via the DescribeStacks API.
Request Syntax
response = client.create_stack(
StackName='string',
TemplateBody='string',
TemplateURL='string',
Parameters=[
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
DisableRollback=True|False,
TimeoutInMinutes=123,
NotificationARNs=[
'string',
],
Capabilities=[
'CAPABILITY_IAM',
],
OnFailure='DO_NOTHING'|'ROLLBACK'|'DELETE',
StackPolicyBody='string',
StackPolicyURL='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
Parameters
• StackName (string) – [REQUIRED]
The name that is associated with the stack. The name must be unique in the
region in which you are creating the stack.
Note: A stack name can contain only alphanumeric characters (case sensitive)
120 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
and hyphens. It must start with an alphabetic character and cannot be longer than
255 characters.
• TemplateBody (string) – Structure containing the template body with a mini-
mum length of 1 byte and a maximum length of 51,200 bytes. For more infor-
mation, go to Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify either the TemplateBody or the
TemplateURL parameter, but not both.
• TemplateURL (string) – Location of file containing the template body. The
URL must point to a template (max size: 460,800 bytes) located in an S3 bucket
in the same region as the stack. For more information, go to the Template
Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify either the TemplateBody or the
TemplateURL parameter, but not both.
• Parameters (list) – A list of Parameter structures that specify input parame-
ters for the stack.
– (dict) –
The Parameter data type.
* ParameterKey (string) –
The key associated with the parameter. If you don’t specify a key
and value for a particular parameter, AWS CloudFormation uses the
default value that is specified in your template.
* ParameterValue (string) –
The value associated with the parameter.
* UsePreviousValue (boolean) –
During a stack update, use the existing parameter value that the stack
is using for a given parameter key. If you specify true , do not
specify a parameter value.
• DisableRollback (boolean) – Set to true to disable rollback of the stack
if stack creation failed. You can specify either DisableRollback or
OnFailure , but not both.
Default: false
• TimeoutInMinutes (integer) – The amount of time that can pass before the stack
status becomes CREATE_FAILED; if DisableRollback is not set or is set
to false , the stack will be rolled back.
• NotificationARNs (list) – The Simple Notification Service (SNS) topic ARNs
to publish stack related events. You can find your SNS topic ARNs using the
SNS console or your Command Line Interface (CLI).
– (string) –
• Capabilities (list) – A list of capabilities that you must specify before AWS
CloudFormation can create or update certain stacks. Some stack templates might
include resources that can affect permissions in your AWS account. For those
stacks, you must explicitly acknowledge their capabilities by specifying this pa-
rameter.
Currently, the only valid value is CAPABILITY_IAM , which is required
for the following resources: AWS::IAM::AccessKey , AWS::IAM::Group
, AWS::IAM::InstanceProfile , AWS::IAM::Policy , AWS::IAM::Role ,
AWS::IAM::User , and AWS::IAM::UserToGroupAddition . If your stack tem-
plate contains these resources, we recommend that you review any permissions
associated with them. If you don’t specify this parameter, this action returns an
3.1. Services 121
Boto3 Documentation, Release 1.1.4
InsufficientCapabilities error.
– (string) –
• OnFailure (string) – Determines what action will be taken if stack creation fails.
This must be one of: DO_NOTHING, ROLLBACK, or DELETE. You can spec-
ify either OnFailure or DisableRollback , but not both.
Default: ROLLBACK
• StackPolicyBody (string) – Structure containing the stack policy body. For more
information, go to Prevent Updates to Stack Resources in the AWS CloudFor-
mation User Guide. You can specify either the StackPolicyBody or the
StackPolicyURL parameter, but not both.
• StackPolicyURL (string) – Location of a file containing the stack policy. The
URL must point to a policy (max size: 16KB) located in an S3 bucket in the
same region as the stack. You can specify either the StackPolicyBody or
the StackPolicyURL parameter, but not both.
• Tags (list) – A set of user-defined Tags to associate with this stack, represented
by key/value pairs. Tags defined for the stack are propagated to EC2 resources
that are created as part of the stack. A maximum number of 10 tags can be
specified.
– (dict) –
The Tag type is used by CreateStack in the Tags parameter. It allows
you to specify a key/value pair that can be used to store information related
to cost allocation for an AWS CloudFormation stack.
* Key (string) –
Required . A string used to identify this tag. You can specify a
maximum of 128 characters for a tag key. Tags owned by Amazon
Web Services (AWS) have the reserved prefix: aws: .
* Value (string) –
Required . A string containing the value for this tag. You can specify
a maximum of 256 characters for a tag value.
Return type dict
Returns
Response Syntax
{
'StackId': 'string'
}
Response Structure
• (dict) –
The output for a CreateStack action.
– StackId (string) –
Unique identifier of the stack.
delete_stack(**kwargs)
Deletes a specified stack. Once the call completes successfully, stack deletion starts. Deleted stacks do
not show up in the DescribeStacks API if the deletion has been completed successfully.
Request Syntax
response = client.delete_stack(
StackName='string'
)
122 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters StackName (string) – [REQUIRED]
The name or the unique stack ID that is associated with the stack.
Returns None
describe_stack_events(**kwargs)
Returns all stack related events for a specified stack. For more information about a stack’s event history,
go to Stacks in the AWS CloudFormation User Guide.
Note: You can list events for stacks that have failed to create or have been deleted by specifying the
unique stack identifier (stack ID).
Request Syntax
response = client.describe_stack_events(
StackName='string',
NextToken='string'
)
Parameters
• StackName (string) – The name or the unique stack ID that is associated with
the stack, which are not always interchangeable:
– Running stacks: You can specify either the stack’s name or its unique stack
ID.
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
• NextToken (string) – String that identifies the start of the next list of events, if
there is one.
Default: There is no default value.
Return type dict
Returns
Response Syntax
{
'StackEvents': [
{
'StackId': 'string',
'EventId': 'string',
'StackName': 'string',
'LogicalResourceId': 'string',
'PhysicalResourceId': 'string',
'ResourceType': 'string',
'Timestamp': datetime(2015, 1, 1),
'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLET
'ResourceStatusReason': 'string',
'ResourceProperties': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
The output for a DescribeStackEvents action.
3.1. Services 123
Boto3 Documentation, Release 1.1.4
– StackEvents (list) –
A list of StackEvents structures.
* (dict) –
The StackEvent data type.
· StackId (string) –
The unique ID name of the instance of the stack.
· EventId (string) –
The unique ID of this event.
· StackName (string) –
The name associated with a stack.
· LogicalResourceId (string) –
The logical name of the resource specified in the template.
· PhysicalResourceId (string) –
The name or unique identifier associated with the physical
instance of the resource.
· ResourceType (string) –
Type of resource. (For more information, go to AWS Re-
source Types Reference in the AWS CloudFormation User
Guide.)
· Timestamp (datetime) –
Time the status was updated.
· ResourceStatus (string) –
Current status of the resource.
· ResourceStatusReason (string) –
Success/failure message associated with the resource.
· ResourceProperties (string) –
BLOB of the properties used to create the resource.
– NextToken (string) –
String that identifies the start of the next list of events, if there is one.
describe_stack_resource(**kwargs)
Returns a description of the specified resource in the specified stack.
For deleted stacks, DescribeStackResource returns resource information for up to 90 days after the stack
has been deleted.
Request Syntax
response = client.describe_stack_resource(
StackName='string',
LogicalResourceId='string'
)
Parameters
• StackName (string) – [REQUIRED]
The name or the unique stack ID that is associated with the stack, which are not
always interchangeable:
– Running stacks: You can specify either the stack’s name or its unique stack
ID.
124 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
• LogicalResourceId (string) – [REQUIRED]
The logical name of the resource as specified in the template.
Default: There is no default value.
Return type dict
Returns
Response Syntax
{
'StackResourceDetail': {
'StackName': 'string',
'StackId': 'string',
'LogicalResourceId': 'string',
'PhysicalResourceId': 'string',
'ResourceType': 'string',
'LastUpdatedTimestamp': datetime(2015, 1, 1),
'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'
'ResourceStatusReason': 'string',
'Description': 'string',
'Metadata': 'string'
}
}
Response Structure
• (dict) –
The output for a DescribeStackResource action.
– StackResourceDetail (dict) –
A StackResourceDetail structure containing the description of the
specified resource in the specified stack.
* StackName (string) –
The name associated with the stack.
* StackId (string) –
Unique identifier of the stack.
* LogicalResourceId (string) –
The logical name of the resource specified in the template.
* PhysicalResourceId (string) –
The name or unique identifier that corresponds to a physical instance
ID of a resource supported by AWS CloudFormation.
* ResourceType (string) –
Type of resource. ((For more information, go to AWS Resource
Types Reference in the AWS CloudFormation User Guide.)
* LastUpdatedTimestamp (datetime) –
Time the status was updated.
* ResourceStatus (string) –
Current status of the resource.
* ResourceStatusReason (string) –
Success/failure message associated with the resource.
3.1. Services 125
Boto3 Documentation, Release 1.1.4
* Description (string) –
User defined description associated with the resource.
* Metadata (string) –
The JSON format content of the Metadata attribute declared for
the resource. For more information, see Metadata Attribute in the
AWS CloudFormation User Guide.
describe_stack_resources(**kwargs)
Returns AWS resource descriptions for running and deleted stacks. If StackName is specified, all the
associated resources that are part of the stack are returned. If PhysicalResourceId is specified, the
associated resources of the stack that the resource belongs to are returned.
Note: Only the first 100 resources will be returned. If your stack has more resources than this, you
should use ListStackResources instead.
For deleted stacks, DescribeStackResources returns resource information for up to 90 days after
the stack has been deleted.
You must specify either StackName or PhysicalResourceId , but not both. In addition, you can
specify LogicalResourceId to filter the returned result. For more information about resources, the
LogicalResourceId and PhysicalResourceId , go to the AWS CloudFormation User Guide .
Note: A ValidationError is returned if you specify both StackName and
PhysicalResourceId in the same request.
Request Syntax
response = client.describe_stack_resources(
StackName='string',
LogicalResourceId='string',
PhysicalResourceId='string'
)
Parameters
• StackName (string) – The name or the unique stack ID that is associated with
the stack, which are not always interchangeable:
– Running stacks: You can specify either the stack’s name or its unique stack
ID.
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
Required: Conditional. If you do not specify StackName , you must specify
PhysicalResourceId .
• LogicalResourceId (string) – The logical name of the resource as specified in
the template.
Default: There is no default value.
• PhysicalResourceId (string) – The name or unique identifier that corresponds
to a physical instance ID of a resource supported by AWS CloudFormation.
For example, for an Amazon Elastic Compute Cloud (EC2) instance,
PhysicalResourceId corresponds to the InstanceId . You can pass
the EC2 InstanceId to DescribeStackResources to find which stack
the instance belongs to and what other resources are part of the stack.
126 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Required: Conditional. If you do not specify PhysicalResourceId , you
must specify StackName .
Default: There is no default value.
Return type dict
Returns
Response Syntax
{
'StackResources': [
{
'StackName': 'string',
'StackId': 'string',
'LogicalResourceId': 'string',
'PhysicalResourceId': 'string',
'ResourceType': 'string',
'Timestamp': datetime(2015, 1, 1),
'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLET
'ResourceStatusReason': 'string',
'Description': 'string'
},
]
}
Response Structure
• (dict) –
The output for a DescribeStackResources action.
– StackResources (list) –
A list of StackResource structures.
* (dict) –
The StackResource data type.
· StackName (string) –
The name associated with the stack.
· StackId (string) –
Unique identifier of the stack.
· LogicalResourceId (string) –
The logical name of the resource specified in the template.
· PhysicalResourceId (string) –
The name or unique identifier that corresponds to a physical
instance ID of a resource supported by AWS CloudFormation.
· ResourceType (string) –
Type of resource. (For more information, go to AWS Re-
source Types Reference in the AWS CloudFormation User
Guide.)
· Timestamp (datetime) –
Time the status was updated.
· ResourceStatus (string) –
Current status of the resource.
· ResourceStatusReason (string) –
Success/failure message associated with the resource.
3.1. Services 127
Boto3 Documentation, Release 1.1.4
· Description (string) –
User defined description associated with the resource.
describe_stacks(**kwargs)
Returns the description for the specified stack; if no stack name was specified, then it returns the descrip-
tion for all the stacks created.
Request Syntax
response = client.describe_stacks(
StackName='string',
NextToken='string'
)
Parameters
• StackName (string) – The name or the unique stack ID that is associated with
the stack, which are not always interchangeable:
– Running stacks: You can specify either the stack’s name or its unique stack
ID.
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
• NextToken (string) – String that identifies the start of the next list of stacks, if
there is one.
Return type dict
Returns
Response Syntax
{
'Stacks': [
{
'StackId': 'string',
'StackName': 'string',
'Description': 'string',
'Parameters': [
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
'CreationTime': datetime(2015, 1, 1),
'LastUpdatedTime': datetime(2015, 1, 1),
'StackStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|
'StackStatusReason': 'string',
'DisableRollback': True|False,
'NotificationARNs': [
'string',
],
'TimeoutInMinutes': 123,
'Capabilities': [
'CAPABILITY_IAM',
],
'Outputs': [
{
'OutputKey': 'string',
'OutputValue': 'string',
128 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Description': 'string'
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
The output for a DescribeStacks action.
– Stacks (list) –
A list of stack structures.
* (dict) –
The Stack data type.
· StackId (string) –
Unique identifier of the stack.
· StackName (string) –
The name associated with the stack.
· Description (string) –
User defined description associated with the stack.
· Parameters (list) –
A list of Parameter structures.
· (dict) –
The Parameter data type.
· ParameterKey (string) –
The key associated with the parameter. If you don’t specify a
key and value for a particular parameter, AWS CloudForma-
tion uses the default value that is specified in your template.
· ParameterValue (string) –
The value associated with the parameter.
· UsePreviousValue (boolean) –
During a stack update, use the existing parameter value that
the stack is using for a given parameter key. If you specify
true , do not specify a parameter value.
· CreationTime (datetime) –
Time at which the stack was created.
· LastUpdatedTime (datetime) –
The time the stack was last updated. This field will only be
returned if the stack has been updated at least once.
· StackStatus (string) –
Current status of the stack.
3.1. Services 129
Boto3 Documentation, Release 1.1.4
· StackStatusReason (string) –
Success/failure message associated with the stack status.
· DisableRollback (boolean) –
Boolean to enable or disable rollback on stack creation fail-
ures:
· true : disable rollback
· false : enable rollback
· NotificationARNs (list) –
SNS topic ARNs to which stack related events are published.
· (string) –
· TimeoutInMinutes (integer) –
The amount of time within which stack creation should com-
plete.
· Capabilities (list) –
The capabilities allowed in the stack.
· (string) –
· Outputs (list) –
A list of output structures.
· (dict) –
The Output data type.
· OutputKey (string) –
The key associated with the output.
· OutputValue (string) –
The value associated with the output.
· Description (string) –
User defined description associated with the output.
· Tags (list) –
A list of Tag s that specify cost allocation information for the
stack.
· (dict) –
The Tag type is used by CreateStack in the Tags pa-
rameter. It allows you to specify a key/value pair that can
be used to store information related to cost allocation for an
AWS CloudFormation stack.
· Key (string) –
Required . A string used to identify this tag. You can specify
a maximum of 128 characters for a tag key. Tags owned by
Amazon Web Services (AWS) have the reserved prefix: aws:
.
· Value (string) –
Required . A string containing the value for this tag. You can
specify a maximum of 256 characters for a tag value.
– NextToken (string) – String that identifies the start of the next list of
stacks, if there is one.
estimate_template_cost(**kwargs)
Returns the estimated monthly cost of a template. The return value is an AWS Simple Monthly Calculator
130 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
URL with a query string that describes the resources required to run the template.
Request Syntax
response = client.estimate_template_cost(
TemplateBody='string',
TemplateURL='string',
Parameters=[
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
]
)
Parameters
• TemplateBody (string) – Structure containing the template body with a mini-
mum length of 1 byte and a maximum length of 51,200 bytes. (For more infor-
mation, go to Template Anatomy in the AWS CloudFormation User Guide.)
Conditional: You must pass TemplateBody or TemplateURL . If both are
passed, only TemplateBody is used.
• TemplateURL (string) – Location of file containing the template body. The
URL must point to a template located in an S3 bucket in the same region as the
stack. For more information, go to Template Anatomy in the AWS CloudForma-
tion User Guide.
Conditional: You must pass TemplateURL or TemplateBody . If both are
passed, only TemplateBody is used.
• Parameters (list) – A list of Parameter structures that specify input parame-
ters.
– (dict) –
The Parameter data type.
* ParameterKey (string) –
The key associated with the parameter. If you don’t specify a key
and value for a particular parameter, AWS CloudFormation uses the
default value that is specified in your template.
* ParameterValue (string) –
The value associated with the parameter.
* UsePreviousValue (boolean) –
During a stack update, use the existing parameter value that the stack
is using for a given parameter key. If you specify true , do not
specify a parameter value.
Return type dict
Returns
Response Syntax
{
'Url': 'string'
}
Response Structure
3.1. Services 131
Boto3 Documentation, Release 1.1.4
• (dict) –
The output for a EstimateTemplateCost action.
– Url (string) –
An AWS Simple Monthly Calculator URL with a query string that de-
scribes the resources required to run the template.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_stack_policy(**kwargs)
Returns the stack policy for a specified stack. If a stack doesn’t have a policy, a null value is returned.
Request Syntax
response = client.get_stack_policy(
StackName='string'
)
Parameters StackName (string) – [REQUIRED]
The name or unique stack ID that is associated with the stack whose policy you want
to get.
Return type dict
Returns
Response Syntax
{
'StackPolicyBody': 'string'
}
Response Structure
• (dict) –
The output for the GetStackPolicy action.
132 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– StackPolicyBody (string) –
Structure containing the stack policy body. (For more information, go to
Prevent Updates to Stack Resources in the AWS CloudFormation User
Guide.)
get_template(**kwargs)
Returns the template body for a specified stack. You can get the template for running or deleted stacks.
For deleted stacks, GetTemplate returns the template for up to 90 days after the stack has been deleted.
Note: If the template does not exist, a ValidationError is returned.
Request Syntax
response = client.get_template(
StackName='string'
)
Parameters StackName (string) – [REQUIRED]
The name or the unique stack ID that is associated with the stack, which are not always
interchangeable:
• Running stacks: You can specify either the stack’s name or its unique stack ID.
• Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
Return type dict
Returns
Response Syntax
{
'TemplateBody': 'string'
}
Response Structure
• (dict) –
The output for GetTemplate action.
– TemplateBody (string) –
Structure containing the template body. (For more information, go to Tem-
plate Anatomy in the AWS CloudFormation User Guide.)
get_template_summary(**kwargs)
Returns information about a new or existing template. The GetTemplateSummary action is useful for
viewing parameter information, such as default parameter values and parameter types, before you create
or update a stack.
You can use the GetTemplateSummary action when you submit a template, or you can get template
information for a running or deleted stack.
For deleted stacks, GetTemplateSummary returns the template information for up to 90 days after the
stack has been deleted. If the template does not exist, a ValidationError is returned.
Request Syntax
response = client.get_template_summary(
TemplateBody='string',
TemplateURL='string',
3.1. Services 133
Boto3 Documentation, Release 1.1.4
StackName='string'
)
Parameters
• TemplateBody (string) – Structure containing the template body with a mini-
mum length of 1 byte and a maximum length of 51,200 bytes. For more in-
formation about templates, see Template Anatomy in the AWS CloudFormation
User Guide.
Conditional: You must specify only one of the following parameters:
StackName , TemplateBody , or TemplateURL .
• TemplateURL (string) – Location of file containing the template body. The
URL must point to a template (max size: 460,800 bytes) located in an Amazon
S3 bucket. For more information about templates, see Template Anatomy in the
AWS CloudFormation User Guide.
Conditional: You must specify only one of the following parameters:
StackName , TemplateBody , or TemplateURL .
• StackName (string) – The name or the stack ID that is associated with the stack,
which are not always interchangeable. For running stacks, you can specify either
the stack’s name or its unique stack ID. For deleted stack, you must specify the
unique stack ID.
Conditional: You must specify only one of the following parameters:
StackName , TemplateBody , or TemplateURL .
Return type dict
Returns
Response Syntax
{
'Parameters': [
{
'ParameterKey': 'string',
'DefaultValue': 'string',
'ParameterType': 'string',
'NoEcho': True|False,
'Description': 'string',
'ParameterConstraints': {
'AllowedValues': [
'string',
]
}
},
],
'Description': 'string',
'Capabilities': [
'CAPABILITY_IAM',
],
'CapabilitiesReason': 'string',
'Version': 'string',
'Metadata': 'string'
}
Response Structure
• (dict) –
The output for the GetTemplateSummary action.
134 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– Parameters (list) –
A list of parameter declarations that describe various properties for each
parameter.
* (dict) –
The ParameterDeclaration data type.
· ParameterKey (string) –
The name that is associated with the parameter.
· DefaultValue (string) –
The default value of the parameter.
· ParameterType (string) –
The type of parameter.
· NoEcho (boolean) –
Flag that indicates whether the parameter value is shown as
plain text in logs and in the AWS Management Console.
· Description (string) –
The description that is associate with the parameter.
· ParameterConstraints (dict) –
The criteria that AWS CloudFormation uses to validate pa-
rameter values.
· AllowedValues (list) –
A list of values that are permitted for a parameter.
· (string) –
– Description (string) –
The value that is defined in the Description property of the template.
– Capabilities (list) –
The capabilities found within the template. Currently, AWS CloudForma-
tion supports only the CAPABILITY_IAM capability. If your template
contains IAM resources, you must specify the CAPABILITY_IAM value
for this parameter when you use the CreateStack or UpdateStack actions
with your template; otherwise, those actions return an InsufficientCapabil-
ities error.
* (string) –
– CapabilitiesReason (string) –
The list of resources that generated the values in the Capabilities
response element.
– Version (string) –
The AWS template format version, which identifies the capabilities of the
template.
– Metadata (string) –
The value that is defined for the Metadata property of the template.
get_waiter(waiter_name)
list_stack_resources(**kwargs)
Returns descriptions of all resources of the specified stack.
For deleted stacks, ListStackResources returns resource information for up to 90 days after the stack has
been deleted.
3.1. Services 135
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.list_stack_resources(
StackName='string',
NextToken='string'
)
Parameters
• StackName (string) – [REQUIRED]
The name or the unique stack ID that is associated with the stack, which are not
always interchangeable:
– Running stacks: You can specify either the stack’s name or its unique stack
ID.
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
• NextToken (string) – String that identifies the start of the next list of stack re-
source summaries, if there is one.
Default: There is no default value.
Return type dict
Returns
Response Syntax
{
'StackResourceSummaries': [
{
'LogicalResourceId': 'string',
'PhysicalResourceId': 'string',
'ResourceType': 'string',
'LastUpdatedTimestamp': datetime(2015, 1, 1),
'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLET
'ResourceStatusReason': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
The output for a ListStackResources action.
– StackResourceSummaries (list) –
A list of StackResourceSummary structures.
* (dict) –
Contains high-level information about the specified stack resource.
· LogicalResourceId (string) –
The logical name of the resource specified in the template.
· PhysicalResourceId (string) –
The name or unique identifier that corresponds to a physical
instance ID of the resource.
· ResourceType (string) –
136 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Type of resource. (For more information, go to AWS Re-
source Types Reference in the AWS CloudFormation User
Guide.)
· LastUpdatedTimestamp (datetime) –
Time the status was updated.
· ResourceStatus (string) –
Current status of the resource.
· ResourceStatusReason (string) –
Success/failure message associated with the resource.
– NextToken (string) –
String that identifies the start of the next list of stack resources, if there is
one.
list_stacks(**kwargs)
Returns the summary information for stacks whose status matches the specified StackStatusFilter. Sum-
mary information for stacks that have been deleted is kept for 90 days after the stack is deleted. If no
StackStatusFilter is specified, summary information for all stacks is returned (including existing stacks
and stacks that have been deleted).
Request Syntax
response = client.list_stacks(
NextToken='string',
StackStatusFilter=[
'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'ROLLBACK_IN_PROGRESS'|'ROLLB
]
)
Parameters
• NextToken (string) – String that identifies the start of the next list of stacks, if
there is one.
Default: There is no default value.
• StackStatusFilter (list) – Stack status to use as a filter. Specify one or more
stack status codes to list only stacks with the specified status codes. For a com-
plete list of stack status codes, see the StackStatus parameter of the Stack
data type.
– (string) –
Return type dict
Returns
Response Syntax
{
'StackSummaries': [
{
'StackId': 'string',
'StackName': 'string',
'TemplateDescription': 'string',
'CreationTime': datetime(2015, 1, 1),
'LastUpdatedTime': datetime(2015, 1, 1),
'DeletionTime': datetime(2015, 1, 1),
'StackStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|
'StackStatusReason': 'string'
},
3.1. Services 137
Boto3 Documentation, Release 1.1.4
],
'NextToken': 'string'
}
Response Structure
• (dict) –
The output for ListStacks action.
– StackSummaries (list) –
A list of StackSummary structures containing information about the
specified stacks.
* (dict) –
The StackSummary Data Type
· StackId (string) –
Unique stack identifier.
· StackName (string) –
The name associated with the stack.
· TemplateDescription (string) –
The template description of the template used to create the
stack.
· CreationTime (datetime) –
The time the stack was created.
· LastUpdatedTime (datetime) –
The time the stack was last updated. This field will only be
returned if the stack has been updated at least once.
· DeletionTime (datetime) –
The time the stack was deleted.
· StackStatus (string) –
The current status of the stack.
· StackStatusReason (string) –
Success/Failure message associated with the stack status.
– NextToken (string) –
String that identifies the start of the next list of stacks, if there is one.
set_stack_policy(**kwargs)
Sets a stack policy for a specified stack.
Request Syntax
response = client.set_stack_policy(
StackName='string',
StackPolicyBody='string',
StackPolicyURL='string'
)
Parameters
• StackName (string) – [REQUIRED]
The name or unique stack ID that you want to associate a policy with.
138 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• StackPolicyBody (string) – Structure containing the stack policy body. For more
information, go to Prevent Updates to Stack Resources in the AWS CloudFor-
mation User Guide. You can specify either the StackPolicyBody or the
StackPolicyURL parameter, but not both.
• StackPolicyURL (string) – Location of a file containing the stack policy. The
URL must point to a policy (max size: 16KB) located in an S3 bucket in the
same region as the stack. You can specify either the StackPolicyBody or
the StackPolicyURL parameter, but not both.
Returns None
signal_resource(**kwargs)
Sends a signal to the specified resource with a success or failure status. You can use the SignalResource
API in conjunction with a creation policy or update policy. AWS CloudFormation doesn’t proceed with
a stack creation or update until resources receive the required number of signals or the timeout period
is exceeded. The SignalResource API is useful in cases where you want to send signals from anywhere
other than an Amazon EC2 instance.
Request Syntax
response = client.signal_resource(
StackName='string',
LogicalResourceId='string',
UniqueId='string',
Status='SUCCESS'|'FAILURE'
)
Parameters
• StackName (string) – [REQUIRED]
The stack name or unique stack ID that includes the resource that you want to
signal.
• LogicalResourceId (string) – [REQUIRED]
The logical ID of the resource that you want to signal. The logical ID is the name
of the resource that given in the template.
• UniqueId (string) – [REQUIRED]
A unique ID of the signal. When you signal Amazon EC2 instances or Auto
Scaling groups, specify the instance ID that you are signaling as the unique ID.
If you send multiple signals to a single resource (such as signaling a wait condi-
tion), each signal requires a different unique ID.
• Status (string) – [REQUIRED]
The status of the signal, which is either success or failure. A failure signal causes
AWS CloudFormation to immediately fail the stack creation or update.
Returns None
update_stack(**kwargs)
Updates a stack as specified in the template. After the call completes successfully, the stack update starts.
You can check the status of the stack via the DescribeStacks action.
To get a copy of the template for an existing stack, you can use the GetTemplate action.
Tags that were associated with this stack during creation time will still be associated with the stack after
an UpdateStack operation.
For more information about creating an update template, updating a stack, and monitoring the progress of
the update, see Updating a Stack .
Request Syntax
3.1. Services 139
Boto3 Documentation, Release 1.1.4
response = client.update_stack(
StackName='string',
TemplateBody='string',
TemplateURL='string',
UsePreviousTemplate=True|False,
StackPolicyDuringUpdateBody='string',
StackPolicyDuringUpdateURL='string',
Parameters=[
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
Capabilities=[
'CAPABILITY_IAM',
],
StackPolicyBody='string',
StackPolicyURL='string',
NotificationARNs=[
'string',
]
)
Parameters
• StackName (string) – [REQUIRED]
The name or unique stack ID of the stack to update.
• TemplateBody (string) – Structure containing the template body with a mini-
mum length of 1 byte and a maximum length of 51,200 bytes. (For more infor-
mation, go to Template Anatomy in the AWS CloudFormation User Guide.)
Conditional: You must specify either the TemplateBody or the
TemplateURL parameter, but not both.
• TemplateURL (string) – Location of file containing the template body. The
URL must point to a template located in an S3 bucket in the same region as the
stack. For more information, go to Template Anatomy in the AWS CloudForma-
tion User Guide.
Conditional: You must specify either the TemplateBody or the
TemplateURL parameter, but not both.
• UsePreviousTemplate (boolean) – Reuse the existing template that is associated
with the stack that you are updating.
• StackPolicyDuringUpdateBody (string) – Structure containing
the temporary overriding stack policy body. You can spec-
ify either the StackPolicyDuringUpdateBody or the
StackPolicyDuringUpdateURL parameter, but not both.
If you want to update protected resources, specify a temporary overriding stack
policy during this update. If you do not specify a stack policy, the current policy
that is associated with the stack will be used.
• StackPolicyDuringUpdateURL (string) – Location of a file containing the
temporary overriding stack policy. The URL must point to a policy (max
size: 16KB) located in an S3 bucket in the same region as the stack.
You can specify either the StackPolicyDuringUpdateBody or the
StackPolicyDuringUpdateURL parameter, but not both.
If you want to update protected resources, specify a temporary overriding stack
140 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
policy during this update. If you do not specify a stack policy, the current policy
that is associated with the stack will be used.
• Parameters (list) – A list of Parameter structures that specify input parame-
ters for the stack. For more information, see the Parameter data type.
– (dict) –
The Parameter data type.
* ParameterKey (string) –
The key associated with the parameter. If you don’t specify a key
and value for a particular parameter, AWS CloudFormation uses the
default value that is specified in your template.
* ParameterValue (string) –
The value associated with the parameter.
* UsePreviousValue (boolean) –
During a stack update, use the existing parameter value that the stack
is using for a given parameter key. If you specify true , do not
specify a parameter value.
• Capabilities (list) – A list of capabilities that you must specify before AWS
CloudFormation can create or update certain stacks. Some stack templates
might include resources that can affect permissions in your AWS account.
For those stacks, you must explicitly acknowledge their capabilities by spec-
ifying this parameter. Currently, the only valid value is CAPABILITY_IAM
, which is required for the following resources: AWS::IAM::AccessKey
, AWS::IAM::Group , AWS::IAM::InstanceProfile , AWS::IAM::Policy ,
AWS::IAM::Role , AWS::IAM::User , and AWS::IAM::UserToGroupAddition .
If your stack template contains these resources, we recommend that you review
any permissions associated with them. If you don’t specify this parameter, this
action returns an InsufficientCapabilities error.
– (string) –
• StackPolicyBody (string) – Structure containing a new stack policy body. You
can specify either the StackPolicyBody or the StackPolicyURL param-
eter, but not both.
You might update the stack policy, for example, in order to protect a new resource
that you created during a stack update. If you do not specify a stack policy, the
current policy that is associated with the stack is unchanged.
• StackPolicyURL (string) – Location of a file containing the updated stack pol-
icy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in
the same region as the stack. You can specify either the StackPolicyBody
or the StackPolicyURL parameter, but not both.
You might update the stack policy, for example, in order to protect a new resource
that you created during a stack update. If you do not specify a stack policy, the
current policy that is associated with the stack is unchanged.
• NotificationARNs (list) – Update the ARNs for the Amazon SNS topics that are
associated with the stack.
– (string) –
Return type dict
Returns
Response Syntax
{
'StackId': 'string'
3.1. Services 141
Boto3 Documentation, Release 1.1.4
Response Structure
• (dict) –
The output for a UpdateStack action.
– StackId (string) –
Unique identifier of the stack.
validate_template(**kwargs)
Validates a specified template.
Request Syntax
response = client.validate_template(
TemplateBody='string',
TemplateURL='string'
)
Parameters
• TemplateBody (string) – Structure containing the template body with a mini-
mum length of 1 byte and a maximum length of 51,200 bytes. For more infor-
mation, go to Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must pass TemplateURL or TemplateBody . If both are
passed, only TemplateBody is used.
• TemplateURL (string) – Location of file containing the template body. The
URL must point to a template (max size: 460,800 bytes) located in an S3 bucket
in the same region as the stack. For more information, go to Template Anatomy
in the AWS CloudFormation User Guide.
Conditional: You must pass TemplateURL or TemplateBody . If both are
passed, only TemplateBody is used.
Return type dict
Returns
Response Syntax
{
'Parameters': [
{
'ParameterKey': 'string',
'DefaultValue': 'string',
'NoEcho': True|False,
'Description': 'string'
},
],
'Description': 'string',
'Capabilities': [
'CAPABILITY_IAM',
],
'CapabilitiesReason': 'string'
}
Response Structure
• (dict) –
The output for ValidateTemplate action.
142 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– Parameters (list) –
A list of TemplateParameter structures.
* (dict) –
The TemplateParameter data type.
· ParameterKey (string) –
The name associated with the parameter.
· DefaultValue (string) –
The default value associated with the parameter.
· NoEcho (boolean) –
Flag indicating whether the parameter should be displayed as
plain text in logs and UIs.
· Description (string) –
User defined description associated with the parameter.
– Description (string) –
The description found within the template.
– Capabilities (list) –
The capabilities found within the template. Currently, AWS CloudForma-
tion supports only the CAPABILITY_IAM capability. If your template
contains IAM resources, you must specify the CAPABILITY_IAM value
for this parameter when you use the CreateStack or UpdateStack actions
with your template; otherwise, those actions return an InsufficientCapabil-
ities error.
* (string) –
– CapabilitiesReason (string) –
The list of resources that generated the values in the Capabilities
response element.
Paginators
The available paginators are:
• CloudFormation.Paginator.DescribeStackEvents
• CloudFormation.Paginator.DescribeStacks
• CloudFormation.Paginator.ListStackResources
• CloudFormation.Paginator.ListStacks
class CloudFormation.Paginator.DescribeStackEvents
paginator = client.get_paginator('describe_stack_events')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudFormation.Client.describe_stack_events().
Request Syntax
3.1. Services 143
Boto3 Documentation, Release 1.1.4
response_iterator = paginator.paginate(
StackName='string',
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• StackName (string) – The name or the unique stack ID that is associated with
the stack, which are not always interchangeable:
– Running stacks: You can specify either the stack’s name or its unique stack
ID.
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'StackEvents': [
{
'StackId': 'string',
'EventId': 'string',
'StackName': 'string',
'LogicalResourceId': 'string',
'PhysicalResourceId': 'string',
'ResourceType': 'string',
'Timestamp': datetime(2015, 1, 1),
'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLET
'ResourceStatusReason': 'string',
'ResourceProperties': 'string'
},
],
Response Structure
• (dict) –
The output for a DescribeStackEvents action.
– StackEvents (list) –
144 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A list of StackEvents structures.
* (dict) –
The StackEvent data type.
· StackId (string) –
The unique ID name of the instance of the stack.
· EventId (string) –
The unique ID of this event.
· StackName (string) –
The name associated with a stack.
· LogicalResourceId (string) –
The logical name of the resource specified in the template.
· PhysicalResourceId (string) –
The name or unique identifier associated with the physical
instance of the resource.
· ResourceType (string) –
Type of resource. (For more information, go to AWS Re-
source Types Reference in the AWS CloudFormation User
Guide.)
· Timestamp (datetime) –
Time the status was updated.
· ResourceStatus (string) –
Current status of the resource.
· ResourceStatusReason (string) –
Success/failure message associated with the resource.
· ResourceProperties (string) –
BLOB of the properties used to create the resource.
class CloudFormation.Paginator.DescribeStacks
paginator = client.get_paginator('describe_stacks')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudFormation.Client.describe_stacks().
Request Syntax
response_iterator = paginator.paginate(
StackName='string',
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• StackName (string) – The name or the unique stack ID that is associated with
the stack, which are not always interchangeable:
3.1. Services 145
Boto3 Documentation, Release 1.1.4
– Running stacks: You can specify either the stack’s name or its unique stack
ID.
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'Stacks': [
{
'StackId': 'string',
'StackName': 'string',
'Description': 'string',
'Parameters': [
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
'CreationTime': datetime(2015, 1, 1),
'LastUpdatedTime': datetime(2015, 1, 1),
'StackStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|
'StackStatusReason': 'string',
'DisableRollback': True|False,
'NotificationARNs': [
'string',
],
'TimeoutInMinutes': 123,
'Capabilities': [
'CAPABILITY_IAM',
],
'Outputs': [
{
'OutputKey': 'string',
'OutputValue': 'string',
'Description': 'string'
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
146 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
]
},
],
Response Structure
• (dict) –
The output for a DescribeStacks action.
– Stacks (list) –
A list of stack structures.
* (dict) –
The Stack data type.
· StackId (string) –
Unique identifier of the stack.
· StackName (string) –
The name associated with the stack.
· Description (string) –
User defined description associated with the stack.
· Parameters (list) –
A list of Parameter structures.
· (dict) –
The Parameter data type.
· ParameterKey (string) –
The key associated with the parameter. If you don’t specify a
key and value for a particular parameter, AWS CloudForma-
tion uses the default value that is specified in your template.
· ParameterValue (string) –
The value associated with the parameter.
· UsePreviousValue (boolean) –
During a stack update, use the existing parameter value that
the stack is using for a given parameter key. If you specify
true , do not specify a parameter value.
· CreationTime (datetime) –
Time at which the stack was created.
· LastUpdatedTime (datetime) –
The time the stack was last updated. This field will only be
returned if the stack has been updated at least once.
· StackStatus (string) –
Current status of the stack.
· StackStatusReason (string) –
Success/failure message associated with the stack status.
· DisableRollback (boolean) –
Boolean to enable or disable rollback on stack creation fail-
ures:
3.1. Services 147
Boto3 Documentation, Release 1.1.4
· true : disable rollback
· false : enable rollback
· NotificationARNs (list) –
SNS topic ARNs to which stack related events are published.
· (string) –
· TimeoutInMinutes (integer) –
The amount of time within which stack creation should com-
plete.
· Capabilities (list) –
The capabilities allowed in the stack.
· (string) –
· Outputs (list) –
A list of output structures.
· (dict) –
The Output data type.
· OutputKey (string) –
The key associated with the output.
· OutputValue (string) –
The value associated with the output.
· Description (string) –
User defined description associated with the output.
· Tags (list) –
A list of Tag s that specify cost allocation information for the
stack.
· (dict) –
The Tag type is used by CreateStack in the Tags pa-
rameter. It allows you to specify a key/value pair that can
be used to store information related to cost allocation for an
AWS CloudFormation stack.
· Key (string) –
Required . A string used to identify this tag. You can specify
a maximum of 128 characters for a tag key. Tags owned by
Amazon Web Services (AWS) have the reserved prefix: aws:
.
· Value (string) –
Required . A string containing the value for this tag. You can
specify a maximum of 256 characters for a tag value.
class CloudFormation.Paginator.ListStackResources
paginator = client.get_paginator('list_stack_resources')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudFormation.Client.list_stack_resources().
Request Syntax
148 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response_iterator = paginator.paginate(
StackName='string',
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• StackName (string) – [REQUIRED]
The name or the unique stack ID that is associated with the stack, which are not
always interchangeable:
– Running stacks: You can specify either the stack’s name or its unique stack
ID.
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'StackResourceSummaries': [
{
'LogicalResourceId': 'string',
'PhysicalResourceId': 'string',
'ResourceType': 'string',
'LastUpdatedTimestamp': datetime(2015, 1, 1),
'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLET
'ResourceStatusReason': 'string'
},
],
Response Structure
• (dict) –
The output for a ListStackResources action.
– StackResourceSummaries (list) –
A list of StackResourceSummary structures.
3.1. Services 149
Boto3 Documentation, Release 1.1.4
* (dict) –
Contains high-level information about the specified stack resource.
· LogicalResourceId (string) –
The logical name of the resource specified in the template.
· PhysicalResourceId (string) –
The name or unique identifier that corresponds to a physical
instance ID of the resource.
· ResourceType (string) –
Type of resource. (For more information, go to AWS Re-
source Types Reference in the AWS CloudFormation User
Guide.)
· LastUpdatedTimestamp (datetime) –
Time the status was updated.
· ResourceStatus (string) –
Current status of the resource.
· ResourceStatusReason (string) –
Success/failure message associated with the resource.
class CloudFormation.Paginator.ListStacks
paginator = client.get_paginator('list_stacks')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudFormation.Client.list_stacks().
Request Syntax
response_iterator = paginator.paginate(
StackStatusFilter=[
'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'ROLLBACK_IN_PROGRESS'|'ROLLB
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• StackStatusFilter (list) – Stack status to use as a filter. Specify one or more
stack status codes to list only stacks with the specified status codes. For a com-
plete list of stack status codes, see the StackStatus parameter of the Stack
data type.
– (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
150 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'StackSummaries': [
{
'StackId': 'string',
'StackName': 'string',
'TemplateDescription': 'string',
'CreationTime': datetime(2015, 1, 1),
'LastUpdatedTime': datetime(2015, 1, 1),
'DeletionTime': datetime(2015, 1, 1),
'StackStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|
'StackStatusReason': 'string'
},
],
Response Structure
• (dict) –
The output for ListStacks action.
– StackSummaries (list) –
A list of StackSummary structures containing information about the
specified stacks.
* (dict) –
The StackSummary Data Type
· StackId (string) –
Unique stack identifier.
· StackName (string) –
The name associated with the stack.
· TemplateDescription (string) –
The template description of the template used to create the
stack.
· CreationTime (datetime) –
The time the stack was created.
· LastUpdatedTime (datetime) –
The time the stack was last updated. This field will only be
returned if the stack has been updated at least once.
· DeletionTime (datetime) –
The time the stack was deleted.
· StackStatus (string) –
The current status of the stack.
3.1. Services 151
Boto3 Documentation, Release 1.1.4
· StackStatusReason (string) –
Success/Failure message associated with the stack status.
Service Resource
class CloudFormation.ServiceResource
A resource representing AWS CloudFormation:
import boto3
cloudformation = boto3.resource('cloudformation')
These are the resource’s available actions:
•create_stack()
These are the resource’s available sub-resources:
•Event()
•Stack()
•StackResource()
•StackResourceSummary()
These are the resource’s available collections:
•stacks
Actions
Actions call operations on resources. They may automatically handle the passing in of arguments set from
identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.
create_stack(**kwargs)
Creates a stack as specified in the template. After the call completes successfully, the stack creation starts.
You can check the status of the stack via the DescribeStacks API.
Request Syntax
stack = cloudformation.create_stack(
StackName='string',
TemplateBody='string',
TemplateURL='string',
Parameters=[
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
DisableRollback=True|False,
TimeoutInMinutes=123,
NotificationARNs=[
'string',
],
Capabilities=[
'CAPABILITY_IAM',
],
OnFailure='DO_NOTHING'|'ROLLBACK'|'DELETE',
StackPolicyBody='string',
StackPolicyURL='string',
Tags=[
{
152 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Key': 'string',
'Value': 'string'
},
]
)
Parameters
• StackName (string) – [REQUIRED]
The name that is associated with the stack. The name must be unique in the
region in which you are creating the stack.
Note: A stack name can contain only alphanumeric characters (case sensitive)
and hyphens. It must start with an alphabetic character and cannot be longer than
255 characters.
• TemplateBody (string) – Structure containing the template body with a mini-
mum length of 1 byte and a maximum length of 51,200 bytes. For more infor-
mation, go to Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify either the TemplateBody or the
TemplateURL parameter, but not both.
• TemplateURL (string) – Location of file containing the template body. The
URL must point to a template (max size: 460,800 bytes) located in an S3 bucket
in the same region as the stack. For more information, go to the Template
Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify either the TemplateBody or the
TemplateURL parameter, but not both.
• Parameters (list) – A list of Parameter structures that specify input parame-
ters for the stack.
– (dict) –
The Parameter data type.
* ParameterKey (string) –
The key associated with the parameter. If you don’t specify a key
and value for a particular parameter, AWS CloudFormation uses the
default value that is specified in your template.
* ParameterValue (string) –
The value associated with the parameter.
* UsePreviousValue (boolean) –
During a stack update, use the existing parameter value that the stack
is using for a given parameter key. If you specify true , do not
specify a parameter value.
• DisableRollback (boolean) – Set to true to disable rollback of the stack
if stack creation failed. You can specify either DisableRollback or
OnFailure , but not both.
Default: false
• TimeoutInMinutes (integer) – The amount of time that can pass before the stack
status becomes CREATE_FAILED; if DisableRollback is not set or is set
to false , the stack will be rolled back.
• NotificationARNs (list) – The Simple Notification Service (SNS) topic ARNs
to publish stack related events. You can find your SNS topic ARNs using the
SNS console or your Command Line Interface (CLI).
3.1. Services 153
Boto3 Documentation, Release 1.1.4
– (string) –
• Capabilities (list) – A list of capabilities that you must specify before AWS
CloudFormation can create or update certain stacks. Some stack templates might
include resources that can affect permissions in your AWS account. For those
stacks, you must explicitly acknowledge their capabilities by specifying this pa-
rameter.
Currently, the only valid value is CAPABILITY_IAM , which is required
for the following resources: AWS::IAM::AccessKey , AWS::IAM::Group
, AWS::IAM::InstanceProfile , AWS::IAM::Policy , AWS::IAM::Role ,
AWS::IAM::User , and AWS::IAM::UserToGroupAddition . If your stack tem-
plate contains these resources, we recommend that you review any permissions
associated with them. If you don’t specify this parameter, this action returns an
InsufficientCapabilities error.
– (string) –
• OnFailure (string) – Determines what action will be taken if stack creation fails.
This must be one of: DO_NOTHING, ROLLBACK, or DELETE. You can spec-
ify either OnFailure or DisableRollback , but not both.
Default: ROLLBACK
• StackPolicyBody (string) – Structure containing the stack policy body. For more
information, go to Prevent Updates to Stack Resources in the AWS CloudFor-
mation User Guide. You can specify either the StackPolicyBody or the
StackPolicyURL parameter, but not both.
• StackPolicyURL (string) – Location of a file containing the stack policy. The
URL must point to a policy (max size: 16KB) located in an S3 bucket in the
same region as the stack. You can specify either the StackPolicyBody or
the StackPolicyURL parameter, but not both.
• Tags (list) – A set of user-defined Tags to associate with this stack, represented
by key/value pairs. Tags defined for the stack are propagated to EC2 resources
that are created as part of the stack. A maximum number of 10 tags can be
specified.
– (dict) –
The Tag type is used by CreateStack in the Tags parameter. It allows
you to specify a key/value pair that can be used to store information related
to cost allocation for an AWS CloudFormation stack.
* Key (string) –
Required . A string used to identify this tag. You can specify a
maximum of 128 characters for a tag key. Tags owned by Amazon
Web Services (AWS) have the reserved prefix: aws: .
* Value (string) –
Required . A string containing the value for this tag. You can specify
a maximum of 256 characters for a tag value.
Return type cloudformation.Stack
Returns Stack resource
Sub-resources
Sub-resources are methods that create a new instance of a child resource. This resource’s identifiers get passed
along to the child. For more information about sub-resources refer to the Resources Introduction Guide.
Event(id)
Creates a Event resource.:
154 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
event = cloudformation.Event('id')
Parameters id (string) – The Event’s id identifier. This must be set.
Return type CloudFormation.Event
Returns A Event resource
Stack(name)
Creates a Stack resource.:
stack = cloudformation.Stack('name')
Parameters name (string) – The Stack’s name identifier. This must be set.
Return type CloudFormation.Stack
Returns A Stack resource
StackResource(stack_name, logical_id)
Creates a StackResource resource.:
stack_resource = cloudformation.StackResource('stack_name','logical_id')
Parameters
• stack_name (string) – The StackResource’s stack_name identifier. This must
be set.
• logical_id (string) – The StackResource’s logical_id identifier. This must be set.
Return type CloudFormation.StackResource
Returns A StackResource resource
StackResourceSummary(stack_name, logical_id)
Creates a StackResourceSummary resource.:
stack_resource_summary = cloudformation.StackResourceSummary('stack_name','logical_id')
Parameters
• stack_name (string) – The StackResourceSummary’s stack_name identifier.
This must be set.
• logical_id (string) – The StackResourceSummary’s logical_id identifier. This
must be set.
Return type CloudFormation.StackResourceSummary
Returns A StackResourceSummary resource
Collections
Collections provide an interface to iterate over and manipulate groups of resources. For more information about
collections refer to the Resources Introduction Guide.
stacks
all()
Creates an iterable of all Stack resources in the collection.
Request Syntax
stack_iterator = cloudformation.stacks.all()
Return type list(cloudformation.Stack)
Returns A list of Stack resources
3.1. Services 155
Boto3 Documentation, Release 1.1.4
filter(**kwargs)
Creates an iterable of all Stack resources in the collection filtered by kwargs passed to method.
Request Syntax
stack_iterator = cloudformation.stacks.filter(
StackName='string',
NextToken='string'
)
Parameters
• StackName (string) – The name or the unique stack ID that is associated
with the stack, which are not always interchangeable:
– Running stacks: You can specify either the stack’s name or its
unique stack ID.
– Deleted stacks: You must specify the unique stack ID.
Default: There is no default value.
• NextToken (string) – String that identifies the start of the next list of
stacks, if there is one.
Return type list(cloudformation.Stack)
Returns A list of Stack resources
limit(**kwargs)
Creates an iterable up to a specified amount of Stack resources in the collection.
Request Syntax
stack_iterator = cloudformation.stacks.limit(
count=123
)
Parameters count (integer) – The limit to the number of resources in the iterable.
Return type list(cloudformation.Stack)
Returns A list of Stack resources
page_size(**kwargs)
Creates an iterable of all Stack resources in the collection, but limits the number of items returned
by each service call by the specified amount.
Request Syntax
stack_iterator = cloudformation.stacks.page_size(
count=123
)
Parameters count (integer) – The number of items returned by each service call
Return type list(cloudformation.Stack)
Returns A list of Stack resources
Event
class CloudFormation.Event(id)
A resource representing an AWS CloudFormation Event:
156 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
import boto3
cloudformation = boto3.resource('cloudformation')
event = cloudformation.Event('id')
Parameters id (string) – The Event’s id identifier. This must be set.
These are the resource’s available identifiers:
•id
These are the resource’s available attributes:
•event_id
•logical_resource_id
•physical_resource_id
•resource_properties
•resource_status
•resource_status_reason
•resource_type
•stack_id
•stack_name
•timestamp
Identifiers
Identifiers are properties of a resource that are set upon instantation of the resource. For more information about
identifiers refer to the Resources Introduction Guide.
id
(string) The Event’s id identifier. This must be set.
Attributes
Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed
via the load() method. For more information about attributes refer to the Resources Introduction Guide.
event_id
(string)
The unique ID of this event.
logical_resource_id
(string)
The logical name of the resource specified in the template.
physical_resource_id
(string)
The name or unique identifier associated with the physical instance of the resource.
resource_properties
(string)
BLOB of the properties used to create the resource.
resource_status
(string)
Current status of the resource.
resource_status_reason
(string)
Success/failure message associated with the resource.
3.1. Services 157
Boto3 Documentation, Release 1.1.4
resource_type
(string)
Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFor-
mation User Guide.)
stack_id
(string)
The unique ID name of the instance of the stack.
stack_name
(string)
The name associated with a stack.
timestamp
(datetime)
Time the status was updated.
Stack
class CloudFormation.Stack(name)
A resource representing an AWS CloudFormation Stack:
import boto3
cloudformation = boto3.resource('cloudformation')
stack = cloudformation.Stack('name')
Parameters name (string) – The Stack’s name identifier. This must be set.
These are the resource’s available identifiers:
•name
These are the resource’s available attributes:
•capabilities
•creation_time
•description
•disable_rollback
•last_updated_time
•notification_arns
•outputs
•parameters
•stack_id
•stack_name
•stack_status
•stack_status_reason
•tags
•timeout_in_minutes
These are the resource’s available actions:
•cancel_update()
•delete()
•load()
•reload()
•update()
These are the resource’s available sub-resources:
158 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
•Resource()
These are the resource’s available collections:
•events
•resource_summaries
Identifiers
Identifiers are properties of a resource that are set upon instantation of the resource. For more information about
identifiers refer to the Resources Introduction Guide.
name
(string) The Stack’s name identifier. This must be set.
Attributes
Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed
via the load() method. For more information about attributes refer to the Resources Introduction Guide.
capabilities
(list)
The capabilities allowed in the stack.
creation_time
(datetime)
Time at which the stack was created.
description
(string)
User defined description associated with the stack.
disable_rollback
(boolean)
Boolean to enable or disable rollback on stack creation failures:
•true : disable rollback
•false : enable rollback
last_updated_time
(datetime)
The time the stack was last updated. This field will only be returned if the stack has been updated at least
once.
notification_arns
(list)
SNS topic ARNs to which stack related events are published.
outputs
(list)
A list of output structures.
parameters
(list)
A list of Parameter structures.
stack_id
(string)
Unique identifier of the stack.
3.1. Services 159
Boto3 Documentation, Release 1.1.4
stack_name
(string)
The name associated with the stack.
stack_status
(string)
Current status of the stack.
stack_status_reason
(string)
Success/failure message associated with the stack status.
tags
(list)
A list of Tag s that specify cost allocation information for the stack.
timeout_in_minutes
(integer)
The amount of time within which stack creation should complete.
Actions
Actions call operations on resources. They may automatically handle the passing in of arguments set from
identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.
cancel_update()
Cancels an update on the specified stack. If the call completes successfully, the stack will roll back the
update and revert to the previous stack configuration.
Note: Only stacks that are in the UPDATE_IN_PROGRESS state can be canceled.
Request Syntax
response = stack.cancel_update()
Returns None
delete()
Deletes a specified stack. Once the call completes successfully, stack deletion starts. Deleted stacks do
not show up in the DescribeStacks API if the deletion has been completed successfully.
Request Syntax
response = stack.delete()
Returns None
load()
Calls cloudformation.Client.describe_stacks() to update the attributes of the Stack re-
source
Request Syntax
stack.load()
Returns None
160 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
reload()
Calls cloudformation.Client.describe_stacks() to update the attributes of the Stack re-
source
Request Syntax
stack.reload()
Returns None
update(**kwargs)
Updates a stack as specified in the template. After the call completes successfully, the stack update starts.
You can check the status of the stack via the DescribeStacks action.
To get a copy of the template for an existing stack, you can use the GetTemplate action.
Tags that were associated with this stack during creation time will still be associated with the stack after
an UpdateStack operation.
For more information about creating an update template, updating a stack, and monitoring the progress of
the update, see Updating a Stack .
Request Syntax
response = stack.update(
TemplateBody='string',
TemplateURL='string',
UsePreviousTemplate=True|False,
StackPolicyDuringUpdateBody='string',
StackPolicyDuringUpdateURL='string',
Parameters=[
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
Capabilities=[
'CAPABILITY_IAM',
],
StackPolicyBody='string',
StackPolicyURL='string',
NotificationARNs=[
'string',
]
)
Parameters
• TemplateBody (string) – Structure containing the template body with a mini-
mum length of 1 byte and a maximum length of 51,200 bytes. (For more infor-
mation, go to Template Anatomy in the AWS CloudFormation User Guide.)
Conditional: You must specify either the TemplateBody or the
TemplateURL parameter, but not both.
• TemplateURL (string) – Location of file containing the template body. The
URL must point to a template located in an S3 bucket in the same region as the
stack. For more information, go to Template Anatomy in the AWS CloudForma-
tion User Guide.
3.1. Services 161
Boto3 Documentation, Release 1.1.4
Conditional: You must specify either the TemplateBody or the
TemplateURL parameter, but not both.
• UsePreviousTemplate (boolean) – Reuse the existing template that is associated
with the stack that you are updating.
• StackPolicyDuringUpdateBody (string) – Structure containing
the temporary overriding stack policy body. You can spec-
ify either the StackPolicyDuringUpdateBody or the
StackPolicyDuringUpdateURL parameter, but not both.
If you want to update protected resources, specify a temporary overriding stack
policy during this update. If you do not specify a stack policy, the current policy
that is associated with the stack will be used.
• StackPolicyDuringUpdateURL (string) – Location of a file containing the
temporary overriding stack policy. The URL must point to a policy (max
size: 16KB) located in an S3 bucket in the same region as the stack.
You can specify either the StackPolicyDuringUpdateBody or the
StackPolicyDuringUpdateURL parameter, but not both.
If you want to update protected resources, specify a temporary overriding stack
policy during this update. If you do not specify a stack policy, the current policy
that is associated with the stack will be used.
• Parameters (list) – A list of Parameter structures that specify input parame-
ters for the stack. For more information, see the Parameter data type.
– (dict) –
The Parameter data type.
* ParameterKey (string) –
The key associated with the parameter. If you don’t specify a key
and value for a particular parameter, AWS CloudFormation uses the
default value that is specified in your template.
* ParameterValue (string) –
The value associated with the parameter.
* UsePreviousValue (boolean) –
During a stack update, use the existing parameter value that the stack
is using for a given parameter key. If you specify true , do not
specify a parameter value.
• Capabilities (list) – A list of capabilities that you must specify before AWS
CloudFormation can create or update certain stacks. Some stack templates
might include resources that can affect permissions in your AWS account.
For those stacks, you must explicitly acknowledge their capabilities by spec-
ifying this parameter. Currently, the only valid value is CAPABILITY_IAM
, which is required for the following resources: AWS::IAM::AccessKey
, AWS::IAM::Group , AWS::IAM::InstanceProfile , AWS::IAM::Policy ,
AWS::IAM::Role , AWS::IAM::User , and AWS::IAM::UserToGroupAddition .
If your stack template contains these resources, we recommend that you review
any permissions associated with them. If you don’t specify this parameter, this
action returns an InsufficientCapabilities error.
– (string) –
• StackPolicyBody (string) – Structure containing a new stack policy body. You
can specify either the StackPolicyBody or the StackPolicyURL param-
eter, but not both.
You might update the stack policy, for example, in order to protect a new resource
that you created during a stack update. If you do not specify a stack policy, the
162 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
current policy that is associated with the stack is unchanged.
• StackPolicyURL (string) – Location of a file containing the updated stack pol-
icy. The URL must point to a policy (max size: 16KB) located in an S3 bucket in
the same region as the stack. You can specify either the StackPolicyBody
or the StackPolicyURL parameter, but not both.
You might update the stack policy, for example, in order to protect a new resource
that you created during a stack update. If you do not specify a stack policy, the
current policy that is associated with the stack is unchanged.
• NotificationARNs (list) – Update the ARNs for the Amazon SNS topics that are
associated with the stack.
– (string) –
Return type dict
Returns
Response Syntax
{
'StackId': 'string'
}
Response Structure
• (dict) –
The output for a UpdateStack action.
– StackId (string) –
Unique identifier of the stack.
Sub-resources
Sub-resources are methods that create a new instance of a child resource. This resource’s identifiers get passed
along to the child. For more information about sub-resources refer to the Resources Introduction Guide.
Resource(logical_id)
Creates a StackResource resource.:
stack_resource = stack.Resource('logical_id')
Parameters logical_id (string) – The Resource’s logical_id identifier. This must be set.
Return type CloudFormation.StackResource
Returns A StackResource resource
Collections
Collections provide an interface to iterate over and manipulate groups of resources. For more information about
collections refer to the Resources Introduction Guide.
events
all()
Creates an iterable of all Event resources in the collection.
Request Syntax
event_iterator = stack.events.all()
Return type list(cloudformation.Event)
Returns A list of Event resources
3.1. Services 163
Boto3 Documentation, Release 1.1.4
filter(**kwargs)
Creates an iterable of all Event resources in the collection filtered by kwargs passed to method.
Request Syntax
event_iterator = stack.events.filter(
NextToken='string'
)
Parameters NextToken (string) – String that identifies the start of the next list of
events, if there is one.
Default: There is no default value.
Return type list(cloudformation.Event)
Returns A list of Event resources
limit(**kwargs)
Creates an iterable up to a specified amount of Event resources in the collection.
Request Syntax
event_iterator = stack.events.limit(
count=123
)
Parameters count (integer) – The limit to the number of resources in the iterable.
Return type list(cloudformation.Event)
Returns A list of Event resources
page_size(**kwargs)
Creates an iterable of all Event resources in the collection, but limits the number of items returned
by each service call by the specified amount.
Request Syntax
event_iterator = stack.events.page_size(
count=123
)
Parameters count (integer) – The number of items returned by each service call
Return type list(cloudformation.Event)
Returns A list of Event resources
resource_summaries
all()
Creates an iterable of all StackResourceSummary resources in the collection.
Request Syntax
stack_resource_summary_iterator = stack.resource_summaries.all()
Return type list(cloudformation.StackResourceSummary)
Returns A list of StackResourceSummary resources
filter(**kwargs)
Creates an iterable of all StackResourceSummary resources in the collection filtered by kwargs
passed to method.
164 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
stack_resource_summary_iterator = stack.resource_summaries.filter(
NextToken='string'
)
Parameters NextToken (string) – String that identifies the start of the next list of
stack resource summaries, if there is one.
Default: There is no default value.
Return type list(cloudformation.StackResourceSummary)
Returns A list of StackResourceSummary resources
limit(**kwargs)
Creates an iterable up to a specified amount of StackResourceSummary resources in the collection.
Request Syntax
stack_resource_summary_iterator = stack.resource_summaries.limit(
count=123
)
Parameters count (integer) – The limit to the number of resources in the iterable.
Return type list(cloudformation.StackResourceSummary)
Returns A list of StackResourceSummary resources
page_size(**kwargs)
Creates an iterable of all StackResourceSummary resources in the collection, but limits the number
of items returned by each service call by the specified amount.
Request Syntax
stack_resource_summary_iterator = stack.resource_summaries.page_size(
count=123
)
Parameters count (integer) – The number of items returned by each service call
Return type list(cloudformation.StackResourceSummary)
Returns A list of StackResourceSummary resources
StackResource
class CloudFormation.StackResource(stack_name, logical_id)
A resource representing an AWS CloudFormation StackResource:
import boto3
cloudformation = boto3.resource('cloudformation')
stack_resource = cloudformation.StackResource('stack_name','logical_id')
Parameters
• stack_name (string) – The StackResource’s stack_name identifier. This must be set.
• logical_id (string) – The StackResource’s logical_id identifier. This must be set.
These are the resource’s available identifiers:
•stack_name
•logical_id
3.1. Services 165
Boto3 Documentation, Release 1.1.4
These are the resource’s available attributes:
•description
•last_updated_timestamp
•logical_resource_id
•metadata
•physical_resource_id
•resource_status
•resource_status_reason
•resource_type
•stack_id
These are the resource’s available sub-resources:
•Stack()
Identifiers
Identifiers are properties of a resource that are set upon instantation of the resource. For more information about
identifiers refer to the Resources Introduction Guide.
stack_name
(string) The StackResource’s stack_name identifier. This must be set.
logical_id
(string) The StackResource’s logical_id identifier. This must be set.
Attributes
Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed
via the load() method. For more information about attributes refer to the Resources Introduction Guide.
description
(string)
User defined description associated with the resource.
last_updated_timestamp
(datetime)
Time the status was updated.
logical_resource_id
(string)
The logical name of the resource specified in the template.
metadata
(string)
The JSON format content of the Metadata attribute declared for the resource. For more information,
see Metadata Attribute in the AWS CloudFormation User Guide.
physical_resource_id
(string)
The name or unique identifier that corresponds to a physical instance ID of a resource supported by AWS
CloudFormation.
resource_status
(string)
Current status of the resource.
resource_status_reason
(string)
166 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Success/failure message associated with the resource.
resource_type
(string)
Type of resource. ((For more information, go to AWS Resource Types Reference in the AWS CloudFor-
mation User Guide.)
stack_id
(string)
Unique identifier of the stack.
Sub-resources
Sub-resources are methods that create a new instance of a child resource. This resource’s identifiers get passed
along to the child. For more information about sub-resources refer to the Resources Introduction Guide.
Stack()
Creates a Stack resource.:
stack = stack_resource.Stack()
Return type CloudFormation.Stack
Returns A Stack resource
StackResourceSummary
class CloudFormation.StackResourceSummary(stack_name, logical_id)
A resource representing an AWS CloudFormation StackResourceSummary:
import boto3
cloudformation = boto3.resource('cloudformation')
stack_resource_summary = cloudformation.StackResourceSummary('stack_name','logical_id')
Parameters
• stack_name (string) – The StackResourceSummary’s stack_name identifier. This
must be set.
• logical_id (string) – The StackResourceSummary’s logical_id identifier. This must be
set.
These are the resource’s available identifiers:
•stack_name
•logical_id
These are the resource’s available attributes:
•last_updated_timestamp
•logical_resource_id
•physical_resource_id
•resource_status
•resource_status_reason
•resource_type
These are the resource’s available sub-resources:
•Resource()
Identifiers
Identifiers are properties of a resource that are set upon instantation of the resource. For more information about
identifiers refer to the Resources Introduction Guide.
3.1. Services 167
Boto3 Documentation, Release 1.1.4
stack_name
(string) The StackResourceSummary’s stack_name identifier. This must be set.
logical_id
(string) The StackResourceSummary’s logical_id identifier. This must be set.
Attributes
Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed
via the load() method. For more information about attributes refer to the Resources Introduction Guide.
last_updated_timestamp
(datetime)
Time the status was updated.
logical_resource_id
(string)
The logical name of the resource specified in the template.
physical_resource_id
(string)
The name or unique identifier that corresponds to a physical instance ID of the resource.
resource_status
(string)
Current status of the resource.
resource_status_reason
(string)
Success/failure message associated with the resource.
resource_type
(string)
Type of resource. (For more information, go to AWS Resource Types Reference in the AWS CloudFor-
mation User Guide.)
Sub-resources
Sub-resources are methods that create a new instance of a child resource. This resource’s identifiers get passed
along to the child. For more information about sub-resources refer to the Resources Introduction Guide.
Resource()
Creates a StackResource resource.:
stack_resource = stack_resource_summary.Resource()
Return type CloudFormation.StackResource
Returns A StackResource resource
CloudFront
168 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Table of Contents
• CloudFront
– Client
– Paginators
– Waiters
Client
class CloudFront.Client
A low-level client representing Amazon CloudFront:
import boto3
client = boto3.client('cloudfront')
These are the available methods:
•can_paginate()
•create_cloud_front_origin_access_identity()
•create_distribution()
•create_invalidation()
•create_streaming_distribution()
•delete_cloud_front_origin_access_identity()
•delete_distribution()
•delete_streaming_distribution()
•generate_presigned_url()
•get_cloud_front_origin_access_identity()
•get_cloud_front_origin_access_identity_config()
•get_distribution()
•get_distribution_config()
•get_invalidation()
•get_paginator()
•get_streaming_distribution()
•get_streaming_distribution_config()
•get_waiter()
•list_cloud_front_origin_access_identities()
•list_distributions()
•list_invalidations()
•list_streaming_distributions()
•update_cloud_front_origin_access_identity()
•update_distribution()
•update_streaming_distribution()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
3.1. Services 169
Boto3 Documentation, Release 1.1.4
create_cloud_front_origin_access_identity(**kwargs)
Create a new origin access identity.
Request Syntax
response = client.create_cloud_front_origin_access_identity(
CloudFrontOriginAccessIdentityConfig={
'CallerReference': 'string',
'Comment': 'string'
}
)
Parameters CloudFrontOriginAccessIdentityConfig (dict) – [REQUIRED] The origin
access identity’s configuration information.
• CallerReference (string) – [REQUIRED] A unique number that ensures the re-
quest can’t be replayed. If the CallerReference is new (no matter the content of
the CloudFrontOriginAccessIdentityConfig object), a new origin access identity
is created. If the CallerReference is a value you already sent in a previous re-
quest to create an identity, and the content of the CloudFrontOriginAccessIdenti-
tyConfig is identical to the original request (ignoring white space), the response
includes the same information returned to the original request. If the Caller-
Reference is a value you already sent in a previous request to create an identity
but the content of the CloudFrontOriginAccessIdentityConfig is different from
the original request, CloudFront returns a CloudFrontOriginAccessIdentityAl-
readyExists error.
• Comment (string) – [REQUIRED] Any comments you want to include about
the origin access identity.
Return type dict
Returns
Response Syntax
{
'CloudFrontOriginAccessIdentity': {
'Id': 'string',
'S3CanonicalUserId': 'string',
'CloudFrontOriginAccessIdentityConfig': {
'CallerReference': 'string',
'Comment': 'string'
}
},
'Location': 'string',
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– CloudFrontOriginAccessIdentity (dict) – The origin access identity’s in-
formation.
* Id (string) – The ID for the origin access identity. For example:
E74FTE3AJFJ256A.
* S3CanonicalUserId (string) – The Amazon S3 canonical user ID
for the origin access identity, which you use when giving the origin
access identity read permission to an object in Amazon S3.
* CloudFrontOriginAccessIdentityConfig (dict) – The current con-
figuration information for the identity.
170 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· CallerReference (string) – A unique number that ensures
the request can’t be replayed. If the CallerReference is new
(no matter the content of the CloudFrontOriginAccessIdenti-
tyConfig object), a new origin access identity is created. If the
CallerReference is a value you already sent in a previous re-
quest to create an identity, and the content of the CloudFron-
tOriginAccessIdentityConfig is identical to the original re-
quest (ignoring white space), the response includes the same
information returned to the original request. If the CallerRef-
erence is a value you already sent in a previous request to cre-
ate an identity but the content of the CloudFrontOriginAcces-
sIdentityConfig is different from the original request, Cloud-
Front returns a CloudFrontOriginAccessIdentityAlreadyEx-
ists error.
· Comment (string) – Any comments you want to include
about the origin access identity.
– Location (string) – The fully qualified URI of the new origin access iden-
tity just created. For example: https://cloudfront.amazonaws.com/2010-
11-01/origin-access-identity/cloudfront/E74FTE3AJFJ256A.
– ETag (string) – The current version of the origin access identity created.
create_distribution(**kwargs)
Create a new distribution.
Request Syntax
response = client.create_distribution(
DistributionConfig={
'CallerReference': 'string',
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'DefaultRootObject': 'string',
'Origins': {
'Quantity': 123,
'Items': [
{
'Id': 'string',
'DomainName': 'string',
'OriginPath': 'string',
'S3OriginConfig': {
'OriginAccessIdentity': 'string'
},
'CustomOriginConfig': {
'HTTPPort': 123,
'HTTPSPort': 123,
'OriginProtocolPolicy': 'http-only'|'match-viewer'
}
},
]
},
'DefaultCacheBehavior': {
'TargetOriginId': 'string',
'ForwardedValues': {
3.1. Services 171
Boto3 Documentation, Release 1.1.4
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
'CacheBehaviors': {
'Quantity': 123,
'Items': [
{
'PathPattern': 'string',
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
172 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
]
},
'CustomErrorResponses': {
'Quantity': 123,
'Items': [
{
'ErrorCode': 123,
'ResponsePagePath': 'string',
'ResponseCode': 'string',
'ErrorCachingMinTTL': 123
},
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'IncludeCookies': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False,
'ViewerCertificate': {
'IAMCertificateId': 'string',
'CloudFrontDefaultCertificate': True|False,
3.1. Services 173
Boto3 Documentation, Release 1.1.4
'SSLSupportMethod': 'sni-only'|'vip',
'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
},
'Restrictions': {
'GeoRestriction': {
'RestrictionType': 'blacklist'|'whitelist'|'none',
'Quantity': 123,
'Items': [
'string',
]
}
}
}
)
Parameters DistributionConfig (dict) – [REQUIRED] The distribution’s configuration in-
formation.
• CallerReference (string) – [REQUIRED] A unique number that ensures the re-
quest can’t be replayed. If the CallerReference is new (no matter the content of
the DistributionConfig object), a new distribution is created. If the CallerRefer-
ence is a value you already sent in a previous request to create a distribution, and
the content of the DistributionConfig is identical to the original request (ignoring
white space), the response includes the same information returned to the original
request. If the CallerReference is a value you already sent in a previous request
to create a distribution but the content of the DistributionConfig is different from
the original request, CloudFront returns a DistributionAlreadyExists error.
• Aliases (dict) – A complex type that contains information about CNAMEs (al-
ternate domain names), if any, for this distribution.
– Quantity (integer) – [REQUIRED] The number of CNAMEs, if any, for
this distribution.
– Items (list) – Optional: A complex type that contains CNAME elements,
if any, for this distribution. If Quantity is 0, you can omit Items.
* (string) –
• DefaultRootObject (string) – The object that you want CloudFront to return
(for example, index.html) when an end user requests the root URL for your
distribution (http://www.example.com) instead of an object in your distribution
(http://www.example.com/index.html). Specifying a default root object avoids
exposing the contents of your distribution. If you don’t want to specify a default
root object when you create a distribution, include an empty DefaultRootObject
element. To delete the default root object from an existing distribution, update
the distribution configuration and include an empty DefaultRootObject element.
To replace the default root object, update the distribution configuration and spec-
ify the new object.
• Origins (dict) – [REQUIRED] A complex type that contains information about
origins for this distribution.
– Quantity (integer) – [REQUIRED] The number of origins for this distri-
bution.
– Items (list) – A complex type that contains origins for this distribution.
* (dict) – A complex type that describes the Amazon S3 bucket or the
HTTP server (for example, a web server) from which CloudFront
gets your files.You must create at least one origin.
· Id (string) – [REQUIRED] A unique identifier for the origin.
The value of Id must be unique within the distribution. You
use the value of Id when you create a cache behavior. The Id
identifies the origin that CloudFront routes a request to when
174 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
the request matches the path pattern for that cache behavior.
· DomainName (string) – [REQUIRED] Amazon S3 origins:
The DNS name of the Amazon S3 bucket from which you
want CloudFront to get objects for this origin, for exam-
ple, myawsbucket.s3.amazonaws.com. Custom origins: The
DNS domain name for the HTTP server from which you
want CloudFront to get objects for this origin, for example,
www.example.com.
· OriginPath (string) – An optional element that causes Cloud-
Front to request your content from a directory in your Ama-
zon S3 bucket or your custom origin. When you include the
OriginPath element, specify the directory name, beginning
with a /. CloudFront appends the directory name to the value
of DomainName.
· S3OriginConfig (dict) – A complex type that contains infor-
mation about the Amazon S3 origin. If the origin is a custom
origin, use the CustomOriginConfig element instead.
· OriginAccessIdentity (string) – [REQUIRED] The Cloud-
Front origin access identity to associate with the origin. Use
an origin access identity to configure the origin so that end
users can only access objects in an Amazon S3 bucket through
CloudFront. If you want end users to be able to access ob-
jects using either the CloudFront URL or the Amazon S3
URL, specify an empty OriginAccessIdentity element. To
delete the origin access identity from an existing distribution,
update the distribution configuration and include an empty
OriginAccessIdentity element. To replace the origin access
identity, update the distribution configuration and specify the
new origin access identity. Use the format origin-access-
identity/cloudfront/Id where Id is the value that CloudFront
returned in the Id element when you created the origin access
identity.
· CustomOriginConfig (dict) – A complex type that contains
information about a custom origin. If the origin is an Amazon
S3 bucket, use the S3OriginConfig element instead.
· HTTPPort (integer) – [REQUIRED] The HTTP port the
custom origin listens on.
· HTTPSPort (integer) – [REQUIRED] The HTTPS port the
custom origin listens on.
· OriginProtocolPolicy (string) – [REQUIRED] The origin
protocol policy to apply to your origin.
• DefaultCacheBehavior (dict) – [REQUIRED] A complex type that describes
the default cache behavior if you do not specify a CacheBehavior element or
if files don’t match any of the values of PathPattern in CacheBehavior ele-
ments.You must create exactly one default cache behavior.
– TargetOriginId (string) – [REQUIRED] The value of ID for the origin
that you want CloudFront to route requests to when a request matches the
path pattern either for a cache behavior or for the default cache behavior.
– ForwardedValues (dict) – [REQUIRED] A complex type that specifies
how CloudFront handles query strings, cookies and headers.
* QueryString (boolean) – [REQUIRED] Indicates whether you
want CloudFront to forward query strings to the origin that is as-
sociated with this cache behavior. If so, specify true; if not, specify
false.
3.1. Services 175
Boto3 Documentation, Release 1.1.4
* Cookies (dict) – [REQUIRED] A complex type that specifies how
CloudFront handles cookies.
· Forward (string) – [REQUIRED] Use this element to spec-
ify whether you want CloudFront to forward cookies to the
origin that is associated with this cache behavior. You can
specify all, none or whitelist. If you choose All, CloudFront
forwards all cookies regardless of how many your application
uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – [REQUIRED] The number of
whitelisted cookies for this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
* Headers (dict) – A complex type that specifies the Headers, if any,
that you want CloudFront to vary upon for this cache behavior.
· Quantity (integer) – [REQUIRED] The number of different
headers that you want CloudFront to forward to the origin and
to vary on for this cache behavior. The maximum number
of headers that you can specify by name is 10. If you want
CloudFront to forward all headers to the origin and vary on
all of them, specify 1 for Quantity and * for Name. If you
don’t want CloudFront to forward any additional headers to
the origin or to vary on any headers, specify 0 for Quantity
and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
– TrustedSigners (dict) – [REQUIRED] A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed URLs for
private content. If you want to require signed URLs in requests for ob-
jects in the target origin that match the PathPattern for this cache behavior,
specify true for Enabled, and specify the applicable values for Quantity
and Items. For more information, go to Using a Signed URL to Serve Pri-
vate Content in the Amazon CloudFront Developer Guide. If you don’t
want to require signed URLs in requests for objects that match PathPat-
tern, specify false for Enabled and 0 for Quantity. Omit Items. To add,
change, or remove one or more trusted signers, change Enabled to true (if
it’s currently false), change Quantity as applicable, and specify all of the
trusted signers that you want to include in the updated distribution.
* Enabled (boolean) – [REQUIRED] Specifies whether you want to
require end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
* Quantity (integer) – [REQUIRED] The number of trusted signers
for this cache behavior.
* Items (list) – Optional: A complex type that contains trusted signers
for this cache behavior. If Quantity is 0, you can omit Items.
· (string) –
– ViewerProtocolPolicy (string) – [REQUIRED] Use this element to spec-
176 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
ify the protocol that users can use to access the files in the origin specified
by TargetOriginId when a request matches the path pattern in PathPattern.
If you want CloudFront to allow end users to use any available protocol,
specify allow-all. If you want CloudFront to require HTTPS, specify https.
If you want CloudFront to respond to an HTTP request with an HTTP
status code of 301 (Moved Permanently) and the HTTPS URL, specify
redirect-to-https. The viewer then resubmits the request using the HTTPS
URL.
– MinTTL (integer) – [REQUIRED] The minimum amount of time that
you want objects to stay in CloudFront caches before CloudFront queries
your origin to see whether the object has been updated.You can specify a
value from 0 to 3,153,600,000 seconds (100 years).
– AllowedMethods (dict) – A complex type that controls which HTTP
methods CloudFront processes and forwards to your Amazon S3 bucket
or your custom origin. There are three choices: - CloudFront forwards
only GET and HEAD requests. - CloudFront forwards only GET, HEAD
and OPTIONS requests. - CloudFront forwards GET, HEAD, OPTIONS,
PUT, PATCH, POST, and DELETE requests. If you pick the third choice,
you may need to restrict access to your Amazon S3 bucket or to your cus-
tom origin so users can’t perform operations that you don’t want them to.
For example, you may not want users to have permission to delete objects
from your origin.
* Quantity (integer) – [REQUIRED] The number of HTTP methods
that you want CloudFront to forward to your origin. Valid values are
2 (for GET and HEAD requests), 3 (for GET, HEAD and OPTIONS
requests) and 7 (for GET, HEAD, OPTIONS, PUT, PATCH, POST,
and DELETE requests).
* Items (list) – [REQUIRED] A complex type that contains the
HTTP methods that you want CloudFront to process and forward
to your origin.
· (string) –
* CachedMethods (dict) – A complex type that controls whether
CloudFront caches the response to requests using the specified
HTTP methods. There are two choices: - CloudFront caches re-
sponses to GET and HEAD requests. - CloudFront caches re-
sponses to GET, HEAD, and OPTIONS requests. If you pick
the second choice for your S3 Origin, you may need to for-
ward Access-Control-Request-Method, Access-Control-Request-
Headers and Origin headers for the responses to be cached correctly.
· Quantity (integer) – [REQUIRED] The number of HTTP
methods for which you want CloudFront to cache responses.
Valid values are 2 (for caching responses to GET and HEAD
requests) and 3 (for caching responses to GET, HEAD, and
OPTIONS requests).
· Items (list) – [REQUIRED] A complex type that contains the
HTTP methods that you want CloudFront to cache responses
to.
· (string) –
– SmoothStreaming (boolean) – Indicates whether you want to distribute
media files in Microsoft Smooth Streaming format using the origin that
is associated with this cache behavior. If so, specify true; if not, specify
false.
– DefaultTTL (integer) – If you don’t configure your origin to add a Cache-
Control max-age directive or an Expires header, DefaultTTL is the default
3.1. Services 177
Boto3 Documentation, Release 1.1.4
amount of time (in seconds) that an object is in a CloudFront cache before
CloudFront forwards another request to your origin to determine whether
the object has been updated. The value that you specify applies only when
your origin does not add HTTP headers such as Cache-Control max-age,
Cache-Control s-maxage, and Expires to objects. You can specify a value
from 0 to 3,153,600,000 seconds (100 years).
– MaxTTL (integer) – The maximum amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards another re-
quest to your origin to determine whether the object has been updated. The
value that you specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000 seconds (100
years).
• CacheBehaviors (dict) – A complex type that contains zero or more CacheBe-
havior elements.
– Quantity (integer) – [REQUIRED] The number of cache behaviors for
this distribution.
– Items (list) – Optional: A complex type that contains cache behaviors for
this distribution. If Quantity is 0, you can omit Items.
* (dict) – A complex type that describes how CloudFront processes
requests. You can create up to 10 cache behaviors.You must create
at least as many cache behaviors (including the default cache behav-
ior) as you have origins if you want CloudFront to distribute objects
from all of the origins. Each cache behavior specifies the one origin
from which you want CloudFront to get objects. If you have two ori-
gins and only the default cache behavior, the default cache behavior
will cause CloudFront to get objects from one of the origins, but the
other origin will never be used. If you don’t want to specify any
cache behaviors, include only an empty CacheBehaviors element.
Don’t include an empty CacheBehavior element, or CloudFront re-
turns a MalformedXML error. To delete all cache behaviors in an
existing distribution, update the distribution configuration and in-
clude only an empty CacheBehaviors element. To add, change, or
remove one or more cache behaviors, update the distribution con-
figuration and specify all of the cache behaviors that you want to
include in the updated distribution.
· PathPattern (string) – [REQUIRED] The pattern (for ex-
ample, images/*.jpg) that specifies which requests you want
this cache behavior to apply to. When CloudFront receives
an end-user request, the requested path is compared with path
patterns in the order in which cache behaviors are listed in the
distribution. The path pattern for the default cache behavior is
* and cannot be changed. If the request for an object does not
match the path pattern for any cache behaviors, CloudFront
applies the behavior in the default cache behavior.
· TargetOriginId (string) – [REQUIRED] The value of ID for
the origin that you want CloudFront to route requests to when
a request matches the path pattern either for a cache behavior
or for the default cache behavior.
· ForwardedValues (dict) – [REQUIRED] A complex type
that specifies how CloudFront handles query strings, cookies
and headers.
· QueryString (boolean) – [REQUIRED] Indicates whether
you want CloudFront to forward query strings to the origin
178 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
that is associated with this cache behavior. If so, specify true;
if not, specify false.
· Cookies (dict) – [REQUIRED] A complex type that specifies
how CloudFront handles cookies.
· Forward (string) – [REQUIRED] Use this element to spec-
ify whether you want CloudFront to forward cookies to the
origin that is associated with this cache behavior. You can
specify all, none or whitelist. If you choose All, CloudFront
forwards all cookies regardless of how many your application
uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – [REQUIRED] The number of
whitelisted cookies for this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – [REQUIRED] The number of different
headers that you want CloudFront to forward to the origin and
to vary on for this cache behavior. The maximum number
of headers that you can specify by name is 10. If you want
CloudFront to forward all headers to the origin and vary on
all of them, specify 1 for Quantity and * for Name. If you
don’t want CloudFront to forward any additional headers to
the origin or to vary on any headers, specify 0 for Quantity
and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – [REQUIRED] A complex type that
specifies the AWS accounts, if any, that you want to allow to
create signed URLs for private content. If you want to require
signed URLs in requests for objects in the target origin that
match the PathPattern for this cache behavior, specify true for
Enabled, and specify the applicable values for Quantity and
Items. For more information, go to Using a Signed URL to
Serve Private Content in the Amazon CloudFront Developer
Guide. If you don’t want to require signed URLs in requests
for objects that match PathPattern, specify false for Enabled
and 0 for Quantity. Omit Items. To add, change, or remove
one or more trusted signers, change Enabled to true (if it’s
currently false), change Quantity as applicable, and specify all
of the trusted signers that you want to include in the updated
distribution.
· Enabled (boolean) – [REQUIRED] Specifies whether you
want to require end users to use signed URLs to access the
files specified by PathPattern and TargetOriginId.
3.1. Services 179
Boto3 Documentation, Release 1.1.4
· Quantity (integer) – [REQUIRED] The number of trusted
signers for this cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – [REQUIRED] Use this el-
ement to specify the protocol that users can use to access the
files in the origin specified by TargetOriginId when a request
matches the path pattern in PathPattern. If you want Cloud-
Front to allow end users to use any available protocol, specify
allow-all. If you want CloudFront to require HTTPS, specify
https. If you want CloudFront to respond to an HTTP request
with an HTTP status code of 301 (Moved Permanently) and
the HTTPS URL, specify redirect-to-https. The viewer then
resubmits the request using the HTTPS URL.
· MinTTL (integer) – [REQUIRED] The minimum amount of
time that you want objects to stay in CloudFront caches before
CloudFront queries your origin to see whether the object has
been updated.You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – [REQUIRED] The number of HTTP
methods that you want CloudFront to forward to your origin.
Valid values are 2 (for GET and HEAD requests), 3 (for GET,
HEAD and OPTIONS requests) and 7 (for GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests).
· Items (list) – [REQUIRED] A complex type that contains
the HTTP methods that you want CloudFront to process and
forward to your origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – [REQUIRED] The number of HTTP
methods for which you want CloudFront to cache responses.
Valid values are 2 (for caching responses to GET and HEAD
180 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
requests) and 3 (for caching responses to GET, HEAD, and
OPTIONS requests).
· Items (list) – [REQUIRED] A complex type that contains the
HTTP methods that you want CloudFront to cache responses
to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
• CustomErrorResponses (dict) – A complex type that contains zero or more
CustomErrorResponse elements.
– Quantity (integer) – [REQUIRED] The number of custom error re-
sponses for this distribution.
– Items (list) – Optional: A complex type that contains custom error re-
sponses for this distribution. If Quantity is 0, you can omit Items.
* (dict) – A complex type that describes how you’d prefer CloudFront
to respond to requests that result in either a 4xx or 5xx response.
You can control whether a custom error page should be displayed,
what the desired response code should be for this error page and
how long should the error response be cached by CloudFront. If you
don’t want to specify any custom error responses, include only an
empty CustomErrorResponses element. To delete all custom error
responses in an existing distribution, update the distribution config-
uration and include only an empty CustomErrorResponses element.
To add, change, or remove one or more custom error responses, up-
date the distribution configuration and specify all of the custom error
responses that you want to include in the updated distribution.
· ErrorCode (integer) – [REQUIRED] The 4xx or 5xx HTTP
status code that you want to customize. For a list of HTTP
status codes that you can customize, see CloudFront docu-
mentation.
· ResponsePagePath (string) – The path of the custom error
page (for example, /custom_404.html). The path is relative
to the distribution and must begin with a slash (/). If the path
includes any non-ASCII characters or unsafe characters as de-
3.1. Services 181
Boto3 Documentation, Release 1.1.4
fined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL
encode those characters. Do not URL encode any other char-
acters in the path, or CloudFront will not return the custom
error page to the viewer.
· ResponseCode (string) – The HTTP status code that you
want CloudFront to return with the custom error page to the
viewer. For a list of HTTP status codes that you can replace,
see CloudFront Documentation.
· ErrorCachingMinTTL (integer) – The minimum amount of
time you want HTTP error codes to stay in CloudFront caches
before CloudFront queries your origin to see whether the ob-
ject has been updated. You can specify a value from 0 to
31,536,000.
• Comment (string) – [REQUIRED] Any comments you want to include about
the distribution.
• Logging (dict) – A complex type that controls whether access logs are written
for the distribution.
– Enabled (boolean) – [REQUIRED] Specifies whether you want Cloud-
Front to save access logs to an Amazon S3 bucket. If you do not want
to enable logging when you create a distribution or if you want to disable
logging for an existing distribution, specify false for Enabled, and specify
empty Bucket and Prefix elements. If you specify false for Enabled but
you specify values for Bucket, prefix and IncludeCookies, the values are
automatically deleted.
– IncludeCookies (boolean) – [REQUIRED] Specifies whether you want
CloudFront to include cookies in access logs, specify true for Include-
Cookies. If you choose to include cookies in logs, CloudFront logs all
cookies regardless of how you configure the cache behaviors for this dis-
tribution. If you do not want to include cookies when you create a distribu-
tion or if you want to disable include cookies for an existing distribution,
specify false for IncludeCookies.
– Bucket (string) – [REQUIRED] The Amazon S3 bucket to store the ac-
cess logs in, for example, myawslogbucket.s3.amazonaws.com.
– Prefix (string) – [REQUIRED] An optional string that you want Cloud-
Front to prefix to the access log filenames for this distribution, for ex-
ample, myprefix/. If you want to enable logging, but you do not want
to specify a prefix, you still must include an empty Prefix element in the
Logging element.
• PriceClass (string) – A complex type that contains information about price class
for this distribution.
• Enabled (boolean) – [REQUIRED] Whether the distribution is enabled to ac-
cept end user requests for content.
• ViewerCertificate (dict) – A complex type that contains information about
viewer certificates for this distribution.
– IAMCertificateId (string) – If you want viewers to use HTTPS to re-
quest your objects and you’re using an alternate domain name in your ob-
ject URLs (for example, https://example.com/logo.jpg), specify the IAM
certificate identifier of the custom viewer certificate for this distribution.
Specify either this value or CloudFrontDefaultCertificate.
– CloudFrontDefaultCertificate (boolean) – If you want viewers to use
HTTPS to request your objects and you’re using the CloudFront do-
main name of your distribution in your object URLs (for example,
https://d111111abcdef8.cloudfront.net/logo.jpg), set to true. Omit this
value if you are setting an IAMCertificateId.
182 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– SSLSupportMethod (string) – If you specify a value for IAMCertifi-
cateId, you must also specify how you want CloudFront to serve HTTPS
requests. Valid values are vip and sni-only. If you specify vip, CloudFront
uses dedicated IP addresses for your content and can respond to HTTPS
requests from any viewer. However, you must request permission to use
this feature, and you incur additional monthly charges. If you specify sni-
only, CloudFront can only respond to HTTPS requests from viewers that
support Server Name Indication (SNI). All modern browsers support SNI,
but some browsers still in use don’t support SNI. Do not specify a value
for SSLSupportMethod if you specified true for CloudFrontDefaultCertifi-
cate.
– MinimumProtocolVersion (string) – Specify the minimum version of
the SSL protocol that you want CloudFront to use, SSLv3 or TLSv1, for
HTTPS connections. CloudFront will serve your objects only to browsers
or devices that support at least the SSL version that you specify. The
TLSv1 protocol is more secure, so we recommend that you specify SSLv3
only if your users are using browsers or devices that don’t support TLSv1.
If you’re using a custom certificate (if you specify a value for IAMCertifi-
cateId) and if you’re using dedicated IP (if you specify vip for SSLSup-
portMethod), you can choose SSLv3 or TLSv1 as the MinimumProto-
colVersion. If you’re using a custom certificate (if you specify a value
for IAMCertificateId) and if you’re using SNI (if you specify sni-only for
SSLSupportMethod), you must specify TLSv1 for MinimumProtocolVer-
sion.
• Restrictions (dict) – A complex type that identifies ways in which you want to
restrict distribution of your content.
– GeoRestriction (dict) – [REQUIRED] A complex type that controls the
countries in which your content is distributed. For more information about
geo restriction, go to Customizing Error Responses in the Amazon Cloud-
Front Developer Guide. CloudFront determines the location of your users
using MaxMind GeoIP databases. For information about the accuracy of
these databases, see How accurate are your GeoIP databases? on the Max-
Mind website.
* RestrictionType (string) – [REQUIRED] The method that you
want to use to restrict distribution of your content by country: -
none: No geo restriction is enabled, meaning access to content is
not restricted by client geo location. - blacklist: The Location ele-
ments specify the countries in which you do not want CloudFront
to distribute your content. - whitelist: The Location elements spec-
ify the countries in which you want CloudFront to distribute your
content.
* Quantity (integer) – [REQUIRED] When geo restriction is en-
abled, this is the number of countries in your whitelist or blacklist.
Otherwise, when it is not enabled, Quantity is 0, and you can omit
Items.
* Items (list) – A complex type that contains a Location element for
each country in which you want CloudFront either to distribute your
content (whitelist) or not distribute your content (blacklist). The Lo-
cation element is a two-letter, uppercase country code for a country
that you want to include in your blacklist or whitelist. Include one
Location element for each country. CloudFront and MaxMind both
use ISO 3166 country codes. For the current list of countries and the
corresponding codes, see ISO 3166-1-alpha-2 code on the Interna-
tional Organization for Standardization website. You can also refer
3.1. Services 183
Boto3 Documentation, Release 1.1.4
to the country list in the CloudFront console, which includes both
country names and codes.
· (string) –
Return type dict
Returns
Response Syntax
{
'Distribution': {
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'InProgressInvalidationBatches': 123,
'DomainName': 'string',
'ActiveTrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
{
'AwsAccountNumber': 'string',
'KeyPairIds': {
'Quantity': 123,
'Items': [
'string',
]
}
},
]
},
'DistributionConfig': {
'CallerReference': 'string',
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'DefaultRootObject': 'string',
'Origins': {
'Quantity': 123,
'Items': [
{
'Id': 'string',
'DomainName': 'string',
'OriginPath': 'string',
'S3OriginConfig': {
'OriginAccessIdentity': 'string'
},
'CustomOriginConfig': {
'HTTPPort': 123,
'HTTPSPort': 123,
'OriginProtocolPolicy': 'http-only'|'match-viewer'
}
},
]
},
'DefaultCacheBehavior': {
184 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-http
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
'CacheBehaviors': {
'Quantity': 123,
'Items': [
{
'PathPattern': 'string',
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
3.1. Services 185
Boto3 Documentation, Release 1.1.4
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELET
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'D
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
]
},
'CustomErrorResponses': {
'Quantity': 123,
'Items': [
{
'ErrorCode': 123,
'ResponsePagePath': 'string',
'ResponseCode': 'string',
'ErrorCachingMinTTL': 123
},
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'IncludeCookies': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False,
'ViewerCertificate': {
186 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'IAMCertificateId': 'string',
'CloudFrontDefaultCertificate': True|False,
'SSLSupportMethod': 'sni-only'|'vip',
'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
},
'Restrictions': {
'GeoRestriction': {
'RestrictionType': 'blacklist'|'whitelist'|'none',
'Quantity': 123,
'Items': [
'string',
]
}
}
}
},
'Location': 'string',
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– Distribution (dict) – The distribution’s information.
* Id (string) – The identifier for the distribution. For example: EDFD-
VBD632BHDS5.
* Status (string) – This response element indicates the current status
of the distribution. When the status is Deployed, the distribution’s
information is fully propagated throughout the Amazon CloudFront
system.
* LastModifiedTime (datetime) – The date and time the distribution
was last modified.
* InProgressInvalidationBatches (integer) – The number of invali-
dation batches currently in progress.
* DomainName (string) – The domain name corresponding to the
distribution. For example: d604721fxaaqy9.cloudfront.net.
* ActiveTrustedSigners (dict) – CloudFront automatically adds this
element to the response only if you’ve set up the distribution to serve
private content with signed URLs. The element lists the key pair IDs
that CloudFront is aware of for each trusted signer. The Signer child
element lists the AWS account number of the trusted signer (or an
empty Self element if the signer is you). The Signer element also
includes the IDs of any active key pairs associated with the trusted
signer’s AWS account. If no KeyPairId element appears for a Signer,
that signer can’t create working signed URLs.
· Enabled (boolean) – Each active trusted signer.
· Quantity (integer) – The number of unique trusted signers
included in all cache behaviors. For example, if three cache
behaviors all list the same three AWS accounts, the value of
Quantity for ActiveTrustedSigners will be 3.
· Items (list) – A complex type that contains one Signer com-
plex type for each unique trusted signer that is specified in the
TrustedSigners complex type, including trusted signers in the
default cache behavior and in all of the other cache behaviors.
· (dict) – A complex type that lists the AWS accounts that were
included in the TrustedSigners complex type, as well as their
3.1. Services 187
Boto3 Documentation, Release 1.1.4
active CloudFront key pair IDs, if any.
· AwsAccountNumber (string) – Specifies an AWS account
that can create signed URLs. Values: self, which indicates
that the AWS account that was used to create the distribution
can created signed URLs, or an AWS account number. Omit
the dashes in the account number.
· KeyPairIds (dict) – A complex type that lists the active
CloudFront key pairs, if any, that are associated with AwsAc-
countNumber.
· Quantity (integer) – The number of active CloudFront key
pairs for AwsAccountNumber.
· Items (list) – A complex type that lists the active CloudFront
key pairs, if any, that are associated with AwsAccountNum-
ber.
· (string) –
* DistributionConfig (dict) – The current configuration information
for the distribution.
· CallerReference (string) – A unique number that ensures the
request can’t be replayed. If the CallerReference is new (no
matter the content of the DistributionConfig object), a new
distribution is created. If the CallerReference is a value you
already sent in a previous request to create a distribution,
and the content of the DistributionConfig is identical to the
original request (ignoring white space), the response includes
the same information returned to the original request. If the
CallerReference is a value you already sent in a previous re-
quest to create a distribution but the content of the Distribu-
tionConfig is different from the original request, CloudFront
returns a DistributionAlreadyExists error.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this dis-
tribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· DefaultRootObject (string) – The object that you want
CloudFront to return (for example, index.html) when an
end user requests the root URL for your distribution
(http://www.example.com) instead of an object in your dis-
tribution (http://www.example.com/index.html). Specifying
a default root object avoids exposing the contents of your dis-
tribution. If you don’t want to specify a default root object
when you create a distribution, include an empty Default-
RootObject element. To delete the default root object from
an existing distribution, update the distribution configuration
and include an empty DefaultRootObject element. To replace
the default root object, update the distribution configuration
and specify the new object.
· Origins (dict) – A complex type that contains information
about origins for this distribution.
· Quantity (integer) – The number of origins for this distribu-
188 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
tion.
· Items (list) – A complex type that contains origins for this
distribution.
· (dict) – A complex type that describes the Amazon S3 bucket
or the HTTP server (for example, a web server) from which
CloudFront gets your files.You must create at least one origin.
· Id (string) – A unique identifier for the origin. The value of
Id must be unique within the distribution. You use the value
of Id when you create a cache behavior. The Id identifies the
origin that CloudFront routes a request to when the request
matches the path pattern for that cache behavior.
· DomainName (string) – Amazon S3 origins: The DNS name
of the Amazon S3 bucket from which you want Cloud-
Front to get objects for this origin, for example, myaws-
bucket.s3.amazonaws.com. Custom origins: The DNS do-
main name for the HTTP server from which you want
CloudFront to get objects for this origin, for example,
www.example.com.
· OriginPath (string) – An optional element that causes Cloud-
Front to request your content from a directory in your Ama-
zon S3 bucket or your custom origin. When you include the
OriginPath element, specify the directory name, beginning
with a /. CloudFront appends the directory name to the value
of DomainName.
· S3OriginConfig (dict) – A complex type that contains infor-
mation about the Amazon S3 origin. If the origin is a custom
origin, use the CustomOriginConfig element instead.
· OriginAccessIdentity (string) – The CloudFront origin ac-
cess identity to associate with the origin. Use an origin ac-
cess identity to configure the origin so that end users can only
access objects in an Amazon S3 bucket through CloudFront.
If you want end users to be able to access objects using ei-
ther the CloudFront URL or the Amazon S3 URL, specify
an empty OriginAccessIdentity element. To delete the origin
access identity from an existing distribution, update the distri-
bution configuration and include an empty OriginAccessIden-
tity element. To replace the origin access identity, update the
distribution configuration and specify the new origin access
identity. Use the format origin-access-identity/cloudfront/Id
where Id is the value that CloudFront returned in the Id ele-
ment when you created the origin access identity.
· CustomOriginConfig (dict) – A complex type that contains
information about a custom origin. If the origin is an Amazon
S3 bucket, use the S3OriginConfig element instead.
· HTTPPort (integer) – The HTTP port the custom origin lis-
tens on.
· HTTPSPort (integer) – The HTTPS port the custom origin
listens on.
· OriginProtocolPolicy (string) – The origin protocol policy
to apply to your origin.
· DefaultCacheBehavior (dict) – A complex type that de-
scribes the default cache behavior if you do not specify a
CacheBehavior element or if files don’t match any of the val-
ues of PathPattern in CacheBehavior elements.You must cre-
3.1. Services 189
Boto3 Documentation, Release 1.1.4
ate exactly one default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
190 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
3.1. Services 191
Boto3 Documentation, Release 1.1.4
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CacheBehaviors (dict) – A complex type that contains zero
or more CacheBehavior elements.
· Quantity (integer) – The number of cache behaviors for this
distribution.
· Items (list) – Optional: A complex type that contains cache
behaviors for this distribution. If Quantity is 0, you can omit
Items.
· (dict) – A complex type that describes how CloudFront pro-
cesses requests. You can create up to 10 cache behav-
iors.You must create at least as many cache behaviors (in-
cluding the default cache behavior) as you have origins if you
want CloudFront to distribute objects from all of the origins.
Each cache behavior specifies the one origin from which you
want CloudFront to get objects. If you have two origins and
only the default cache behavior, the default cache behavior
will cause CloudFront to get objects from one of the ori-
gins, but the other origin will never be used. If you don’t
want to specify any cache behaviors, include only an empty
CacheBehaviors element. Don’t include an empty CacheBe-
havior element, or CloudFront returns a MalformedXML er-
ror. To delete all cache behaviors in an existing distribu-
tion, update the distribution configuration and include only an
192 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
empty CacheBehaviors element. To add, change, or remove
one or more cache behaviors, update the distribution configu-
ration and specify all of the cache behaviors that you want to
include in the updated distribution.
· PathPattern (string) – The pattern (for example, im-
ages/*.jpg) that specifies which requests you want this cache
behavior to apply to. When CloudFront receives an end-user
request, the requested path is compared with path patterns in
the order in which cache behaviors are listed in the distribu-
tion. The path pattern for the default cache behavior is * and
cannot be changed. If the request for an object does not match
the path pattern for any cache behaviors, CloudFront applies
the behavior in the default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
3.1. Services 193
Boto3 Documentation, Release 1.1.4
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
194 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CustomErrorResponses (dict) – A complex type that con-
tains zero or more CustomErrorResponse elements.
· Quantity (integer) – The number of custom error responses
for this distribution.
· Items (list) – Optional: A complex type that contains custom
error responses for this distribution. If Quantity is 0, you can
omit Items.
· (dict) – A complex type that describes how you’d prefer
CloudFront to respond to requests that result in either a 4xx or
5xx response. You can control whether a custom error page
3.1. Services 195
Boto3 Documentation, Release 1.1.4
should be displayed, what the desired response code should
be for this error page and how long should the error response
be cached by CloudFront. If you don’t want to specify any
custom error responses, include only an empty CustomEr-
rorResponses element. To delete all custom error responses
in an existing distribution, update the distribution configura-
tion and include only an empty CustomErrorResponses ele-
ment. To add, change, or remove one or more custom error
responses, update the distribution configuration and specify
all of the custom error responses that you want to include in
the updated distribution.
· ErrorCode (integer) – The 4xx or 5xx HTTP status code that
you want to customize. For a list of HTTP status codes that
you can customize, see CloudFront documentation.
· ResponsePagePath (string) – The path of the custom error
page (for example, /custom_404.html). The path is relative
to the distribution and must begin with a slash (/). If the path
includes any non-ASCII characters or unsafe characters as de-
fined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL
encode those characters. Do not URL encode any other char-
acters in the path, or CloudFront will not return the custom
error page to the viewer.
· ResponseCode (string) – The HTTP status code that you
want CloudFront to return with the custom error page to the
viewer. For a list of HTTP status codes that you can replace,
see CloudFront Documentation.
· ErrorCachingMinTTL (integer) – The minimum amount of
time you want HTTP error codes to stay in CloudFront caches
before CloudFront queries your origin to see whether the ob-
ject has been updated. You can specify a value from 0 to
31,536,000.
· Comment (string) – Any comments you want to include
about the distribution.
· Logging (dict) – A complex type that controls whether access
logs are written for the distribution.
· Enabled (boolean) – Specifies whether you want CloudFront
to save access logs to an Amazon S3 bucket. If you do not
want to enable logging when you create a distribution or if
you want to disable logging for an existing distribution, spec-
ify false for Enabled, and specify empty Bucket and Prefix
elements. If you specify false for Enabled but you specify
values for Bucket, prefix and IncludeCookies, the values are
automatically deleted.
· IncludeCookies (boolean) – Specifies whether you want
CloudFront to include cookies in access logs, specify true for
IncludeCookies. If you choose to include cookies in logs,
CloudFront logs all cookies regardless of how you configure
the cache behaviors for this distribution. If you do not want to
include cookies when you create a distribution or if you want
to disable include cookies for an existing distribution, specify
false for IncludeCookies.
· Bucket (string) – The Amazon S3 bucket to store the access
logs in, for example, myawslogbucket.s3.amazonaws.com.
· Prefix (string) – An optional string that you want CloudFront
196 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
to prefix to the access log filenames for this distribution, for
example, myprefix/. If you want to enable logging, but you do
not want to specify a prefix, you still must include an empty
Prefix element in the Logging element.
· PriceClass (string) – A complex type that contains informa-
tion about price class for this distribution.
· Enabled (boolean) – Whether the distribution is enabled to
accept end user requests for content.
· ViewerCertificate (dict) – A complex type that contains in-
formation about viewer certificates for this distribution.
· IAMCertificateId (string) – If you want viewers to use
HTTPS to request your objects and you’re using an al-
ternate domain name in your object URLs (for example,
https://example.com/logo.jpg), specify the IAM certificate
identifier of the custom viewer certificate for this distribution.
Specify either this value or CloudFrontDefaultCertificate.
· CloudFrontDefaultCertificate (boolean) – If you
want viewers to use HTTPS to request your objects
and you’re using the CloudFront domain name of
your distribution in your object URLs (for example,
https://d111111abcdef8.cloudfront.net/logo.jpg), set to true.
Omit this value if you are setting an IAMCertificateId.
· SSLSupportMethod (string) – If you specify a value for
IAMCertificateId, you must also specify how you want
CloudFront to serve HTTPS requests. Valid values are vip and
sni-only. If you specify vip, CloudFront uses dedicated IP ad-
dresses for your content and can respond to HTTPS requests
from any viewer. However, you must request permission to
use this feature, and you incur additional monthly charges. If
you specify sni-only, CloudFront can only respond to HTTPS
requests from viewers that support Server Name Indication
(SNI). All modern browsers support SNI, but some browsers
still in use don’t support SNI. Do not specify a value for
SSLSupportMethod if you specified true for CloudFrontDe-
faultCertificate.
· MinimumProtocolVersion (string) – Specify the minimum
version of the SSL protocol that you want CloudFront to use,
SSLv3 or TLSv1, for HTTPS connections. CloudFront will
serve your objects only to browsers or devices that support at
least the SSL version that you specify. The TLSv1 protocol is
more secure, so we recommend that you specify SSLv3 only
if your users are using browsers or devices that don’t support
TLSv1. If you’re using a custom certificate (if you specify a
value for IAMCertificateId) and if you’re using dedicated IP
(if you specify vip for SSLSupportMethod), you can choose
SSLv3 or TLSv1 as the MinimumProtocolVersion. If you’re
using a custom certificate (if you specify a value for IAM-
CertificateId) and if you’re using SNI (if you specify sni-only
for SSLSupportMethod), you must specify TLSv1 for Mini-
mumProtocolVersion.
· Restrictions (dict) – A complex type that identifies ways in
which you want to restrict distribution of your content.
· GeoRestriction (dict) – A complex type that controls the
countries in which your content is distributed. For more in-
3.1. Services 197
Boto3 Documentation, Release 1.1.4
formation about geo restriction, go to Customizing Error Re-
sponses in the Amazon CloudFront Developer Guide. Cloud-
Front determines the location of your users using MaxMind
GeoIP databases. For information about the accuracy of these
databases, see How accurate are your GeoIP databases? on
the MaxMind website.
· RestrictionType (string) – The method that you want to use
to restrict distribution of your content by country: - none: No
geo restriction is enabled, meaning access to content is not
restricted by client geo location. - blacklist: The Location el-
ements specify the countries in which you do not want Cloud-
Front to distribute your content. - whitelist: The Location el-
ements specify the countries in which you want CloudFront
to distribute your content.
· Quantity (integer) – When geo restriction is enabled, this is
the number of countries in your whitelist or blacklist. Other-
wise, when it is not enabled, Quantity is 0, and you can omit
Items.
· Items (list) – A complex type that contains a Location ele-
ment for each country in which you want CloudFront either to
distribute your content (whitelist) or not distribute your con-
tent (blacklist). The Location element is a two-letter, upper-
case country code for a country that you want to include in
your blacklist or whitelist. Include one Location element for
each country. CloudFront and MaxMind both use ISO 3166
country codes. For the current list of countries and the cor-
responding codes, see ISO 3166-1-alpha-2 code on the Inter-
national Organization for Standardization website. You can
also refer to the country list in the CloudFront console, which
includes both country names and codes.
· (string) –
– Location (string) – The fully qualified URI of the
new distribution resource just created. For ex-
ample: https://cloudfront.amazonaws.com/2010-11-
01/distribution/EDFDVBD632BHDS5.
– ETag (string) – The current version of the distribution created.
create_invalidation(**kwargs)
Create a new invalidation.
Request Syntax
response = client.create_invalidation(
DistributionId='string',
InvalidationBatch={
'Paths': {
'Quantity': 123,
'Items': [
'string',
]
},
'CallerReference': 'string'
}
)
Parameters
198 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• DistributionId (string) – [REQUIRED] The distribution’s id.
• InvalidationBatch (dict) – [REQUIRED] The batch information for the invali-
dation.
– Paths (dict) – [REQUIRED] The path of the object to invalidate. The
path is relative to the distribution and must begin with a slash (/). You
must enclose each invalidation object with the Path element tags. If the
path includes non-ASCII characters or unsafe characters as defined in RFC
1783 (http://www.ietf.org/rfc/rfc1738.txt), URL encode those characters.
Do not URL encode any other characters in the path, or CloudFront will
not invalidate the old version of the updated object.
* Quantity (integer) – [REQUIRED] The number of objects that you
want to invalidate.
* Items (list) – A complex type that contains a list of the objects that
you want to invalidate.
· (string) –
– CallerReference (string) – [REQUIRED] A unique name that ensures
the request can’t be replayed. If the CallerReference is new (no matter
the content of the Path object), a new distribution is created. If the Caller-
Reference is a value you already sent in a previous request to create an
invalidation batch, and the content of each Path element is identical to the
original request, the response includes the same information returned to
the original request. If the CallerReference is a value you already sent
in a previous request to create a distribution but the content of any Path
is different from the original request, CloudFront returns an Invalidation-
BatchAlreadyExists error.
Return type dict
Returns
Response Syntax
{
'Location': 'string',
'Invalidation': {
'Id': 'string',
'Status': 'string',
'CreateTime': datetime(2015, 1, 1),
'InvalidationBatch': {
'Paths': {
'Quantity': 123,
'Items': [
'string',
]
},
'CallerReference': 'string'
}
}
}
Response Structure
• (dict) – The returned result of the corresponding request.
– Location (string) – The fully qualified URI of the distribution and invali-
dation batch request, including the Invalidation ID.
– Invalidation (dict) – The invalidation’s information.
* Id (string) – The identifier for the invalidation request. For example:
IDFDVBD632BHDS5.
3.1. Services 199
Boto3 Documentation, Release 1.1.4
* Status (string) – The status of the invalidation request. When the
invalidation batch is finished, the status is Completed.
* CreateTime (datetime) – The date and time the invalidation request
was first made.
* InvalidationBatch (dict) – The current invalidation information for
the batch request.
· Paths (dict) – The path of the object to invalidate. The
path is relative to the distribution and must begin with a
slash (/). You must enclose each invalidation object with
the Path element tags. If the path includes non-ASCII
characters or unsafe characters as defined in RFC 1783
(http://www.ietf.org/rfc/rfc1738.txt), URL encode those char-
acters. Do not URL encode any other characters in the path,
or CloudFront will not invalidate the old version of the up-
dated object.
· Quantity (integer) – The number of objects that you want to
invalidate.
· Items (list) – A complex type that contains a list of the objects
that you want to invalidate.
· (string) –
· CallerReference (string) – A unique name that ensures the
request can’t be replayed. If the CallerReference is new (no
matter the content of the Path object), a new distribution is
created. If the CallerReference is a value you already sent
in a previous request to create an invalidation batch, and the
content of each Path element is identical to the original re-
quest, the response includes the same information returned to
the original request. If the CallerReference is a value you al-
ready sent in a previous request to create a distribution but
the content of any Path is different from the original request,
CloudFront returns an InvalidationBatchAlreadyExists error.
create_streaming_distribution(**kwargs)
Create a new streaming distribution.
Request Syntax
response = client.create_streaming_distribution(
StreamingDistributionConfig={
'CallerReference': 'string',
'S3Origin': {
'DomainName': 'string',
'OriginAccessIdentity': 'string'
},
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
200 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False
}
)
Parameters StreamingDistributionConfig (dict) – [REQUIRED] The streaming distribu-
tion’s configuration information.
• CallerReference (string) – [REQUIRED] A unique number that ensures the
request can’t be replayed. If the CallerReference is new (no matter the content of
the StreamingDistributionConfig object), a new streaming distribution is created.
If the CallerReference is a value you already sent in a previous request to create
a streaming distribution, and the content of the StreamingDistributionConfig is
identical to the original request (ignoring white space), the response includes the
same information returned to the original request. If the CallerReference is a
value you already sent in a previous request to create a streaming distribution
but the content of the StreamingDistributionConfig is different from the original
request, CloudFront returns a DistributionAlreadyExists error.
• S3Origin (dict) – [REQUIRED] A complex type that contains information
about the Amazon S3 bucket from which you want CloudFront to get your media
files for distribution.
– DomainName (string) – [REQUIRED] The DNS name of the S3 origin.
– OriginAccessIdentity (string) – [REQUIRED] Your S3 origin’s origin
access identity.
• Aliases (dict) – A complex type that contains information about CNAMEs (al-
ternate domain names), if any, for this streaming distribution.
– Quantity (integer) – [REQUIRED] The number of CNAMEs, if any, for
this distribution.
– Items (list) – Optional: A complex type that contains CNAME elements,
if any, for this distribution. If Quantity is 0, you can omit Items.
* (string) –
• Comment (string) – [REQUIRED] Any comments you want to include about
the streaming distribution.
• Logging (dict) – A complex type that controls whether access logs are written
for the streaming distribution.
– Enabled (boolean) – [REQUIRED] Specifies whether you want Cloud-
Front to save access logs to an Amazon S3 bucket. If you do not want
to enable logging when you create a streaming distribution or if you want
to disable logging for an existing streaming distribution, specify false for
Enabled, and specify empty Bucket and Prefix elements. If you specify
false for Enabled but you specify values for Bucket and Prefix, the values
are automatically deleted.
– Bucket (string) – [REQUIRED] The Amazon S3 bucket to store the ac-
cess logs in, for example, myawslogbucket.s3.amazonaws.com.
– Prefix (string) – [REQUIRED] An optional string that you want Cloud-
Front to prefix to the access log filenames for this streaming distribution,
for example, myprefix/. If you want to enable logging, but you do not want
to specify a prefix, you still must include an empty Prefix element in the
Logging element.
3.1. Services 201
Boto3 Documentation, Release 1.1.4
• TrustedSigners (dict) – [REQUIRED] A complex type that specifies the AWS
accounts, if any, that you want to allow to create signed URLs for private con-
tent. If you want to require signed URLs in requests for objects in the target ori-
gin that match the PathPattern for this cache behavior, specify true for Enabled,
and specify the applicable values for Quantity and Items. For more information,
go to Using a Signed URL to Serve Private Content in the Amazon CloudFront
Developer Guide. If you don’t want to require signed URLs in requests for ob-
jects that match PathPattern, specify false for Enabled and 0 for Quantity. Omit
Items. To add, change, or remove one or more trusted signers, change Enabled
to true (if it’s currently false), change Quantity as applicable, and specify all of
the trusted signers that you want to include in the updated distribution.
– Enabled (boolean) – [REQUIRED] Specifies whether you want to re-
quire end users to use signed URLs to access the files specified by Path-
Pattern and TargetOriginId.
– Quantity (integer) – [REQUIRED] The number of trusted signers for this
cache behavior.
– Items (list) – Optional: A complex type that contains trusted signers for
this cache behavior. If Quantity is 0, you can omit Items.
* (string) –
• PriceClass (string) – A complex type that contains information about price class
for this streaming distribution.
• Enabled (boolean) – [REQUIRED] Whether the streaming distribution is en-
abled to accept end user requests for content.
Return type dict
Returns
Response Syntax
{
'StreamingDistribution': {
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'DomainName': 'string',
'ActiveTrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
{
'AwsAccountNumber': 'string',
'KeyPairIds': {
'Quantity': 123,
'Items': [
'string',
]
}
},
]
},
'StreamingDistributionConfig': {
'CallerReference': 'string',
'S3Origin': {
'DomainName': 'string',
'OriginAccessIdentity': 'string'
},
'Aliases': {
202 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Quantity': 123,
'Items': [
'string',
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False
}
},
'Location': 'string',
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– StreamingDistribution (dict) – The streaming distribution’s information.
* Id (string) – The identifier for the streaming distribution. For exam-
ple: EGTXBD79H29TRA8.
* Status (string) – The current status of the streaming distribution.
When the status is Deployed, the distribution’s information is fully
propagated throughout the Amazon CloudFront system.
* LastModifiedTime (datetime) – The date and time the distribution
was last modified.
* DomainName (string) – The domain name corre-
sponding to the streaming distribution. For example:
s5c39gqb8ow64r.cloudfront.net.
* ActiveTrustedSigners (dict) – CloudFront automatically adds this
element to the response only if you’ve set up the distribution to serve
private content with signed URLs. The element lists the key pair IDs
that CloudFront is aware of for each trusted signer. The Signer child
element lists the AWS account number of the trusted signer (or an
empty Self element if the signer is you). The Signer element also
includes the IDs of any active key pairs associated with the trusted
signer’s AWS account. If no KeyPairId element appears for a Signer,
that signer can’t create working signed URLs.
· Enabled (boolean) – Each active trusted signer.
· Quantity (integer) – The number of unique trusted signers
included in all cache behaviors. For example, if three cache
behaviors all list the same three AWS accounts, the value of
Quantity for ActiveTrustedSigners will be 3.
· Items (list) – A complex type that contains one Signer com-
plex type for each unique trusted signer that is specified in the
TrustedSigners complex type, including trusted signers in the
3.1. Services 203
Boto3 Documentation, Release 1.1.4
default cache behavior and in all of the other cache behaviors.
· (dict) – A complex type that lists the AWS accounts that were
included in the TrustedSigners complex type, as well as their
active CloudFront key pair IDs, if any.
· AwsAccountNumber (string) – Specifies an AWS account
that can create signed URLs. Values: self, which indicates
that the AWS account that was used to create the distribution
can created signed URLs, or an AWS account number. Omit
the dashes in the account number.
· KeyPairIds (dict) – A complex type that lists the active
CloudFront key pairs, if any, that are associated with AwsAc-
countNumber.
· Quantity (integer) – The number of active CloudFront key
pairs for AwsAccountNumber.
· Items (list) – A complex type that lists the active CloudFront
key pairs, if any, that are associated with AwsAccountNum-
ber.
· (string) –
* StreamingDistributionConfig (dict) – The current configuration
information for the streaming distribution.
· CallerReference (string) – A unique number that ensures
the request can’t be replayed. If the CallerReference is new
(no matter the content of the StreamingDistributionConfig ob-
ject), a new streaming distribution is created. If the Caller-
Reference is a value you already sent in a previous request to
create a streaming distribution, and the content of the Stream-
ingDistributionConfig is identical to the original request (ig-
noring white space), the response includes the same informa-
tion returned to the original request. If the CallerReference
is a value you already sent in a previous request to create a
streaming distribution but the content of the StreamingDis-
tributionConfig is different from the original request, Cloud-
Front returns a DistributionAlreadyExists error.
· S3Origin (dict) – A complex type that contains information
about the Amazon S3 bucket from which you want Cloud-
Front to get your media files for distribution.
· DomainName (string) – The DNS name of the S3 origin.
· OriginAccessIdentity (string) – Your S3 origin’s origin ac-
cess identity.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this
streaming distribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· Comment (string) – Any comments you want to include
about the streaming distribution.
· Logging (dict) – A complex type that controls whether access
logs are written for the streaming distribution.
· Enabled (boolean) – Specifies whether you want CloudFront
to save access logs to an Amazon S3 bucket. If you do not
204 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
want to enable logging when you create a streaming distribu-
tion or if you want to disable logging for an existing stream-
ing distribution, specify false for Enabled, and specify empty
Bucket and Prefix elements. If you specify false for Enabled
but you specify values for Bucket and Prefix, the values are
automatically deleted.
· Bucket (string) – The Amazon S3 bucket to store the access
logs in, for example, myawslogbucket.s3.amazonaws.com.
· Prefix (string) – An optional string that you want CloudFront
to prefix to the access log filenames for this streaming distri-
bution, for example, myprefix/. If you want to enable logging,
but you do not want to specify a prefix, you still must include
an empty Prefix element in the Logging element.
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· PriceClass (string) – A complex type that contains informa-
tion about price class for this streaming distribution.
· Enabled (boolean) – Whether the streaming distribution is
enabled to accept end user requests for content.
– Location (string) – The fully qualified URI of the new
streaming distribution resource just created. For exam-
ple: https://cloudfront.amazonaws.com/2010-11-01/streaming-
distribution/EGTXBD79H29TRA8.
– ETag (string) – The current version of the streaming distribution created.
delete_cloud_front_origin_access_identity(**kwargs)
Delete an origin access identity.
Request Syntax
response = client.delete_cloud_front_origin_access_identity(
Id='string',
IfMatch='string'
)
3.1. Services 205
Boto3 Documentation, Release 1.1.4
Parameters
• Id (string) – [REQUIRED] The origin access identity’s id.
• IfMatch (string) – The value of the ETag header you received from a previous
GET or PUT request. For example: E2QWRUHAPOMQZL.
Returns None
delete_distribution(**kwargs)
Delete a distribution.
Request Syntax
response = client.delete_distribution(
Id='string',
IfMatch='string'
)
Parameters
• Id (string) – [REQUIRED] The distribution id.
• IfMatch (string) – The value of the ETag header you received when you disabled
the distribution. For example: E2QWRUHAPOMQZL.
Returns None
delete_streaming_distribution(**kwargs)
Delete a streaming distribution.
Request Syntax
response = client.delete_streaming_distribution(
Id='string',
IfMatch='string'
)
Parameters
• Id (string) – [REQUIRED] The distribution id.
• IfMatch (string) – The value of the ETag header you received when you disabled
the streaming distribution. For example: E2QWRUHAPOMQZL.
Returns None
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_cloud_front_origin_access_identity(**kwargs)
Get the information about an origin access identity.
Request Syntax
response = client.get_cloud_front_origin_access_identity(
Id='string'
)
Parameters Id (string) – [REQUIRED] The identity’s id.
206 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'CloudFrontOriginAccessIdentity': {
'Id': 'string',
'S3CanonicalUserId': 'string',
'CloudFrontOriginAccessIdentityConfig': {
'CallerReference': 'string',
'Comment': 'string'
}
},
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– CloudFrontOriginAccessIdentity (dict) – The origin access identity’s in-
formation.
* Id (string) – The ID for the origin access identity. For example:
E74FTE3AJFJ256A.
* S3CanonicalUserId (string) – The Amazon S3 canonical user ID
for the origin access identity, which you use when giving the origin
access identity read permission to an object in Amazon S3.
* CloudFrontOriginAccessIdentityConfig (dict) – The current con-
figuration information for the identity.
· CallerReference (string) – A unique number that ensures
the request can’t be replayed. If the CallerReference is new
(no matter the content of the CloudFrontOriginAccessIdenti-
tyConfig object), a new origin access identity is created. If the
CallerReference is a value you already sent in a previous re-
quest to create an identity, and the content of the CloudFron-
tOriginAccessIdentityConfig is identical to the original re-
quest (ignoring white space), the response includes the same
information returned to the original request. If the CallerRef-
erence is a value you already sent in a previous request to cre-
ate an identity but the content of the CloudFrontOriginAcces-
sIdentityConfig is different from the original request, Cloud-
Front returns a CloudFrontOriginAccessIdentityAlreadyEx-
ists error.
· Comment (string) – Any comments you want to include
about the origin access identity.
– ETag (string) – The current version of the origin access identity’s infor-
mation. For example: E2QWRUHAPOMQZL.
get_cloud_front_origin_access_identity_config(**kwargs)
Get the configuration information about an origin access identity.
Request Syntax
response = client.get_cloud_front_origin_access_identity_config(
Id='string'
)
Parameters Id (string) – [REQUIRED] The identity’s id.
3.1. Services 207
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'CloudFrontOriginAccessIdentityConfig': {
'CallerReference': 'string',
'Comment': 'string'
},
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– CloudFrontOriginAccessIdentityConfig (dict) – The origin access iden-
tity’s configuration information.
* CallerReference (string) – A unique number that ensures the re-
quest can’t be replayed. If the CallerReference is new (no matter
the content of the CloudFrontOriginAccessIdentityConfig object),
a new origin access identity is created. If the CallerReference is a
value you already sent in a previous request to create an identity, and
the content of the CloudFrontOriginAccessIdentityConfig is identi-
cal to the original request (ignoring white space), the response in-
cludes the same information returned to the original request. If the
CallerReference is a value you already sent in a previous request
to create an identity but the content of the CloudFrontOriginAcces-
sIdentityConfig is different from the original request, CloudFront
returns a CloudFrontOriginAccessIdentityAlreadyExists error.
* Comment (string) – Any comments you want to include about the
origin access identity.
– ETag (string) – The current version of the configuration. For example:
E2QWRUHAPOMQZL.
get_distribution(**kwargs)
Get the information about a distribution.
Request Syntax
response = client.get_distribution(
Id='string'
)
Parameters Id (string) – [REQUIRED] The distribution’s id.
Return type dict
Returns
Response Syntax
{
'Distribution': {
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'InProgressInvalidationBatches': 123,
'DomainName': 'string',
'ActiveTrustedSigners': {
208 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Enabled': True|False,
'Quantity': 123,
'Items': [
{
'AwsAccountNumber': 'string',
'KeyPairIds': {
'Quantity': 123,
'Items': [
'string',
]
}
},
]
},
'DistributionConfig': {
'CallerReference': 'string',
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'DefaultRootObject': 'string',
'Origins': {
'Quantity': 123,
'Items': [
{
'Id': 'string',
'DomainName': 'string',
'OriginPath': 'string',
'S3OriginConfig': {
'OriginAccessIdentity': 'string'
},
'CustomOriginConfig': {
'HTTPPort': 123,
'HTTPSPort': 123,
'OriginProtocolPolicy': 'http-only'|'match-viewer'
}
},
]
},
'DefaultCacheBehavior': {
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
3.1. Services 209
Boto3 Documentation, Release 1.1.4
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-http
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
'CacheBehaviors': {
'Quantity': 123,
'Items': [
{
'PathPattern': 'string',
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
210 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELET
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'D
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
]
},
'CustomErrorResponses': {
'Quantity': 123,
'Items': [
{
'ErrorCode': 123,
'ResponsePagePath': 'string',
'ResponseCode': 'string',
'ErrorCachingMinTTL': 123
},
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'IncludeCookies': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False,
'ViewerCertificate': {
'IAMCertificateId': 'string',
'CloudFrontDefaultCertificate': True|False,
'SSLSupportMethod': 'sni-only'|'vip',
'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
},
'Restrictions': {
'GeoRestriction': {
'RestrictionType': 'blacklist'|'whitelist'|'none',
'Quantity': 123,
'Items': [
'string',
]
}
}
}
},
3.1. Services 211
Boto3 Documentation, Release 1.1.4
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– Distribution (dict) – The distribution’s information.
* Id (string) – The identifier for the distribution. For example: EDFD-
VBD632BHDS5.
* Status (string) – This response element indicates the current status
of the distribution. When the status is Deployed, the distribution’s
information is fully propagated throughout the Amazon CloudFront
system.
* LastModifiedTime (datetime) – The date and time the distribution
was last modified.
* InProgressInvalidationBatches (integer) – The number of invali-
dation batches currently in progress.
* DomainName (string) – The domain name corresponding to the
distribution. For example: d604721fxaaqy9.cloudfront.net.
* ActiveTrustedSigners (dict) – CloudFront automatically adds this
element to the response only if you’ve set up the distribution to serve
private content with signed URLs. The element lists the key pair IDs
that CloudFront is aware of for each trusted signer. The Signer child
element lists the AWS account number of the trusted signer (or an
empty Self element if the signer is you). The Signer element also
includes the IDs of any active key pairs associated with the trusted
signer’s AWS account. If no KeyPairId element appears for a Signer,
that signer can’t create working signed URLs.
· Enabled (boolean) – Each active trusted signer.
· Quantity (integer) – The number of unique trusted signers
included in all cache behaviors. For example, if three cache
behaviors all list the same three AWS accounts, the value of
Quantity for ActiveTrustedSigners will be 3.
· Items (list) – A complex type that contains one Signer com-
plex type for each unique trusted signer that is specified in the
TrustedSigners complex type, including trusted signers in the
default cache behavior and in all of the other cache behaviors.
· (dict) – A complex type that lists the AWS accounts that were
included in the TrustedSigners complex type, as well as their
active CloudFront key pair IDs, if any.
· AwsAccountNumber (string) – Specifies an AWS account
that can create signed URLs. Values: self, which indicates
that the AWS account that was used to create the distribution
can created signed URLs, or an AWS account number. Omit
the dashes in the account number.
· KeyPairIds (dict) – A complex type that lists the active
CloudFront key pairs, if any, that are associated with AwsAc-
countNumber.
· Quantity (integer) – The number of active CloudFront key
pairs for AwsAccountNumber.
· Items (list) – A complex type that lists the active CloudFront
key pairs, if any, that are associated with AwsAccountNum-
ber.
· (string) –
* DistributionConfig (dict) – The current configuration information
212 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
for the distribution.
· CallerReference (string) – A unique number that ensures the
request can’t be replayed. If the CallerReference is new (no
matter the content of the DistributionConfig object), a new
distribution is created. If the CallerReference is a value you
already sent in a previous request to create a distribution,
and the content of the DistributionConfig is identical to the
original request (ignoring white space), the response includes
the same information returned to the original request. If the
CallerReference is a value you already sent in a previous re-
quest to create a distribution but the content of the Distribu-
tionConfig is different from the original request, CloudFront
returns a DistributionAlreadyExists error.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this dis-
tribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· DefaultRootObject (string) – The object that you want
CloudFront to return (for example, index.html) when an
end user requests the root URL for your distribution
(http://www.example.com) instead of an object in your dis-
tribution (http://www.example.com/index.html). Specifying
a default root object avoids exposing the contents of your dis-
tribution. If you don’t want to specify a default root object
when you create a distribution, include an empty Default-
RootObject element. To delete the default root object from
an existing distribution, update the distribution configuration
and include an empty DefaultRootObject element. To replace
the default root object, update the distribution configuration
and specify the new object.
· Origins (dict) – A complex type that contains information
about origins for this distribution.
· Quantity (integer) – The number of origins for this distribu-
tion.
· Items (list) – A complex type that contains origins for this
distribution.
· (dict) – A complex type that describes the Amazon S3 bucket
or the HTTP server (for example, a web server) from which
CloudFront gets your files.You must create at least one origin.
· Id (string) – A unique identifier for the origin. The value of
Id must be unique within the distribution. You use the value
of Id when you create a cache behavior. The Id identifies the
origin that CloudFront routes a request to when the request
matches the path pattern for that cache behavior.
· DomainName (string) – Amazon S3 origins: The DNS name
of the Amazon S3 bucket from which you want Cloud-
Front to get objects for this origin, for example, myaws-
bucket.s3.amazonaws.com. Custom origins: The DNS do-
main name for the HTTP server from which you want
3.1. Services 213
Boto3 Documentation, Release 1.1.4
CloudFront to get objects for this origin, for example,
www.example.com.
· OriginPath (string) – An optional element that causes Cloud-
Front to request your content from a directory in your Ama-
zon S3 bucket or your custom origin. When you include the
OriginPath element, specify the directory name, beginning
with a /. CloudFront appends the directory name to the value
of DomainName.
· S3OriginConfig (dict) – A complex type that contains infor-
mation about the Amazon S3 origin. If the origin is a custom
origin, use the CustomOriginConfig element instead.
· OriginAccessIdentity (string) – The CloudFront origin ac-
cess identity to associate with the origin. Use an origin ac-
cess identity to configure the origin so that end users can only
access objects in an Amazon S3 bucket through CloudFront.
If you want end users to be able to access objects using ei-
ther the CloudFront URL or the Amazon S3 URL, specify
an empty OriginAccessIdentity element. To delete the origin
access identity from an existing distribution, update the distri-
bution configuration and include an empty OriginAccessIden-
tity element. To replace the origin access identity, update the
distribution configuration and specify the new origin access
identity. Use the format origin-access-identity/cloudfront/Id
where Id is the value that CloudFront returned in the Id ele-
ment when you created the origin access identity.
· CustomOriginConfig (dict) – A complex type that contains
information about a custom origin. If the origin is an Amazon
S3 bucket, use the S3OriginConfig element instead.
· HTTPPort (integer) – The HTTP port the custom origin lis-
tens on.
· HTTPSPort (integer) – The HTTPS port the custom origin
listens on.
· OriginProtocolPolicy (string) – The origin protocol policy
to apply to your origin.
· DefaultCacheBehavior (dict) – A complex type that de-
scribes the default cache behavior if you do not specify a
CacheBehavior element or if files don’t match any of the val-
ues of PathPattern in CacheBehavior elements.You must cre-
ate exactly one default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
214 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
3.1. Services 215
Boto3 Documentation, Release 1.1.4
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
216 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CacheBehaviors (dict) – A complex type that contains zero
or more CacheBehavior elements.
· Quantity (integer) – The number of cache behaviors for this
distribution.
· Items (list) – Optional: A complex type that contains cache
behaviors for this distribution. If Quantity is 0, you can omit
Items.
· (dict) – A complex type that describes how CloudFront pro-
cesses requests. You can create up to 10 cache behav-
iors.You must create at least as many cache behaviors (in-
cluding the default cache behavior) as you have origins if you
want CloudFront to distribute objects from all of the origins.
Each cache behavior specifies the one origin from which you
want CloudFront to get objects. If you have two origins and
only the default cache behavior, the default cache behavior
will cause CloudFront to get objects from one of the ori-
gins, but the other origin will never be used. If you don’t
want to specify any cache behaviors, include only an empty
CacheBehaviors element. Don’t include an empty CacheBe-
havior element, or CloudFront returns a MalformedXML er-
ror. To delete all cache behaviors in an existing distribu-
tion, update the distribution configuration and include only an
empty CacheBehaviors element. To add, change, or remove
one or more cache behaviors, update the distribution configu-
ration and specify all of the cache behaviors that you want to
include in the updated distribution.
· PathPattern (string) – The pattern (for example, im-
ages/*.jpg) that specifies which requests you want this cache
behavior to apply to. When CloudFront receives an end-user
request, the requested path is compared with path patterns in
the order in which cache behaviors are listed in the distribu-
tion. The path pattern for the default cache behavior is * and
cannot be changed. If the request for an object does not match
the path pattern for any cache behaviors, CloudFront applies
the behavior in the default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
3.1. Services 217
Boto3 Documentation, Release 1.1.4
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
218 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
3.1. Services 219
Boto3 Documentation, Release 1.1.4
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CustomErrorResponses (dict) – A complex type that con-
tains zero or more CustomErrorResponse elements.
· Quantity (integer) – The number of custom error responses
for this distribution.
· Items (list) – Optional: A complex type that contains custom
error responses for this distribution. If Quantity is 0, you can
omit Items.
· (dict) – A complex type that describes how you’d prefer
CloudFront to respond to requests that result in either a 4xx or
5xx response. You can control whether a custom error page
should be displayed, what the desired response code should
be for this error page and how long should the error response
be cached by CloudFront. If you don’t want to specify any
custom error responses, include only an empty CustomEr-
rorResponses element. To delete all custom error responses
in an existing distribution, update the distribution configura-
tion and include only an empty CustomErrorResponses ele-
ment. To add, change, or remove one or more custom error
responses, update the distribution configuration and specify
all of the custom error responses that you want to include in
the updated distribution.
· ErrorCode (integer) – The 4xx or 5xx HTTP status code that
you want to customize. For a list of HTTP status codes that
you can customize, see CloudFront documentation.
· ResponsePagePath (string) – The path of the custom error
page (for example, /custom_404.html). The path is relative
220 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
to the distribution and must begin with a slash (/). If the path
includes any non-ASCII characters or unsafe characters as de-
fined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL
encode those characters. Do not URL encode any other char-
acters in the path, or CloudFront will not return the custom
error page to the viewer.
· ResponseCode (string) – The HTTP status code that you
want CloudFront to return with the custom error page to the
viewer. For a list of HTTP status codes that you can replace,
see CloudFront Documentation.
· ErrorCachingMinTTL (integer) – The minimum amount of
time you want HTTP error codes to stay in CloudFront caches
before CloudFront queries your origin to see whether the ob-
ject has been updated. You can specify a value from 0 to
31,536,000.
· Comment (string) – Any comments you want to include
about the distribution.
· Logging (dict) – A complex type that controls whether access
logs are written for the distribution.
· Enabled (boolean) – Specifies whether you want CloudFront
to save access logs to an Amazon S3 bucket. If you do not
want to enable logging when you create a distribution or if
you want to disable logging for an existing distribution, spec-
ify false for Enabled, and specify empty Bucket and Prefix
elements. If you specify false for Enabled but you specify
values for Bucket, prefix and IncludeCookies, the values are
automatically deleted.
· IncludeCookies (boolean) – Specifies whether you want
CloudFront to include cookies in access logs, specify true for
IncludeCookies. If you choose to include cookies in logs,
CloudFront logs all cookies regardless of how you configure
the cache behaviors for this distribution. If you do not want to
include cookies when you create a distribution or if you want
to disable include cookies for an existing distribution, specify
false for IncludeCookies.
· Bucket (string) – The Amazon S3 bucket to store the access
logs in, for example, myawslogbucket.s3.amazonaws.com.
· Prefix (string) – An optional string that you want CloudFront
to prefix to the access log filenames for this distribution, for
example, myprefix/. If you want to enable logging, but you do
not want to specify a prefix, you still must include an empty
Prefix element in the Logging element.
· PriceClass (string) – A complex type that contains informa-
tion about price class for this distribution.
· Enabled (boolean) – Whether the distribution is enabled to
accept end user requests for content.
· ViewerCertificate (dict) – A complex type that contains in-
formation about viewer certificates for this distribution.
· IAMCertificateId (string) – If you want viewers to use
HTTPS to request your objects and you’re using an al-
ternate domain name in your object URLs (for example,
https://example.com/logo.jpg), specify the IAM certificate
identifier of the custom viewer certificate for this distribution.
Specify either this value or CloudFrontDefaultCertificate.
3.1. Services 221
Boto3 Documentation, Release 1.1.4
· CloudFrontDefaultCertificate (boolean) – If you
want viewers to use HTTPS to request your objects
and you’re using the CloudFront domain name of
your distribution in your object URLs (for example,
https://d111111abcdef8.cloudfront.net/logo.jpg), set to true.
Omit this value if you are setting an IAMCertificateId.
· SSLSupportMethod (string) – If you specify a value for
IAMCertificateId, you must also specify how you want
CloudFront to serve HTTPS requests. Valid values are vip and
sni-only. If you specify vip, CloudFront uses dedicated IP ad-
dresses for your content and can respond to HTTPS requests
from any viewer. However, you must request permission to
use this feature, and you incur additional monthly charges. If
you specify sni-only, CloudFront can only respond to HTTPS
requests from viewers that support Server Name Indication
(SNI). All modern browsers support SNI, but some browsers
still in use don’t support SNI. Do not specify a value for
SSLSupportMethod if you specified true for CloudFrontDe-
faultCertificate.
· MinimumProtocolVersion (string) – Specify the minimum
version of the SSL protocol that you want CloudFront to use,
SSLv3 or TLSv1, for HTTPS connections. CloudFront will
serve your objects only to browsers or devices that support at
least the SSL version that you specify. The TLSv1 protocol is
more secure, so we recommend that you specify SSLv3 only
if your users are using browsers or devices that don’t support
TLSv1. If you’re using a custom certificate (if you specify a
value for IAMCertificateId) and if you’re using dedicated IP
(if you specify vip for SSLSupportMethod), you can choose
SSLv3 or TLSv1 as the MinimumProtocolVersion. If you’re
using a custom certificate (if you specify a value for IAM-
CertificateId) and if you’re using SNI (if you specify sni-only
for SSLSupportMethod), you must specify TLSv1 for Mini-
mumProtocolVersion.
· Restrictions (dict) – A complex type that identifies ways in
which you want to restrict distribution of your content.
· GeoRestriction (dict) – A complex type that controls the
countries in which your content is distributed. For more in-
formation about geo restriction, go to Customizing Error Re-
sponses in the Amazon CloudFront Developer Guide. Cloud-
Front determines the location of your users using MaxMind
GeoIP databases. For information about the accuracy of these
databases, see How accurate are your GeoIP databases? on
the MaxMind website.
· RestrictionType (string) – The method that you want to use
to restrict distribution of your content by country: - none: No
geo restriction is enabled, meaning access to content is not
restricted by client geo location. - blacklist: The Location el-
ements specify the countries in which you do not want Cloud-
Front to distribute your content. - whitelist: The Location el-
ements specify the countries in which you want CloudFront
to distribute your content.
· Quantity (integer) – When geo restriction is enabled, this is
the number of countries in your whitelist or blacklist. Other-
222 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
wise, when it is not enabled, Quantity is 0, and you can omit
Items.
· Items (list) – A complex type that contains a Location ele-
ment for each country in which you want CloudFront either to
distribute your content (whitelist) or not distribute your con-
tent (blacklist). The Location element is a two-letter, upper-
case country code for a country that you want to include in
your blacklist or whitelist. Include one Location element for
each country. CloudFront and MaxMind both use ISO 3166
country codes. For the current list of countries and the cor-
responding codes, see ISO 3166-1-alpha-2 code on the Inter-
national Organization for Standardization website. You can
also refer to the country list in the CloudFront console, which
includes both country names and codes.
· (string) –
– ETag (string) – The current version of the distribution’s information. For
example: E2QWRUHAPOMQZL.
get_distribution_config(**kwargs)
Get the configuration information about a distribution.
Request Syntax
response = client.get_distribution_config(
Id='string'
)
Parameters Id (string) – [REQUIRED] The distribution’s id.
Return type dict
Returns
Response Syntax
{
'DistributionConfig': {
'CallerReference': 'string',
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'DefaultRootObject': 'string',
'Origins': {
'Quantity': 123,
'Items': [
{
'Id': 'string',
'DomainName': 'string',
'OriginPath': 'string',
'S3OriginConfig': {
'OriginAccessIdentity': 'string'
},
'CustomOriginConfig': {
'HTTPPort': 123,
'HTTPSPort': 123,
'OriginProtocolPolicy': 'http-only'|'match-viewer'
3.1. Services 223
Boto3 Documentation, Release 1.1.4
}
},
]
},
'DefaultCacheBehavior': {
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
'CacheBehaviors': {
'Quantity': 123,
'Items': [
{
'PathPattern': 'string',
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
224 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELET
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
]
},
'CustomErrorResponses': {
'Quantity': 123,
'Items': [
{
'ErrorCode': 123,
'ResponsePagePath': 'string',
'ResponseCode': 'string',
'ErrorCachingMinTTL': 123
},
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'IncludeCookies': True|False,
'Bucket': 'string',
3.1. Services 225
Boto3 Documentation, Release 1.1.4
'Prefix': 'string'
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False,
'ViewerCertificate': {
'IAMCertificateId': 'string',
'CloudFrontDefaultCertificate': True|False,
'SSLSupportMethod': 'sni-only'|'vip',
'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
},
'Restrictions': {
'GeoRestriction': {
'RestrictionType': 'blacklist'|'whitelist'|'none',
'Quantity': 123,
'Items': [
'string',
]
}
}
},
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– DistributionConfig (dict) – The distribution’s configuration information.
* CallerReference (string) – A unique number that ensures the re-
quest can’t be replayed. If the CallerReference is new (no matter
the content of the DistributionConfig object), a new distribution is
created. If the CallerReference is a value you already sent in a pre-
vious request to create a distribution, and the content of the Dis-
tributionConfig is identical to the original request (ignoring white
space), the response includes the same information returned to the
original request. If the CallerReference is a value you already sent in
a previous request to create a distribution but the content of the Dis-
tributionConfig is different from the original request, CloudFront
returns a DistributionAlreadyExists error.
* Aliases (dict) – A complex type that contains information about
CNAMEs (alternate domain names), if any, for this distribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
* DefaultRootObject (string) – The object that you want
CloudFront to return (for example, index.html) when an
end user requests the root URL for your distribution
(http://www.example.com) instead of an object in your distri-
bution (http://www.example.com/index.html). Specifying a default
root object avoids exposing the contents of your distribution. If you
don’t want to specify a default root object when you create a dis-
tribution, include an empty DefaultRootObject element. To delete
the default root object from an existing distribution, update the
distribution configuration and include an empty DefaultRootObject
226 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
element. To replace the default root object, update the distribution
configuration and specify the new object.
* Origins (dict) – A complex type that contains information about
origins for this distribution.
· Quantity (integer) – The number of origins for this distribu-
tion.
· Items (list) – A complex type that contains origins for this
distribution.
· (dict) – A complex type that describes the Amazon S3 bucket
or the HTTP server (for example, a web server) from which
CloudFront gets your files.You must create at least one origin.
· Id (string) – A unique identifier for the origin. The value of
Id must be unique within the distribution. You use the value
of Id when you create a cache behavior. The Id identifies the
origin that CloudFront routes a request to when the request
matches the path pattern for that cache behavior.
· DomainName (string) – Amazon S3 origins: The DNS name
of the Amazon S3 bucket from which you want Cloud-
Front to get objects for this origin, for example, myaws-
bucket.s3.amazonaws.com. Custom origins: The DNS do-
main name for the HTTP server from which you want
CloudFront to get objects for this origin, for example,
www.example.com.
· OriginPath (string) – An optional element that causes Cloud-
Front to request your content from a directory in your Ama-
zon S3 bucket or your custom origin. When you include the
OriginPath element, specify the directory name, beginning
with a /. CloudFront appends the directory name to the value
of DomainName.
· S3OriginConfig (dict) – A complex type that contains infor-
mation about the Amazon S3 origin. If the origin is a custom
origin, use the CustomOriginConfig element instead.
· OriginAccessIdentity (string) – The CloudFront origin ac-
cess identity to associate with the origin. Use an origin ac-
cess identity to configure the origin so that end users can only
access objects in an Amazon S3 bucket through CloudFront.
If you want end users to be able to access objects using ei-
ther the CloudFront URL or the Amazon S3 URL, specify
an empty OriginAccessIdentity element. To delete the origin
access identity from an existing distribution, update the distri-
bution configuration and include an empty OriginAccessIden-
tity element. To replace the origin access identity, update the
distribution configuration and specify the new origin access
identity. Use the format origin-access-identity/cloudfront/Id
where Id is the value that CloudFront returned in the Id ele-
ment when you created the origin access identity.
· CustomOriginConfig (dict) – A complex type that contains
information about a custom origin. If the origin is an Amazon
S3 bucket, use the S3OriginConfig element instead.
· HTTPPort (integer) – The HTTP port the custom origin lis-
tens on.
· HTTPSPort (integer) – The HTTPS port the custom origin
listens on.
· OriginProtocolPolicy (string) – The origin protocol policy
3.1. Services 227
Boto3 Documentation, Release 1.1.4
to apply to your origin.
* DefaultCacheBehavior (dict) – A complex type that describes the
default cache behavior if you do not specify a CacheBehavior el-
ement or if files don’t match any of the values of PathPattern in
CacheBehavior elements.You must create exactly one default cache
behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
228 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
3.1. Services 229
Boto3 Documentation, Release 1.1.4
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
* CacheBehaviors (dict) – A complex type that contains zero or more
CacheBehavior elements.
· Quantity (integer) – The number of cache behaviors for this
distribution.
· Items (list) – Optional: A complex type that contains cache
behaviors for this distribution. If Quantity is 0, you can omit
Items.
· (dict) – A complex type that describes how CloudFront pro-
cesses requests. You can create up to 10 cache behav-
iors.You must create at least as many cache behaviors (in-
cluding the default cache behavior) as you have origins if you
want CloudFront to distribute objects from all of the origins.
Each cache behavior specifies the one origin from which you
want CloudFront to get objects. If you have two origins and
only the default cache behavior, the default cache behavior
will cause CloudFront to get objects from one of the ori-
gins, but the other origin will never be used. If you don’t
230 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
want to specify any cache behaviors, include only an empty
CacheBehaviors element. Don’t include an empty CacheBe-
havior element, or CloudFront returns a MalformedXML er-
ror. To delete all cache behaviors in an existing distribu-
tion, update the distribution configuration and include only an
empty CacheBehaviors element. To add, change, or remove
one or more cache behaviors, update the distribution configu-
ration and specify all of the cache behaviors that you want to
include in the updated distribution.
· PathPattern (string) – The pattern (for example, im-
ages/*.jpg) that specifies which requests you want this cache
behavior to apply to. When CloudFront receives an end-user
request, the requested path is compared with path patterns in
the order in which cache behaviors are listed in the distribu-
tion. The path pattern for the default cache behavior is * and
cannot be changed. If the request for an object does not match
the path pattern for any cache behaviors, CloudFront applies
the behavior in the default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
3.1. Services 231
Boto3 Documentation, Release 1.1.4
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
232 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
* CustomErrorResponses (dict) – A complex type that contains zero
or more CustomErrorResponse elements.
· Quantity (integer) – The number of custom error responses
for this distribution.
· Items (list) – Optional: A complex type that contains custom
3.1. Services 233
Boto3 Documentation, Release 1.1.4
error responses for this distribution. If Quantity is 0, you can
omit Items.
· (dict) – A complex type that describes how you’d prefer
CloudFront to respond to requests that result in either a 4xx or
5xx response. You can control whether a custom error page
should be displayed, what the desired response code should
be for this error page and how long should the error response
be cached by CloudFront. If you don’t want to specify any
custom error responses, include only an empty CustomEr-
rorResponses element. To delete all custom error responses
in an existing distribution, update the distribution configura-
tion and include only an empty CustomErrorResponses ele-
ment. To add, change, or remove one or more custom error
responses, update the distribution configuration and specify
all of the custom error responses that you want to include in
the updated distribution.
· ErrorCode (integer) – The 4xx or 5xx HTTP status code that
you want to customize. For a list of HTTP status codes that
you can customize, see CloudFront documentation.
· ResponsePagePath (string) – The path of the custom error
page (for example, /custom_404.html). The path is relative
to the distribution and must begin with a slash (/). If the path
includes any non-ASCII characters or unsafe characters as de-
fined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL
encode those characters. Do not URL encode any other char-
acters in the path, or CloudFront will not return the custom
error page to the viewer.
· ResponseCode (string) – The HTTP status code that you
want CloudFront to return with the custom error page to the
viewer. For a list of HTTP status codes that you can replace,
see CloudFront Documentation.
· ErrorCachingMinTTL (integer) – The minimum amount of
time you want HTTP error codes to stay in CloudFront caches
before CloudFront queries your origin to see whether the ob-
ject has been updated. You can specify a value from 0 to
31,536,000.
* Comment (string) – Any comments you want to include about the
distribution.
* Logging (dict) – A complex type that controls whether access logs
are written for the distribution.
· Enabled (boolean) – Specifies whether you want CloudFront
to save access logs to an Amazon S3 bucket. If you do not
want to enable logging when you create a distribution or if
you want to disable logging for an existing distribution, spec-
ify false for Enabled, and specify empty Bucket and Prefix
elements. If you specify false for Enabled but you specify
values for Bucket, prefix and IncludeCookies, the values are
automatically deleted.
· IncludeCookies (boolean) – Specifies whether you want
CloudFront to include cookies in access logs, specify true for
IncludeCookies. If you choose to include cookies in logs,
CloudFront logs all cookies regardless of how you configure
the cache behaviors for this distribution. If you do not want to
include cookies when you create a distribution or if you want
234 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
to disable include cookies for an existing distribution, specify
false for IncludeCookies.
· Bucket (string) – The Amazon S3 bucket to store the access
logs in, for example, myawslogbucket.s3.amazonaws.com.
· Prefix (string) – An optional string that you want CloudFront
to prefix to the access log filenames for this distribution, for
example, myprefix/. If you want to enable logging, but you do
not want to specify a prefix, you still must include an empty
Prefix element in the Logging element.
* PriceClass (string) – A complex type that contains information
about price class for this distribution.
* Enabled (boolean) – Whether the distribution is enabled to accept
end user requests for content.
* ViewerCertificate (dict) – A complex type that contains informa-
tion about viewer certificates for this distribution.
· IAMCertificateId (string) – If you want viewers to use
HTTPS to request your objects and you’re using an al-
ternate domain name in your object URLs (for example,
https://example.com/logo.jpg), specify the IAM certificate
identifier of the custom viewer certificate for this distribution.
Specify either this value or CloudFrontDefaultCertificate.
· CloudFrontDefaultCertificate (boolean) – If you
want viewers to use HTTPS to request your objects
and you’re using the CloudFront domain name of
your distribution in your object URLs (for example,
https://d111111abcdef8.cloudfront.net/logo.jpg), set to true.
Omit this value if you are setting an IAMCertificateId.
· SSLSupportMethod (string) – If you specify a value for
IAMCertificateId, you must also specify how you want
CloudFront to serve HTTPS requests. Valid values are vip and
sni-only. If you specify vip, CloudFront uses dedicated IP ad-
dresses for your content and can respond to HTTPS requests
from any viewer. However, you must request permission to
use this feature, and you incur additional monthly charges. If
you specify sni-only, CloudFront can only respond to HTTPS
requests from viewers that support Server Name Indication
(SNI). All modern browsers support SNI, but some browsers
still in use don’t support SNI. Do not specify a value for
SSLSupportMethod if you specified true for CloudFrontDe-
faultCertificate.
· MinimumProtocolVersion (string) – Specify the minimum
version of the SSL protocol that you want CloudFront to use,
SSLv3 or TLSv1, for HTTPS connections. CloudFront will
serve your objects only to browsers or devices that support at
least the SSL version that you specify. The TLSv1 protocol is
more secure, so we recommend that you specify SSLv3 only
if your users are using browsers or devices that don’t support
TLSv1. If you’re using a custom certificate (if you specify a
value for IAMCertificateId) and if you’re using dedicated IP
(if you specify vip for SSLSupportMethod), you can choose
SSLv3 or TLSv1 as the MinimumProtocolVersion. If you’re
using a custom certificate (if you specify a value for IAM-
CertificateId) and if you’re using SNI (if you specify sni-only
for SSLSupportMethod), you must specify TLSv1 for Mini-
3.1. Services 235
Boto3 Documentation, Release 1.1.4
mumProtocolVersion.
* Restrictions (dict) – A complex type that identifies ways in which
you want to restrict distribution of your content.
· GeoRestriction (dict) – A complex type that controls the
countries in which your content is distributed. For more in-
formation about geo restriction, go to Customizing Error Re-
sponses in the Amazon CloudFront Developer Guide. Cloud-
Front determines the location of your users using MaxMind
GeoIP databases. For information about the accuracy of these
databases, see How accurate are your GeoIP databases? on
the MaxMind website.
· RestrictionType (string) – The method that you want to use
to restrict distribution of your content by country: - none: No
geo restriction is enabled, meaning access to content is not
restricted by client geo location. - blacklist: The Location el-
ements specify the countries in which you do not want Cloud-
Front to distribute your content. - whitelist: The Location el-
ements specify the countries in which you want CloudFront
to distribute your content.
· Quantity (integer) – When geo restriction is enabled, this is
the number of countries in your whitelist or blacklist. Other-
wise, when it is not enabled, Quantity is 0, and you can omit
Items.
· Items (list) – A complex type that contains a Location ele-
ment for each country in which you want CloudFront either to
distribute your content (whitelist) or not distribute your con-
tent (blacklist). The Location element is a two-letter, upper-
case country code for a country that you want to include in
your blacklist or whitelist. Include one Location element for
each country. CloudFront and MaxMind both use ISO 3166
country codes. For the current list of countries and the cor-
responding codes, see ISO 3166-1-alpha-2 code on the Inter-
national Organization for Standardization website. You can
also refer to the country list in the CloudFront console, which
includes both country names and codes.
· (string) –
– ETag (string) – The current version of the configuration. For example:
E2QWRUHAPOMQZL.
get_invalidation(**kwargs)
Get the information about an invalidation.
Request Syntax
response = client.get_invalidation(
DistributionId='string',
Id='string'
)
Parameters
• DistributionId (string) – [REQUIRED] The distribution’s id.
• Id (string) – [REQUIRED] The invalidation’s id.
Return type dict
Returns
Response Syntax
236 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'Invalidation': {
'Id': 'string',
'Status': 'string',
'CreateTime': datetime(2015, 1, 1),
'InvalidationBatch': {
'Paths': {
'Quantity': 123,
'Items': [
'string',
]
},
'CallerReference': 'string'
}
}
}
Response Structure
• (dict) – The returned result of the corresponding request.
– Invalidation (dict) – The invalidation’s information.
* Id (string) – The identifier for the invalidation request. For example:
IDFDVBD632BHDS5.
* Status (string) – The status of the invalidation request. When the
invalidation batch is finished, the status is Completed.
* CreateTime (datetime) – The date and time the invalidation request
was first made.
* InvalidationBatch (dict) – The current invalidation information for
the batch request.
· Paths (dict) – The path of the object to invalidate. The
path is relative to the distribution and must begin with a
slash (/). You must enclose each invalidation object with
the Path element tags. If the path includes non-ASCII
characters or unsafe characters as defined in RFC 1783
(http://www.ietf.org/rfc/rfc1738.txt), URL encode those char-
acters. Do not URL encode any other characters in the path,
or CloudFront will not invalidate the old version of the up-
dated object.
· Quantity (integer) – The number of objects that you want to
invalidate.
· Items (list) – A complex type that contains a list of the objects
that you want to invalidate.
· (string) –
· CallerReference (string) – A unique name that ensures the
request can’t be replayed. If the CallerReference is new (no
matter the content of the Path object), a new distribution is
created. If the CallerReference is a value you already sent
in a previous request to create an invalidation batch, and the
content of each Path element is identical to the original re-
quest, the response includes the same information returned to
the original request. If the CallerReference is a value you al-
ready sent in a previous request to create a distribution but
the content of any Path is different from the original request,
CloudFront returns an InvalidationBatchAlreadyExists error.
get_paginator(operation_name)
3.1. Services 237
Boto3 Documentation, Release 1.1.4
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_streaming_distribution(**kwargs)
Get the information about a streaming distribution.
Request Syntax
response = client.get_streaming_distribution(
Id='string'
)
Parameters Id (string) – [REQUIRED] The streaming distribution’s id.
Return type dict
Returns
Response Syntax
{
'StreamingDistribution': {
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'DomainName': 'string',
'ActiveTrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
{
'AwsAccountNumber': 'string',
'KeyPairIds': {
'Quantity': 123,
'Items': [
'string',
]
}
},
]
},
'StreamingDistributionConfig': {
'CallerReference': 'string',
'S3Origin': {
'DomainName': 'string',
'OriginAccessIdentity': 'string'
},
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
238 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False
}
},
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– StreamingDistribution (dict) – The streaming distribution’s information.
* Id (string) – The identifier for the streaming distribution. For exam-
ple: EGTXBD79H29TRA8.
* Status (string) – The current status of the streaming distribution.
When the status is Deployed, the distribution’s information is fully
propagated throughout the Amazon CloudFront system.
* LastModifiedTime (datetime) – The date and time the distribution
was last modified.
* DomainName (string) – The domain name corre-
sponding to the streaming distribution. For example:
s5c39gqb8ow64r.cloudfront.net.
* ActiveTrustedSigners (dict) – CloudFront automatically adds this
element to the response only if you’ve set up the distribution to serve
private content with signed URLs. The element lists the key pair IDs
that CloudFront is aware of for each trusted signer. The Signer child
element lists the AWS account number of the trusted signer (or an
empty Self element if the signer is you). The Signer element also
includes the IDs of any active key pairs associated with the trusted
signer’s AWS account. If no KeyPairId element appears for a Signer,
that signer can’t create working signed URLs.
· Enabled (boolean) – Each active trusted signer.
· Quantity (integer) – The number of unique trusted signers
included in all cache behaviors. For example, if three cache
behaviors all list the same three AWS accounts, the value of
Quantity for ActiveTrustedSigners will be 3.
· Items (list) – A complex type that contains one Signer com-
plex type for each unique trusted signer that is specified in the
TrustedSigners complex type, including trusted signers in the
default cache behavior and in all of the other cache behaviors.
· (dict) – A complex type that lists the AWS accounts that were
included in the TrustedSigners complex type, as well as their
active CloudFront key pair IDs, if any.
3.1. Services 239
Boto3 Documentation, Release 1.1.4
· AwsAccountNumber (string) – Specifies an AWS account
that can create signed URLs. Values: self, which indicates
that the AWS account that was used to create the distribution
can created signed URLs, or an AWS account number. Omit
the dashes in the account number.
· KeyPairIds (dict) – A complex type that lists the active
CloudFront key pairs, if any, that are associated with AwsAc-
countNumber.
· Quantity (integer) – The number of active CloudFront key
pairs for AwsAccountNumber.
· Items (list) – A complex type that lists the active CloudFront
key pairs, if any, that are associated with AwsAccountNum-
ber.
· (string) –
* StreamingDistributionConfig (dict) – The current configuration
information for the streaming distribution.
· CallerReference (string) – A unique number that ensures
the request can’t be replayed. If the CallerReference is new
(no matter the content of the StreamingDistributionConfig ob-
ject), a new streaming distribution is created. If the Caller-
Reference is a value you already sent in a previous request to
create a streaming distribution, and the content of the Stream-
ingDistributionConfig is identical to the original request (ig-
noring white space), the response includes the same informa-
tion returned to the original request. If the CallerReference
is a value you already sent in a previous request to create a
streaming distribution but the content of the StreamingDis-
tributionConfig is different from the original request, Cloud-
Front returns a DistributionAlreadyExists error.
· S3Origin (dict) – A complex type that contains information
about the Amazon S3 bucket from which you want Cloud-
Front to get your media files for distribution.
· DomainName (string) – The DNS name of the S3 origin.
· OriginAccessIdentity (string) – Your S3 origin’s origin ac-
cess identity.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this
streaming distribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· Comment (string) – Any comments you want to include
about the streaming distribution.
· Logging (dict) – A complex type that controls whether access
logs are written for the streaming distribution.
· Enabled (boolean) – Specifies whether you want CloudFront
to save access logs to an Amazon S3 bucket. If you do not
want to enable logging when you create a streaming distribu-
tion or if you want to disable logging for an existing stream-
ing distribution, specify false for Enabled, and specify empty
Bucket and Prefix elements. If you specify false for Enabled
240 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
but you specify values for Bucket and Prefix, the values are
automatically deleted.
· Bucket (string) – The Amazon S3 bucket to store the access
logs in, for example, myawslogbucket.s3.amazonaws.com.
· Prefix (string) – An optional string that you want CloudFront
to prefix to the access log filenames for this streaming distri-
bution, for example, myprefix/. If you want to enable logging,
but you do not want to specify a prefix, you still must include
an empty Prefix element in the Logging element.
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· PriceClass (string) – A complex type that contains informa-
tion about price class for this streaming distribution.
· Enabled (boolean) – Whether the streaming distribution is
enabled to accept end user requests for content.
– ETag (string) – The current version of the streaming distribution’s infor-
mation. For example: E2QWRUHAPOMQZL.
get_streaming_distribution_config(**kwargs)
Get the configuration information about a streaming distribution.
Request Syntax
response = client.get_streaming_distribution_config(
Id='string'
)
Parameters Id (string) – [REQUIRED] The streaming distribution’s id.
Return type dict
Returns
Response Syntax
{
'StreamingDistributionConfig': {
3.1. Services 241
Boto3 Documentation, Release 1.1.4
'CallerReference': 'string',
'S3Origin': {
'DomainName': 'string',
'OriginAccessIdentity': 'string'
},
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False
},
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– StreamingDistributionConfig (dict) – The streaming distribution’s con-
figuration information.
* CallerReference (string) – A unique number that ensures the re-
quest can’t be replayed. If the CallerReference is new (no matter the
content of the StreamingDistributionConfig object), a new stream-
ing distribution is created. If the CallerReference is a value you
already sent in a previous request to create a streaming distribution,
and the content of the StreamingDistributionConfig is identical to
the original request (ignoring white space), the response includes
the same information returned to the original request. If the Caller-
Reference is a value you already sent in a previous request to create
a streaming distribution but the content of the StreamingDistribu-
tionConfig is different from the original request, CloudFront returns
a DistributionAlreadyExists error.
* S3Origin (dict) – A complex type that contains information about
the Amazon S3 bucket from which you want CloudFront to get your
media files for distribution.
· DomainName (string) – The DNS name of the S3 origin.
· OriginAccessIdentity (string) – Your S3 origin’s origin ac-
cess identity.
* Aliases (dict) – A complex type that contains information about
CNAMEs (alternate domain names), if any, for this streaming dis-
tribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
242 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
* Comment (string) – Any comments you want to include about the
streaming distribution.
* Logging (dict) – A complex type that controls whether access logs
are written for the streaming distribution.
· Enabled (boolean) – Specifies whether you want CloudFront
to save access logs to an Amazon S3 bucket. If you do not
want to enable logging when you create a streaming distribu-
tion or if you want to disable logging for an existing stream-
ing distribution, specify false for Enabled, and specify empty
Bucket and Prefix elements. If you specify false for Enabled
but you specify values for Bucket and Prefix, the values are
automatically deleted.
· Bucket (string) – The Amazon S3 bucket to store the access
logs in, for example, myawslogbucket.s3.amazonaws.com.
· Prefix (string) – An optional string that you want CloudFront
to prefix to the access log filenames for this streaming distri-
bution, for example, myprefix/. If you want to enable logging,
but you do not want to specify a prefix, you still must include
an empty Prefix element in the Logging element.
* TrustedSigners (dict) – A complex type that specifies the AWS ac-
counts, if any, that you want to allow to create signed URLs for
private content. If you want to require signed URLs in requests for
objects in the target origin that match the PathPattern for this cache
behavior, specify true for Enabled, and specify the applicable val-
ues for Quantity and Items. For more information, go to Using a
Signed URL to Serve Private Content in the Amazon CloudFront
Developer Guide. If you don’t want to require signed URLs in re-
quests for objects that match PathPattern, specify false for Enabled
and 0 for Quantity. Omit Items. To add, change, or remove one or
more trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted signers
that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
* PriceClass (string) – A complex type that contains information
about price class for this streaming distribution.
* Enabled (boolean) – Whether the streaming distribution is enabled
to accept end user requests for content.
– ETag (string) – The current version of the configuration. For example:
E2QWRUHAPOMQZL.
get_waiter(waiter_name)
3.1. Services 243
Boto3 Documentation, Release 1.1.4
list_cloud_front_origin_access_identities(**kwargs)
List origin access identities.
Request Syntax
response = client.list_cloud_front_origin_access_identities(
Marker='string',
MaxItems='string'
)
Parameters
• Marker (string) – Use this when paginating results to indicate where to begin
in your list of origin access identities. The results include identities in the list
that occur after the marker. To get the next page of results, set the Marker to the
value of the NextMarker from the current page’s response (which is also the ID
of the last identity on that page).
• MaxItems (string) – The maximum number of origin access identities you want
in the response body.
Return type dict
Returns
Response Syntax
{
'CloudFrontOriginAccessIdentityList': {
'Marker': 'string',
'NextMarker': 'string',
'MaxItems': 123,
'IsTruncated': True|False,
'Quantity': 123,
'Items': [
{
'Id': 'string',
'S3CanonicalUserId': 'string',
'Comment': 'string'
},
]
}
}
Response Structure
• (dict) – The returned result of the corresponding request.
– CloudFrontOriginAccessIdentityList (dict) – The CloudFrontOriginAc-
cessIdentityList type.
* Marker (string) – The value you provided for the Marker request
parameter.
* NextMarker (string) – If IsTruncated is true, this element is present
and contains the value you can use for the Marker request parameter
to continue listing your origin access identities where they left off.
* MaxItems (integer) – The value you provided for the MaxItems
request parameter.
* IsTruncated (boolean) – A flag that indicates whether more origin
access identities remain to be listed. If your results were truncated,
you can make a follow-up pagination request using the Marker re-
quest parameter to retrieve more items in the list.
* Quantity (integer) – The number of CloudFront origin access iden-
tities that were created by the current AWS account.
244 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Items (list) – A complex type that contains one CloudFrontOrig-
inAccessIdentitySummary element for each origin access identity
that was created by the current AWS account.
· (dict) – Summary of the information about a CloudFront ori-
gin access identity.
· Id (string) – The ID for the origin access identity. For exam-
ple: E74FTE3AJFJ256A.
· S3CanonicalUserId (string) – The Amazon S3 canonical
user ID for the origin access identity, which you use when
giving the origin access identity read permission to an object
in Amazon S3.
· Comment (string) – The comment for this origin access iden-
tity, as originally specified when created.
list_distributions(**kwargs)
List distributions.
Request Syntax
response = client.list_distributions(
Marker='string',
MaxItems='string'
)
Parameters
• Marker (string) – Use this when paginating results to indicate where to begin in
your list of distributions. The results include distributions in the list that occur
after the marker. To get the next page of results, set the Marker to the value of
the NextMarker from the current page’s response (which is also the ID of the last
distribution on that page).
• MaxItems (string) – The maximum number of distributions you want in the
response body.
Return type dict
Returns
Response Syntax
{
'DistributionList': {
'Marker': 'string',
'NextMarker': 'string',
'MaxItems': 123,
'IsTruncated': True|False,
'Quantity': 123,
'Items': [
{
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'DomainName': 'string',
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'Origins': {
3.1. Services 245
Boto3 Documentation, Release 1.1.4
'Quantity': 123,
'Items': [
{
'Id': 'string',
'DomainName': 'string',
'OriginPath': 'string',
'S3OriginConfig': {
'OriginAccessIdentity': 'string'
},
'CustomOriginConfig': {
'HTTPPort': 123,
'HTTPSPort': 123,
'OriginProtocolPolicy': 'http-only'|'match-viewer'
}
},
]
},
'DefaultCacheBehavior': {
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELET
]
}
},
246 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
'CacheBehaviors': {
'Quantity': 123,
'Items': [
{
'PathPattern': 'string',
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redi
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'D
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
]
},
'CustomErrorResponses': {
'Quantity': 123,
'Items': [
3.1. Services 247
Boto3 Documentation, Release 1.1.4
{
'ErrorCode': 123,
'ResponsePagePath': 'string',
'ResponseCode': 'string',
'ErrorCachingMinTTL': 123
},
]
},
'Comment': 'string',
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False,
'ViewerCertificate': {
'IAMCertificateId': 'string',
'CloudFrontDefaultCertificate': True|False,
'SSLSupportMethod': 'sni-only'|'vip',
'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
},
'Restrictions': {
'GeoRestriction': {
'RestrictionType': 'blacklist'|'whitelist'|'none',
'Quantity': 123,
'Items': [
'string',
]
}
}
},
]
}
}
Response Structure
• (dict) – The returned result of the corresponding request.
– DistributionList (dict) – The DistributionList type.
* Marker (string) – The value you provided for the Marker request
parameter.
* NextMarker (string) – If IsTruncated is true, this element is present
and contains the value you can use for the Marker request parameter
to continue listing your distributions where they left off.
* MaxItems (integer) – The value you provided for the MaxItems
request parameter.
* IsTruncated (boolean) – A flag that indicates whether more dis-
tributions remain to be listed. If your results were truncated, you
can make a follow-up pagination request using the Marker request
parameter to retrieve more distributions in the list.
* Quantity (integer) – The number of distributions that were created
by the current AWS account.
* Items (list) – A complex type that contains one DistributionSum-
mary element for each distribution that was created by the current
AWS account.
· (dict) – A summary of the information for an Amazon Cloud-
Front distribution.
· Id (string) – The identifier for the distribution. For example:
EDFDVBD632BHDS5.
· Status (string) – This response element indicates the current
status of the distribution. When the status is Deployed, the
248 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
distribution’s information is fully propagated throughout the
Amazon CloudFront system.
· LastModifiedTime (datetime) – The date and time the distri-
bution was last modified.
· DomainName (string) – The domain name cor-
responding to the distribution. For example:
d604721fxaaqy9.cloudfront.net.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this dis-
tribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· Origins (dict) – A complex type that contains information
about origins for this distribution.
· Quantity (integer) – The number of origins for this distribu-
tion.
· Items (list) – A complex type that contains origins for this
distribution.
· (dict) – A complex type that describes the Amazon S3 bucket
or the HTTP server (for example, a web server) from which
CloudFront gets your files.You must create at least one origin.
· Id (string) – A unique identifier for the origin. The value of
Id must be unique within the distribution. You use the value
of Id when you create a cache behavior. The Id identifies the
origin that CloudFront routes a request to when the request
matches the path pattern for that cache behavior.
· DomainName (string) – Amazon S3 origins: The DNS name
of the Amazon S3 bucket from which you want Cloud-
Front to get objects for this origin, for example, myaws-
bucket.s3.amazonaws.com. Custom origins: The DNS do-
main name for the HTTP server from which you want
CloudFront to get objects for this origin, for example,
www.example.com.
· OriginPath (string) – An optional element that causes Cloud-
Front to request your content from a directory in your Ama-
zon S3 bucket or your custom origin. When you include the
OriginPath element, specify the directory name, beginning
with a /. CloudFront appends the directory name to the value
of DomainName.
· S3OriginConfig (dict) – A complex type that contains infor-
mation about the Amazon S3 origin. If the origin is a custom
origin, use the CustomOriginConfig element instead.
· OriginAccessIdentity (string) – The CloudFront origin ac-
cess identity to associate with the origin. Use an origin ac-
cess identity to configure the origin so that end users can only
access objects in an Amazon S3 bucket through CloudFront.
If you want end users to be able to access objects using ei-
ther the CloudFront URL or the Amazon S3 URL, specify
an empty OriginAccessIdentity element. To delete the origin
access identity from an existing distribution, update the distri-
3.1. Services 249
Boto3 Documentation, Release 1.1.4
bution configuration and include an empty OriginAccessIden-
tity element. To replace the origin access identity, update the
distribution configuration and specify the new origin access
identity. Use the format origin-access-identity/cloudfront/Id
where Id is the value that CloudFront returned in the Id ele-
ment when you created the origin access identity.
· CustomOriginConfig (dict) – A complex type that contains
information about a custom origin. If the origin is an Amazon
S3 bucket, use the S3OriginConfig element instead.
· HTTPPort (integer) – The HTTP port the custom origin lis-
tens on.
· HTTPSPort (integer) – The HTTPS port the custom origin
listens on.
· OriginProtocolPolicy (string) – The origin protocol policy
to apply to your origin.
· DefaultCacheBehavior (dict) – A complex type that de-
scribes the default cache behavior if you do not specify a
CacheBehavior element or if files don’t match any of the val-
ues of PathPattern in CacheBehavior elements.You must cre-
ate exactly one default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
250 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
3.1. Services 251
Boto3 Documentation, Release 1.1.4
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CacheBehaviors (dict) – A complex type that contains zero
or more CacheBehavior elements.
· Quantity (integer) – The number of cache behaviors for this
252 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
distribution.
· Items (list) – Optional: A complex type that contains cache
behaviors for this distribution. If Quantity is 0, you can omit
Items.
· (dict) – A complex type that describes how CloudFront pro-
cesses requests. You can create up to 10 cache behav-
iors.You must create at least as many cache behaviors (in-
cluding the default cache behavior) as you have origins if you
want CloudFront to distribute objects from all of the origins.
Each cache behavior specifies the one origin from which you
want CloudFront to get objects. If you have two origins and
only the default cache behavior, the default cache behavior
will cause CloudFront to get objects from one of the ori-
gins, but the other origin will never be used. If you don’t
want to specify any cache behaviors, include only an empty
CacheBehaviors element. Don’t include an empty CacheBe-
havior element, or CloudFront returns a MalformedXML er-
ror. To delete all cache behaviors in an existing distribu-
tion, update the distribution configuration and include only an
empty CacheBehaviors element. To add, change, or remove
one or more cache behaviors, update the distribution configu-
ration and specify all of the cache behaviors that you want to
include in the updated distribution.
· PathPattern (string) – The pattern (for example, im-
ages/*.jpg) that specifies which requests you want this cache
behavior to apply to. When CloudFront receives an end-user
request, the requested path is compared with path patterns in
the order in which cache behaviors are listed in the distribu-
tion. The path pattern for the default cache behavior is * and
cannot be changed. If the request for an object does not match
the path pattern for any cache behaviors, CloudFront applies
the behavior in the default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
3.1. Services 253
Boto3 Documentation, Release 1.1.4
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
254 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
3.1. Services 255
Boto3 Documentation, Release 1.1.4
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CustomErrorResponses (dict) – A complex type that con-
tains zero or more CustomErrorResponses elements.
· Quantity (integer) – The number of custom error responses
for this distribution.
· Items (list) – Optional: A complex type that contains custom
error responses for this distribution. If Quantity is 0, you can
omit Items.
· (dict) – A complex type that describes how you’d prefer
CloudFront to respond to requests that result in either a 4xx or
5xx response. You can control whether a custom error page
should be displayed, what the desired response code should
be for this error page and how long should the error response
be cached by CloudFront. If you don’t want to specify any
custom error responses, include only an empty CustomEr-
rorResponses element. To delete all custom error responses
in an existing distribution, update the distribution configura-
tion and include only an empty CustomErrorResponses ele-
ment. To add, change, or remove one or more custom error
responses, update the distribution configuration and specify
all of the custom error responses that you want to include in
the updated distribution.
· ErrorCode (integer) – The 4xx or 5xx HTTP status code that
you want to customize. For a list of HTTP status codes that
you can customize, see CloudFront documentation.
· ResponsePagePath (string) – The path of the custom error
page (for example, /custom_404.html). The path is relative
to the distribution and must begin with a slash (/). If the path
includes any non-ASCII characters or unsafe characters as de-
fined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL
encode those characters. Do not URL encode any other char-
acters in the path, or CloudFront will not return the custom
error page to the viewer.
· ResponseCode (string) – The HTTP status code that you
want CloudFront to return with the custom error page to the
viewer. For a list of HTTP status codes that you can replace,
see CloudFront Documentation.
· ErrorCachingMinTTL (integer) – The minimum amount of
time you want HTTP error codes to stay in CloudFront caches
before CloudFront queries your origin to see whether the ob-
ject has been updated. You can specify a value from 0 to
31,536,000.
· Comment (string) – The comment originally specified when
this distribution was created.
· PriceClass (string) –
· Enabled (boolean) – Whether the distribution is enabled to
256 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
accept end user requests for content.
· ViewerCertificate (dict) – A complex type that contains in-
formation about viewer certificates for this distribution.
· IAMCertificateId (string) – If you want viewers to use
HTTPS to request your objects and you’re using an al-
ternate domain name in your object URLs (for example,
https://example.com/logo.jpg), specify the IAM certificate
identifier of the custom viewer certificate for this distribution.
Specify either this value or CloudFrontDefaultCertificate.
· CloudFrontDefaultCertificate (boolean) – If you
want viewers to use HTTPS to request your objects
and you’re using the CloudFront domain name of
your distribution in your object URLs (for example,
https://d111111abcdef8.cloudfront.net/logo.jpg), set to true.
Omit this value if you are setting an IAMCertificateId.
· SSLSupportMethod (string) – If you specify a value for
IAMCertificateId, you must also specify how you want
CloudFront to serve HTTPS requests. Valid values are vip and
sni-only. If you specify vip, CloudFront uses dedicated IP ad-
dresses for your content and can respond to HTTPS requests
from any viewer. However, you must request permission to
use this feature, and you incur additional monthly charges. If
you specify sni-only, CloudFront can only respond to HTTPS
requests from viewers that support Server Name Indication
(SNI). All modern browsers support SNI, but some browsers
still in use don’t support SNI. Do not specify a value for
SSLSupportMethod if you specified true for CloudFrontDe-
faultCertificate.
· MinimumProtocolVersion (string) – Specify the minimum
version of the SSL protocol that you want CloudFront to use,
SSLv3 or TLSv1, for HTTPS connections. CloudFront will
serve your objects only to browsers or devices that support at
least the SSL version that you specify. The TLSv1 protocol is
more secure, so we recommend that you specify SSLv3 only
if your users are using browsers or devices that don’t support
TLSv1. If you’re using a custom certificate (if you specify a
value for IAMCertificateId) and if you’re using dedicated IP
(if you specify vip for SSLSupportMethod), you can choose
SSLv3 or TLSv1 as the MinimumProtocolVersion. If you’re
using a custom certificate (if you specify a value for IAM-
CertificateId) and if you’re using SNI (if you specify sni-only
for SSLSupportMethod), you must specify TLSv1 for Mini-
mumProtocolVersion.
· Restrictions (dict) – A complex type that identifies ways in
which you want to restrict distribution of your content.
· GeoRestriction (dict) – A complex type that controls the
countries in which your content is distributed. For more in-
formation about geo restriction, go to Customizing Error Re-
sponses in the Amazon CloudFront Developer Guide. Cloud-
Front determines the location of your users using MaxMind
GeoIP databases. For information about the accuracy of these
databases, see How accurate are your GeoIP databases? on
the MaxMind website.
· RestrictionType (string) – The method that you want to use
3.1. Services 257
Boto3 Documentation, Release 1.1.4
to restrict distribution of your content by country: - none: No
geo restriction is enabled, meaning access to content is not
restricted by client geo location. - blacklist: The Location el-
ements specify the countries in which you do not want Cloud-
Front to distribute your content. - whitelist: The Location el-
ements specify the countries in which you want CloudFront
to distribute your content.
· Quantity (integer) – When geo restriction is enabled, this is
the number of countries in your whitelist or blacklist. Other-
wise, when it is not enabled, Quantity is 0, and you can omit
Items.
· Items (list) – A complex type that contains a Location ele-
ment for each country in which you want CloudFront either to
distribute your content (whitelist) or not distribute your con-
tent (blacklist). The Location element is a two-letter, upper-
case country code for a country that you want to include in
your blacklist or whitelist. Include one Location element for
each country. CloudFront and MaxMind both use ISO 3166
country codes. For the current list of countries and the cor-
responding codes, see ISO 3166-1-alpha-2 code on the Inter-
national Organization for Standardization website. You can
also refer to the country list in the CloudFront console, which
includes both country names and codes.
· (string) –
list_invalidations(**kwargs)
List invalidation batches.
Request Syntax
response = client.list_invalidations(
DistributionId='string',
Marker='string',
MaxItems='string'
)
Parameters
• DistributionId (string) – [REQUIRED] The distribution’s id.
• Marker (string) – Use this parameter when paginating results to indicate where
to begin in your list of invalidation batches. Because the results are returned in
decreasing order from most recent to oldest, the most recent results are on the
first page, the second page will contain earlier results, and so on. To get the next
page of results, set the Marker to the value of the NextMarker from the current
page’s response. This value is the same as the ID of the last invalidation batch
on that page.
• MaxItems (string) – The maximum number of invalidation batches you want in
the response body.
Return type dict
Returns
Response Syntax
{
'InvalidationList': {
'Marker': 'string',
'NextMarker': 'string',
258 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'MaxItems': 123,
'IsTruncated': True|False,
'Quantity': 123,
'Items': [
{
'Id': 'string',
'CreateTime': datetime(2015, 1, 1),
'Status': 'string'
},
]
}
}
Response Structure
• (dict) – The returned result of the corresponding request.
– InvalidationList (dict) – Information about invalidation batches.
* Marker (string) – The value you provided for the Marker request
parameter.
* NextMarker (string) – If IsTruncated is true, this element is present
and contains the value you can use for the Marker request parameter
to continue listing your invalidation batches where they left off.
* MaxItems (integer) – The value you provided for the MaxItems
request parameter.
* IsTruncated (boolean) – A flag that indicates whether more in-
validation batch requests remain to be listed. If your results were
truncated, you can make a follow-up pagination request using the
Marker request parameter to retrieve more invalidation batches in
the list.
* Quantity (integer) – The number of invalidation batches that were
created by the current AWS account.
* Items (list) – A complex type that contains one InvalidationSum-
mary element for each invalidation batch that was created by the
current AWS account.
· (dict) – Summary of an invalidation request.
· Id (string) – The unique ID for an invalidation request.
· CreateTime (datetime) –
· Status (string) – The status of an invalidation request.
list_streaming_distributions(**kwargs)
List streaming distributions.
Request Syntax
response = client.list_streaming_distributions(
Marker='string',
MaxItems='string'
)
Parameters
• Marker (string) – Use this when paginating results to indicate where to begin in
your list of streaming distributions. The results include distributions in the list
that occur after the marker. To get the next page of results, set the Marker to the
value of the NextMarker from the current page’s response (which is also the ID
of the last distribution on that page).
• MaxItems (string) – The maximum number of streaming distributions you want
in the response body.
3.1. Services 259
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'StreamingDistributionList': {
'Marker': 'string',
'NextMarker': 'string',
'MaxItems': 123,
'IsTruncated': True|False,
'Quantity': 123,
'Items': [
{
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'DomainName': 'string',
'S3Origin': {
'DomainName': 'string',
'OriginAccessIdentity': 'string'
},
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'Comment': 'string',
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False
},
]
}
}
Response Structure
• (dict) – The returned result of the corresponding request.
– StreamingDistributionList (dict) – The StreamingDistributionList type.
* Marker (string) – The value you provided for the Marker request
parameter.
* NextMarker (string) – If IsTruncated is true, this element is present
and contains the value you can use for the Marker request parameter
to continue listing your streaming distributions where they left off.
* MaxItems (integer) – The value you provided for the MaxItems
request parameter.
* IsTruncated (boolean) – A flag that indicates whether more stream-
ing distributions remain to be listed. If your results were truncated,
you can make a follow-up pagination request using the Marker re-
quest parameter to retrieve more distributions in the list.
260 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Quantity (integer) – The number of streaming distributions that
were created by the current AWS account.
* Items (list) – A complex type that contains one StreamingDistribu-
tionSummary element for each distribution that was created by the
current AWS account.
· (dict) – A summary of the information for an Amazon Cloud-
Front streaming distribution.
· Id (string) – The identifier for the distribution. For example:
EDFDVBD632BHDS5.
· Status (string) – Indicates the current status of the distribu-
tion. When the status is Deployed, the distribution’s informa-
tion is fully propagated throughout the Amazon CloudFront
system.
· LastModifiedTime (datetime) – The date and time the distri-
bution was last modified.
· DomainName (string) – The domain name cor-
responding to the distribution. For example:
d604721fxaaqy9.cloudfront.net.
· S3Origin (dict) – A complex type that contains information
about the Amazon S3 bucket from which you want Cloud-
Front to get your media files for distribution.
· DomainName (string) – The DNS name of the S3 origin.
· OriginAccessIdentity (string) – Your S3 origin’s origin ac-
cess identity.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this
streaming distribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
3.1. Services 261
Boto3 Documentation, Release 1.1.4
Items.
· (string) –
· Comment (string) – The comment originally specified when
this distribution was created.
· PriceClass (string) –
· Enabled (boolean) – Whether the distribution is enabled to
accept end user requests for content.
update_cloud_front_origin_access_identity(**kwargs)
Update an origin access identity.
Request Syntax
response = client.update_cloud_front_origin_access_identity(
CloudFrontOriginAccessIdentityConfig={
'CallerReference': 'string',
'Comment': 'string'
},
Id='string',
IfMatch='string'
)
Parameters
• CloudFrontOriginAccessIdentityConfig (dict) – [REQUIRED] The identity’s
configuration information.
– CallerReference (string) – [REQUIRED] A unique number that ensures
the request can’t be replayed. If the CallerReference is new (no matter
the content of the CloudFrontOriginAccessIdentityConfig object), a new
origin access identity is created. If the CallerReference is a value you al-
ready sent in a previous request to create an identity, and the content of
the CloudFrontOriginAccessIdentityConfig is identical to the original re-
quest (ignoring white space), the response includes the same information
returned to the original request. If the CallerReference is a value you al-
ready sent in a previous request to create an identity but the content of the
CloudFrontOriginAccessIdentityConfig is different from the original re-
quest, CloudFront returns a CloudFrontOriginAccessIdentityAlreadyEx-
ists error.
– Comment (string) – [REQUIRED] Any comments you want to include
about the origin access identity.
• Id (string) – [REQUIRED] The identity’s id.
• IfMatch (string) – The value of the ETag header you received when retrieving
the identity’s configuration. For example: E2QWRUHAPOMQZL.
Return type dict
Returns
Response Syntax
{
'CloudFrontOriginAccessIdentity': {
'Id': 'string',
'S3CanonicalUserId': 'string',
'CloudFrontOriginAccessIdentityConfig': {
'CallerReference': 'string',
'Comment': 'string'
}
},
262 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– CloudFrontOriginAccessIdentity (dict) – The origin access identity’s in-
formation.
* Id (string) – The ID for the origin access identity. For example:
E74FTE3AJFJ256A.
* S3CanonicalUserId (string) – The Amazon S3 canonical user ID
for the origin access identity, which you use when giving the origin
access identity read permission to an object in Amazon S3.
* CloudFrontOriginAccessIdentityConfig (dict) – The current con-
figuration information for the identity.
· CallerReference (string) – A unique number that ensures
the request can’t be replayed. If the CallerReference is new
(no matter the content of the CloudFrontOriginAccessIdenti-
tyConfig object), a new origin access identity is created. If the
CallerReference is a value you already sent in a previous re-
quest to create an identity, and the content of the CloudFron-
tOriginAccessIdentityConfig is identical to the original re-
quest (ignoring white space), the response includes the same
information returned to the original request. If the CallerRef-
erence is a value you already sent in a previous request to cre-
ate an identity but the content of the CloudFrontOriginAcces-
sIdentityConfig is different from the original request, Cloud-
Front returns a CloudFrontOriginAccessIdentityAlreadyEx-
ists error.
· Comment (string) – Any comments you want to include
about the origin access identity.
– ETag (string) – The current version of the configuration. For example:
E2QWRUHAPOMQZL.
update_distribution(**kwargs)
Update a distribution.
Request Syntax
response = client.update_distribution(
DistributionConfig={
'CallerReference': 'string',
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'DefaultRootObject': 'string',
'Origins': {
'Quantity': 123,
'Items': [
{
'Id': 'string',
'DomainName': 'string',
'OriginPath': 'string',
'S3OriginConfig': {
3.1. Services 263
Boto3 Documentation, Release 1.1.4
'OriginAccessIdentity': 'string'
},
'CustomOriginConfig': {
'HTTPPort': 123,
'HTTPSPort': 123,
'OriginProtocolPolicy': 'http-only'|'match-viewer'
}
},
]
},
'DefaultCacheBehavior': {
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
'CacheBehaviors': {
'Quantity': 123,
'Items': [
264 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'PathPattern': 'string',
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-https',
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
]
},
'CustomErrorResponses': {
'Quantity': 123,
'Items': [
{
'ErrorCode': 123,
'ResponsePagePath': 'string',
'ResponseCode': 'string',
'ErrorCachingMinTTL': 123
},
]
3.1. Services 265
Boto3 Documentation, Release 1.1.4
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'IncludeCookies': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False,
'ViewerCertificate': {
'IAMCertificateId': 'string',
'CloudFrontDefaultCertificate': True|False,
'SSLSupportMethod': 'sni-only'|'vip',
'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
},
'Restrictions': {
'GeoRestriction': {
'RestrictionType': 'blacklist'|'whitelist'|'none',
'Quantity': 123,
'Items': [
'string',
]
}
}
},
Id='string',
IfMatch='string'
)
Parameters
• DistributionConfig (dict) – [REQUIRED] The distribution’s configuration in-
formation.
– CallerReference (string) – [REQUIRED] A unique number that ensures
the request can’t be replayed. If the CallerReference is new (no matter the
content of the DistributionConfig object), a new distribution is created. If
the CallerReference is a value you already sent in a previous request to
create a distribution, and the content of the DistributionConfig is identical
to the original request (ignoring white space), the response includes the
same information returned to the original request. If the CallerReference
is a value you already sent in a previous request to create a distribution but
the content of the DistributionConfig is different from the original request,
CloudFront returns a DistributionAlreadyExists error.
– Aliases (dict) – A complex type that contains information about CNAMEs
(alternate domain names), if any, for this distribution.
* Quantity (integer) – [REQUIRED] The number of CNAMEs, if
any, for this distribution.
* Items (list) – Optional: A complex type that contains CNAME el-
ements, if any, for this distribution. If Quantity is 0, you can omit
Items.
· (string) –
– DefaultRootObject (string) – The object that you want CloudFront to re-
turn (for example, index.html) when an end user requests the root URL for
your distribution (http://www.example.com) instead of an object in your
distribution (http://www.example.com/index.html). Specifying a default
root object avoids exposing the contents of your distribution. If you don’t
266 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
want to specify a default root object when you create a distribution, in-
clude an empty DefaultRootObject element. To delete the default root ob-
ject from an existing distribution, update the distribution configuration and
include an empty DefaultRootObject element. To replace the default root
object, update the distribution configuration and specify the new object.
– Origins (dict) – [REQUIRED] A complex type that contains information
about origins for this distribution.
* Quantity (integer) – [REQUIRED] The number of origins for this
distribution.
* Items (list) – A complex type that contains origins for this distribu-
tion.
· (dict) – A complex type that describes the Amazon S3 bucket
or the HTTP server (for example, a web server) from which
CloudFront gets your files.You must create at least one origin.
· Id (string) – [REQUIRED] A unique identifier for the origin.
The value of Id must be unique within the distribution. You
use the value of Id when you create a cache behavior. The Id
identifies the origin that CloudFront routes a request to when
the request matches the path pattern for that cache behavior.
· DomainName (string) – [REQUIRED] Amazon S3 origins:
The DNS name of the Amazon S3 bucket from which you
want CloudFront to get objects for this origin, for exam-
ple, myawsbucket.s3.amazonaws.com. Custom origins: The
DNS domain name for the HTTP server from which you
want CloudFront to get objects for this origin, for example,
www.example.com.
· OriginPath (string) – An optional element that causes Cloud-
Front to request your content from a directory in your Ama-
zon S3 bucket or your custom origin. When you include the
OriginPath element, specify the directory name, beginning
with a /. CloudFront appends the directory name to the value
of DomainName.
· S3OriginConfig (dict) – A complex type that contains infor-
mation about the Amazon S3 origin. If the origin is a custom
origin, use the CustomOriginConfig element instead.
· OriginAccessIdentity (string) – [REQUIRED] The Cloud-
Front origin access identity to associate with the origin. Use
an origin access identity to configure the origin so that end
users can only access objects in an Amazon S3 bucket through
CloudFront. If you want end users to be able to access ob-
jects using either the CloudFront URL or the Amazon S3
URL, specify an empty OriginAccessIdentity element. To
delete the origin access identity from an existing distribution,
update the distribution configuration and include an empty
OriginAccessIdentity element. To replace the origin access
identity, update the distribution configuration and specify the
new origin access identity. Use the format origin-access-
identity/cloudfront/Id where Id is the value that CloudFront
returned in the Id element when you created the origin access
identity.
· CustomOriginConfig (dict) – A complex type that contains
information about a custom origin. If the origin is an Amazon
S3 bucket, use the S3OriginConfig element instead.
· HTTPPort (integer) – [REQUIRED] The HTTP port the
3.1. Services 267
Boto3 Documentation, Release 1.1.4
custom origin listens on.
· HTTPSPort (integer) – [REQUIRED] The HTTPS port the
custom origin listens on.
· OriginProtocolPolicy (string) – [REQUIRED] The origin
protocol policy to apply to your origin.
– DefaultCacheBehavior (dict) – [REQUIRED] A complex type that de-
scribes the default cache behavior if you do not specify a CacheBehavior
element or if files don’t match any of the values of PathPattern in CacheBe-
havior elements.You must create exactly one default cache behavior.
* TargetOriginId (string) – [REQUIRED] The value of ID for the
origin that you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for the default
cache behavior.
* ForwardedValues (dict) – [REQUIRED] A complex type that
specifies how CloudFront handles query strings, cookies and head-
ers.
· QueryString (boolean) – [REQUIRED] Indicates whether
you want CloudFront to forward query strings to the origin
that is associated with this cache behavior. If so, specify true;
if not, specify false.
· Cookies (dict) – [REQUIRED] A complex type that specifies
how CloudFront handles cookies.
· Forward (string) – [REQUIRED] Use this element to spec-
ify whether you want CloudFront to forward cookies to the
origin that is associated with this cache behavior. You can
specify all, none or whitelist. If you choose All, CloudFront
forwards all cookies regardless of how many your application
uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – [REQUIRED] The number of
whitelisted cookies for this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – [REQUIRED] The number of different
headers that you want CloudFront to forward to the origin and
to vary on for this cache behavior. The maximum number
of headers that you can specify by name is 10. If you want
CloudFront to forward all headers to the origin and vary on
all of them, specify 1 for Quantity and * for Name. If you
don’t want CloudFront to forward any additional headers to
the origin or to vary on any headers, specify 0 for Quantity
and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
268 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* TrustedSigners (dict) – [REQUIRED] A complex type that speci-
fies the AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs in re-
quests for objects in the target origin that match the PathPattern for
this cache behavior, specify true for Enabled, and specify the ap-
plicable values for Quantity and Items. For more information, go to
Using a Signed URL to Serve Private Content in the Amazon Cloud-
Front Developer Guide. If you don’t want to require signed URLs
in requests for objects that match PathPattern, specify false for En-
abled and 0 for Quantity. Omit Items. To add, change, or remove
one or more trusted signers, change Enabled to true (if it’s currently
false), change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – [REQUIRED] Specifies whether you
want to require end users to use signed URLs to access the
files specified by PathPattern and TargetOriginId.
· Quantity (integer) – [REQUIRED] The number of trusted
signers for this cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
* ViewerProtocolPolicy (string) – [REQUIRED] Use this element
to specify the protocol that users can use to access the files in the
origin specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end users
to use any available protocol, specify allow-all. If you want Cloud-
Front to require HTTPS, specify https. If you want CloudFront to re-
spond to an HTTP request with an HTTP status code of 301 (Moved
Permanently) and the HTTPS URL, specify redirect-to-https. The
viewer then resubmits the request using the HTTPS URL.
* MinTTL (integer) – [REQUIRED] The minimum amount of time
that you want objects to stay in CloudFront caches before Cloud-
Front queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 seconds (100
years).
* AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your Amazon
S3 bucket or your custom origin. There are three choices: - Cloud-
Front forwards only GET and HEAD requests. - CloudFront for-
wards only GET, HEAD and OPTIONS requests. - CloudFront for-
wards GET, HEAD, OPTIONS, PUT, PATCH, POST, and DELETE
requests. If you pick the third choice, you may need to restrict ac-
cess to your Amazon S3 bucket or to your custom origin so users
can’t perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects from
your origin.
· Quantity (integer) – [REQUIRED] The number of HTTP
methods that you want CloudFront to forward to your origin.
Valid values are 2 (for GET and HEAD requests), 3 (for GET,
HEAD and OPTIONS requests) and 7 (for GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests).
· Items (list) – [REQUIRED] A complex type that contains
the HTTP methods that you want CloudFront to process and
3.1. Services 269
Boto3 Documentation, Release 1.1.4
forward to your origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – [REQUIRED] The number of HTTP
methods for which you want CloudFront to cache responses.
Valid values are 2 (for caching responses to GET and HEAD
requests) and 3 (for caching responses to GET, HEAD, and
OPTIONS requests).
· Items (list) – [REQUIRED] A complex type that contains the
HTTP methods that you want CloudFront to cache responses
to.
· (string) –
* SmoothStreaming (boolean) – Indicates whether you want to dis-
tribute media files in Microsoft Smooth Streaming format using the
origin that is associated with this cache behavior. If so, specify true;
if not, specify false.
* DefaultTTL (integer) – If you don’t configure your origin to add
a Cache-Control max-age directive or an Expires header, Default-
TTL is the default amount of time (in seconds) that an object is in
a CloudFront cache before CloudFront forwards another request to
your origin to determine whether the object has been updated. The
value that you specify applies only when your origin does not add
HTTP headers such as Cache-Control max-age, Cache-Control s-
maxage, and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
* MaxTTL (integer) – The maximum amount of time (in seconds)
that an object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the object has
been updated. The value that you specify applies only when your
origin adds HTTP headers such as Cache-Control max-age, Cache-
Control s-maxage, and Expires to objects. You can specify a value
from 0 to 3,153,600,000 seconds (100 years).
– CacheBehaviors (dict) – A complex type that contains zero or more
CacheBehavior elements.
* Quantity (integer) – [REQUIRED] The number of cache behaviors
for this distribution.
* Items (list) – Optional: A complex type that contains cache behav-
iors for this distribution. If Quantity is 0, you can omit Items.
· (dict) – A complex type that describes how CloudFront pro-
cesses requests. You can create up to 10 cache behav-
iors.You must create at least as many cache behaviors (in-
cluding the default cache behavior) as you have origins if you
want CloudFront to distribute objects from all of the origins.
Each cache behavior specifies the one origin from which you
want CloudFront to get objects. If you have two origins and
only the default cache behavior, the default cache behavior
270 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
will cause CloudFront to get objects from one of the ori-
gins, but the other origin will never be used. If you don’t
want to specify any cache behaviors, include only an empty
CacheBehaviors element. Don’t include an empty CacheBe-
havior element, or CloudFront returns a MalformedXML er-
ror. To delete all cache behaviors in an existing distribu-
tion, update the distribution configuration and include only an
empty CacheBehaviors element. To add, change, or remove
one or more cache behaviors, update the distribution configu-
ration and specify all of the cache behaviors that you want to
include in the updated distribution.
· PathPattern (string) – [REQUIRED] The pattern (for ex-
ample, images/*.jpg) that specifies which requests you want
this cache behavior to apply to. When CloudFront receives
an end-user request, the requested path is compared with path
patterns in the order in which cache behaviors are listed in the
distribution. The path pattern for the default cache behavior is
* and cannot be changed. If the request for an object does not
match the path pattern for any cache behaviors, CloudFront
applies the behavior in the default cache behavior.
· TargetOriginId (string) – [REQUIRED] The value of ID for
the origin that you want CloudFront to route requests to when
a request matches the path pattern either for a cache behavior
or for the default cache behavior.
· ForwardedValues (dict) – [REQUIRED] A complex type
that specifies how CloudFront handles query strings, cookies
and headers.
· QueryString (boolean) – [REQUIRED] Indicates whether
you want CloudFront to forward query strings to the origin
that is associated with this cache behavior. If so, specify true;
if not, specify false.
· Cookies (dict) – [REQUIRED] A complex type that specifies
how CloudFront handles cookies.
· Forward (string) – [REQUIRED] Use this element to spec-
ify whether you want CloudFront to forward cookies to the
origin that is associated with this cache behavior. You can
specify all, none or whitelist. If you choose All, CloudFront
forwards all cookies regardless of how many your application
uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – [REQUIRED] The number of
whitelisted cookies for this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – [REQUIRED] The number of different
headers that you want CloudFront to forward to the origin and
to vary on for this cache behavior. The maximum number
3.1. Services 271
Boto3 Documentation, Release 1.1.4
of headers that you can specify by name is 10. If you want
CloudFront to forward all headers to the origin and vary on
all of them, specify 1 for Quantity and * for Name. If you
don’t want CloudFront to forward any additional headers to
the origin or to vary on any headers, specify 0 for Quantity
and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – [REQUIRED] A complex type that
specifies the AWS accounts, if any, that you want to allow to
create signed URLs for private content. If you want to require
signed URLs in requests for objects in the target origin that
match the PathPattern for this cache behavior, specify true for
Enabled, and specify the applicable values for Quantity and
Items. For more information, go to Using a Signed URL to
Serve Private Content in the Amazon CloudFront Developer
Guide. If you don’t want to require signed URLs in requests
for objects that match PathPattern, specify false for Enabled
and 0 for Quantity. Omit Items. To add, change, or remove
one or more trusted signers, change Enabled to true (if it’s
currently false), change Quantity as applicable, and specify all
of the trusted signers that you want to include in the updated
distribution.
· Enabled (boolean) – [REQUIRED] Specifies whether you
want to require end users to use signed URLs to access the
files specified by PathPattern and TargetOriginId.
· Quantity (integer) – [REQUIRED] The number of trusted
signers for this cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – [REQUIRED] Use this el-
ement to specify the protocol that users can use to access the
files in the origin specified by TargetOriginId when a request
matches the path pattern in PathPattern. If you want Cloud-
Front to allow end users to use any available protocol, specify
allow-all. If you want CloudFront to require HTTPS, specify
https. If you want CloudFront to respond to an HTTP request
with an HTTP status code of 301 (Moved Permanently) and
the HTTPS URL, specify redirect-to-https. The viewer then
resubmits the request using the HTTPS URL.
· MinTTL (integer) – [REQUIRED] The minimum amount of
time that you want objects to stay in CloudFront caches before
CloudFront queries your origin to see whether the object has
been updated.You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
272 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – [REQUIRED] The number of HTTP
methods that you want CloudFront to forward to your origin.
Valid values are 2 (for GET and HEAD requests), 3 (for GET,
HEAD and OPTIONS requests) and 7 (for GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests).
· Items (list) – [REQUIRED] A complex type that contains
the HTTP methods that you want CloudFront to process and
forward to your origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – [REQUIRED] The number of HTTP
methods for which you want CloudFront to cache responses.
Valid values are 2 (for caching responses to GET and HEAD
requests) and 3 (for caching responses to GET, HEAD, and
OPTIONS requests).
· Items (list) – [REQUIRED] A complex type that contains the
HTTP methods that you want CloudFront to cache responses
to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
3.1. Services 273
Boto3 Documentation, Release 1.1.4
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
– CustomErrorResponses (dict) – A complex type that contains zero or
more CustomErrorResponse elements.
* Quantity (integer) – [REQUIRED] The number of custom error
responses for this distribution.
* Items (list) – Optional: A complex type that contains custom error
responses for this distribution. If Quantity is 0, you can omit Items.
· (dict) – A complex type that describes how you’d prefer
CloudFront to respond to requests that result in either a 4xx or
5xx response. You can control whether a custom error page
should be displayed, what the desired response code should
be for this error page and how long should the error response
be cached by CloudFront. If you don’t want to specify any
custom error responses, include only an empty CustomEr-
rorResponses element. To delete all custom error responses
in an existing distribution, update the distribution configura-
tion and include only an empty CustomErrorResponses ele-
ment. To add, change, or remove one or more custom error
responses, update the distribution configuration and specify
all of the custom error responses that you want to include in
the updated distribution.
· ErrorCode (integer) – [REQUIRED] The 4xx or 5xx HTTP
status code that you want to customize. For a list of HTTP
status codes that you can customize, see CloudFront docu-
mentation.
· ResponsePagePath (string) – The path of the custom error
page (for example, /custom_404.html). The path is relative
to the distribution and must begin with a slash (/). If the path
includes any non-ASCII characters or unsafe characters as de-
fined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL
encode those characters. Do not URL encode any other char-
acters in the path, or CloudFront will not return the custom
error page to the viewer.
· ResponseCode (string) – The HTTP status code that you
want CloudFront to return with the custom error page to the
viewer. For a list of HTTP status codes that you can replace,
see CloudFront Documentation.
· ErrorCachingMinTTL (integer) – The minimum amount of
time you want HTTP error codes to stay in CloudFront caches
before CloudFront queries your origin to see whether the ob-
ject has been updated. You can specify a value from 0 to
31,536,000.
– Comment (string) – [REQUIRED] Any comments you want to include
about the distribution.
– Logging (dict) – A complex type that controls whether access logs are
written for the distribution.
* Enabled (boolean) – [REQUIRED] Specifies whether you want
CloudFront to save access logs to an Amazon S3 bucket. If you do
not want to enable logging when you create a distribution or if you
want to disable logging for an existing distribution, specify false
for Enabled, and specify empty Bucket and Prefix elements. If you
specify false for Enabled but you specify values for Bucket, prefix
274 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
and IncludeCookies, the values are automatically deleted.
* IncludeCookies (boolean) – [REQUIRED] Specifies whether you
want CloudFront to include cookies in access logs, specify true for
IncludeCookies. If you choose to include cookies in logs, Cloud-
Front logs all cookies regardless of how you configure the cache
behaviors for this distribution. If you do not want to include cook-
ies when you create a distribution or if you want to disable include
cookies for an existing distribution, specify false for IncludeCook-
ies.
* Bucket (string) – [REQUIRED] The Amazon S3 bucket
to store the access logs in, for example, myawslog-
bucket.s3.amazonaws.com.
* Prefix (string) – [REQUIRED] An optional string that you want
CloudFront to prefix to the access log filenames for this distribution,
for example, myprefix/. If you want to enable logging, but you do
not want to specify a prefix, you still must include an empty Prefix
element in the Logging element.
– PriceClass (string) – A complex type that contains information about
price class for this distribution.
– Enabled (boolean) – [REQUIRED] Whether the distribution is enabled
to accept end user requests for content.
– ViewerCertificate (dict) – A complex type that contains information
about viewer certificates for this distribution.
* IAMCertificateId (string) – If you want viewers to use HTTPS to
request your objects and you’re using an alternate domain name
in your object URLs (for example, https://example.com/logo.jpg),
specify the IAM certificate identifier of the custom viewer certifi-
cate for this distribution. Specify either this value or CloudFront-
DefaultCertificate.
* CloudFrontDefaultCertificate (boolean) – If you want viewers to
use HTTPS to request your objects and you’re using the CloudFront
domain name of your distribution in your object URLs (for example,
https://d111111abcdef8.cloudfront.net/logo.jpg), set to true. Omit
this value if you are setting an IAMCertificateId.
* SSLSupportMethod (string) – If you specify a value for IAMCer-
tificateId, you must also specify how you want CloudFront to serve
HTTPS requests. Valid values are vip and sni-only. If you spec-
ify vip, CloudFront uses dedicated IP addresses for your content
and can respond to HTTPS requests from any viewer. However,
you must request permission to use this feature, and you incur ad-
ditional monthly charges. If you specify sni-only, CloudFront can
only respond to HTTPS requests from viewers that support Server
Name Indication (SNI). All modern browsers support SNI, but some
browsers still in use don’t support SNI. Do not specify a value for
SSLSupportMethod if you specified true for CloudFrontDefaultCer-
tificate.
* MinimumProtocolVersion (string) – Specify the minimum version
of the SSL protocol that you want CloudFront to use, SSLv3 or
TLSv1, for HTTPS connections. CloudFront will serve your objects
only to browsers or devices that support at least the SSL version that
you specify. The TLSv1 protocol is more secure, so we recommend
that you specify SSLv3 only if your users are using browsers or
devices that don’t support TLSv1. If you’re using a custom cer-
tificate (if you specify a value for IAMCertificateId) and if you’re
3.1. Services 275
Boto3 Documentation, Release 1.1.4
using dedicated IP (if you specify vip for SSLSupportMethod), you
can choose SSLv3 or TLSv1 as the MinimumProtocolVersion. If
you’re using a custom certificate (if you specify a value for IAM-
CertificateId) and if you’re using SNI (if you specify sni-only for
SSLSupportMethod), you must specify TLSv1 for MinimumProto-
colVersion.
– Restrictions (dict) – A complex type that identifies ways in which you
want to restrict distribution of your content.
* GeoRestriction (dict) – [REQUIRED] A complex type that con-
trols the countries in which your content is distributed. For more in-
formation about geo restriction, go to Customizing Error Responses
in the Amazon CloudFront Developer Guide. CloudFront deter-
mines the location of your users using MaxMind GeoIP databases.
For information about the accuracy of these databases, see How ac-
curate are your GeoIP databases? on the MaxMind website.
· RestrictionType (string) – [REQUIRED] The method that
you want to use to restrict distribution of your content by
country: - none: No geo restriction is enabled, meaning ac-
cess to content is not restricted by client geo location. - black-
list: The Location elements specify the countries in which you
do not want CloudFront to distribute your content. - whitelist:
The Location elements specify the countries in which you
want CloudFront to distribute your content.
· Quantity (integer) – [REQUIRED] When geo restriction is
enabled, this is the number of countries in your whitelist or
blacklist. Otherwise, when it is not enabled, Quantity is 0,
and you can omit Items.
· Items (list) – A complex type that contains a Location ele-
ment for each country in which you want CloudFront either to
distribute your content (whitelist) or not distribute your con-
tent (blacklist). The Location element is a two-letter, upper-
case country code for a country that you want to include in
your blacklist or whitelist. Include one Location element for
each country. CloudFront and MaxMind both use ISO 3166
country codes. For the current list of countries and the cor-
responding codes, see ISO 3166-1-alpha-2 code on the Inter-
national Organization for Standardization website. You can
also refer to the country list in the CloudFront console, which
includes both country names and codes.
· (string) –
• Id (string) – [REQUIRED] The distribution’s id.
• IfMatch (string) – The value of the ETag header you received when retrieving
the distribution’s configuration. For example: E2QWRUHAPOMQZL.
Return type dict
Returns
Response Syntax
{
'Distribution': {
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'InProgressInvalidationBatches': 123,
'DomainName': 'string',
276 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'ActiveTrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
{
'AwsAccountNumber': 'string',
'KeyPairIds': {
'Quantity': 123,
'Items': [
'string',
]
}
},
]
},
'DistributionConfig': {
'CallerReference': 'string',
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'DefaultRootObject': 'string',
'Origins': {
'Quantity': 123,
'Items': [
{
'Id': 'string',
'DomainName': 'string',
'OriginPath': 'string',
'S3OriginConfig': {
'OriginAccessIdentity': 'string'
},
'CustomOriginConfig': {
'HTTPPort': 123,
'HTTPSPort': 123,
'OriginProtocolPolicy': 'http-only'|'match-viewer'
}
},
]
},
'DefaultCacheBehavior': {
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
3.1. Services 277
Boto3 Documentation, Release 1.1.4
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-http
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
'CacheBehaviors': {
'Quantity': 123,
'Items': [
{
'PathPattern': 'string',
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
278 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELET
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'D
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
]
},
'CustomErrorResponses': {
'Quantity': 123,
'Items': [
{
'ErrorCode': 123,
'ResponsePagePath': 'string',
'ResponseCode': 'string',
'ErrorCachingMinTTL': 123
},
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'IncludeCookies': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False,
'ViewerCertificate': {
'IAMCertificateId': 'string',
'CloudFrontDefaultCertificate': True|False,
'SSLSupportMethod': 'sni-only'|'vip',
'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
},
'Restrictions': {
'GeoRestriction': {
'RestrictionType': 'blacklist'|'whitelist'|'none',
'Quantity': 123,
'Items': [
'string',
]
}
}
}
3.1. Services 279
Boto3 Documentation, Release 1.1.4
},
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– Distribution (dict) – The distribution’s information.
* Id (string) – The identifier for the distribution. For example: EDFD-
VBD632BHDS5.
* Status (string) – This response element indicates the current status
of the distribution. When the status is Deployed, the distribution’s
information is fully propagated throughout the Amazon CloudFront
system.
* LastModifiedTime (datetime) – The date and time the distribution
was last modified.
* InProgressInvalidationBatches (integer) – The number of invali-
dation batches currently in progress.
* DomainName (string) – The domain name corresponding to the
distribution. For example: d604721fxaaqy9.cloudfront.net.
* ActiveTrustedSigners (dict) – CloudFront automatically adds this
element to the response only if you’ve set up the distribution to serve
private content with signed URLs. The element lists the key pair IDs
that CloudFront is aware of for each trusted signer. The Signer child
element lists the AWS account number of the trusted signer (or an
empty Self element if the signer is you). The Signer element also
includes the IDs of any active key pairs associated with the trusted
signer’s AWS account. If no KeyPairId element appears for a Signer,
that signer can’t create working signed URLs.
· Enabled (boolean) – Each active trusted signer.
· Quantity (integer) – The number of unique trusted signers
included in all cache behaviors. For example, if three cache
behaviors all list the same three AWS accounts, the value of
Quantity for ActiveTrustedSigners will be 3.
· Items (list) – A complex type that contains one Signer com-
plex type for each unique trusted signer that is specified in the
TrustedSigners complex type, including trusted signers in the
default cache behavior and in all of the other cache behaviors.
· (dict) – A complex type that lists the AWS accounts that were
included in the TrustedSigners complex type, as well as their
active CloudFront key pair IDs, if any.
· AwsAccountNumber (string) – Specifies an AWS account
that can create signed URLs. Values: self, which indicates
that the AWS account that was used to create the distribution
can created signed URLs, or an AWS account number. Omit
the dashes in the account number.
· KeyPairIds (dict) – A complex type that lists the active
CloudFront key pairs, if any, that are associated with AwsAc-
countNumber.
· Quantity (integer) – The number of active CloudFront key
pairs for AwsAccountNumber.
· Items (list) – A complex type that lists the active CloudFront
key pairs, if any, that are associated with AwsAccountNum-
ber.
· (string) –
280 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* DistributionConfig (dict) – The current configuration information
for the distribution.
· CallerReference (string) – A unique number that ensures the
request can’t be replayed. If the CallerReference is new (no
matter the content of the DistributionConfig object), a new
distribution is created. If the CallerReference is a value you
already sent in a previous request to create a distribution,
and the content of the DistributionConfig is identical to the
original request (ignoring white space), the response includes
the same information returned to the original request. If the
CallerReference is a value you already sent in a previous re-
quest to create a distribution but the content of the Distribu-
tionConfig is different from the original request, CloudFront
returns a DistributionAlreadyExists error.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this dis-
tribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· DefaultRootObject (string) – The object that you want
CloudFront to return (for example, index.html) when an
end user requests the root URL for your distribution
(http://www.example.com) instead of an object in your dis-
tribution (http://www.example.com/index.html). Specifying
a default root object avoids exposing the contents of your dis-
tribution. If you don’t want to specify a default root object
when you create a distribution, include an empty Default-
RootObject element. To delete the default root object from
an existing distribution, update the distribution configuration
and include an empty DefaultRootObject element. To replace
the default root object, update the distribution configuration
and specify the new object.
· Origins (dict) – A complex type that contains information
about origins for this distribution.
· Quantity (integer) – The number of origins for this distribu-
tion.
· Items (list) – A complex type that contains origins for this
distribution.
· (dict) – A complex type that describes the Amazon S3 bucket
or the HTTP server (for example, a web server) from which
CloudFront gets your files.You must create at least one origin.
· Id (string) – A unique identifier for the origin. The value of
Id must be unique within the distribution. You use the value
of Id when you create a cache behavior. The Id identifies the
origin that CloudFront routes a request to when the request
matches the path pattern for that cache behavior.
· DomainName (string) – Amazon S3 origins: The DNS name
of the Amazon S3 bucket from which you want Cloud-
Front to get objects for this origin, for example, myaws-
bucket.s3.amazonaws.com. Custom origins: The DNS do-
3.1. Services 281
Boto3 Documentation, Release 1.1.4
main name for the HTTP server from which you want
CloudFront to get objects for this origin, for example,
www.example.com.
· OriginPath (string) – An optional element that causes Cloud-
Front to request your content from a directory in your Ama-
zon S3 bucket or your custom origin. When you include the
OriginPath element, specify the directory name, beginning
with a /. CloudFront appends the directory name to the value
of DomainName.
· S3OriginConfig (dict) – A complex type that contains infor-
mation about the Amazon S3 origin. If the origin is a custom
origin, use the CustomOriginConfig element instead.
· OriginAccessIdentity (string) – The CloudFront origin ac-
cess identity to associate with the origin. Use an origin ac-
cess identity to configure the origin so that end users can only
access objects in an Amazon S3 bucket through CloudFront.
If you want end users to be able to access objects using ei-
ther the CloudFront URL or the Amazon S3 URL, specify
an empty OriginAccessIdentity element. To delete the origin
access identity from an existing distribution, update the distri-
bution configuration and include an empty OriginAccessIden-
tity element. To replace the origin access identity, update the
distribution configuration and specify the new origin access
identity. Use the format origin-access-identity/cloudfront/Id
where Id is the value that CloudFront returned in the Id ele-
ment when you created the origin access identity.
· CustomOriginConfig (dict) – A complex type that contains
information about a custom origin. If the origin is an Amazon
S3 bucket, use the S3OriginConfig element instead.
· HTTPPort (integer) – The HTTP port the custom origin lis-
tens on.
· HTTPSPort (integer) – The HTTPS port the custom origin
listens on.
· OriginProtocolPolicy (string) – The origin protocol policy
to apply to your origin.
· DefaultCacheBehavior (dict) – A complex type that de-
scribes the default cache behavior if you do not specify a
CacheBehavior element or if files don’t match any of the val-
ues of PathPattern in CacheBehavior elements.You must cre-
ate exactly one default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
282 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
3.1. Services 283
Boto3 Documentation, Release 1.1.4
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
284 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CacheBehaviors (dict) – A complex type that contains zero
or more CacheBehavior elements.
· Quantity (integer) – The number of cache behaviors for this
distribution.
· Items (list) – Optional: A complex type that contains cache
behaviors for this distribution. If Quantity is 0, you can omit
Items.
· (dict) – A complex type that describes how CloudFront pro-
cesses requests. You can create up to 10 cache behav-
iors.You must create at least as many cache behaviors (in-
cluding the default cache behavior) as you have origins if you
want CloudFront to distribute objects from all of the origins.
Each cache behavior specifies the one origin from which you
want CloudFront to get objects. If you have two origins and
only the default cache behavior, the default cache behavior
will cause CloudFront to get objects from one of the ori-
gins, but the other origin will never be used. If you don’t
want to specify any cache behaviors, include only an empty
CacheBehaviors element. Don’t include an empty CacheBe-
havior element, or CloudFront returns a MalformedXML er-
ror. To delete all cache behaviors in an existing distribu-
tion, update the distribution configuration and include only an
empty CacheBehaviors element. To add, change, or remove
one or more cache behaviors, update the distribution configu-
ration and specify all of the cache behaviors that you want to
include in the updated distribution.
· PathPattern (string) – The pattern (for example, im-
ages/*.jpg) that specifies which requests you want this cache
behavior to apply to. When CloudFront receives an end-user
request, the requested path is compared with path patterns in
the order in which cache behaviors are listed in the distribu-
tion. The path pattern for the default cache behavior is * and
cannot be changed. If the request for an object does not match
the path pattern for any cache behaviors, CloudFront applies
the behavior in the default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
3.1. Services 285
Boto3 Documentation, Release 1.1.4
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
286 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
3.1. Services 287
Boto3 Documentation, Release 1.1.4
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CustomErrorResponses (dict) – A complex type that con-
tains zero or more CustomErrorResponse elements.
· Quantity (integer) – The number of custom error responses
for this distribution.
· Items (list) – Optional: A complex type that contains custom
error responses for this distribution. If Quantity is 0, you can
omit Items.
· (dict) – A complex type that describes how you’d prefer
CloudFront to respond to requests that result in either a 4xx or
5xx response. You can control whether a custom error page
should be displayed, what the desired response code should
be for this error page and how long should the error response
be cached by CloudFront. If you don’t want to specify any
custom error responses, include only an empty CustomEr-
rorResponses element. To delete all custom error responses
in an existing distribution, update the distribution configura-
tion and include only an empty CustomErrorResponses ele-
ment. To add, change, or remove one or more custom error
responses, update the distribution configuration and specify
all of the custom error responses that you want to include in
the updated distribution.
· ErrorCode (integer) – The 4xx or 5xx HTTP status code that
you want to customize. For a list of HTTP status codes that
you can customize, see CloudFront documentation.
· ResponsePagePath (string) – The path of the custom error
288 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
page (for example, /custom_404.html). The path is relative
to the distribution and must begin with a slash (/). If the path
includes any non-ASCII characters or unsafe characters as de-
fined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL
encode those characters. Do not URL encode any other char-
acters in the path, or CloudFront will not return the custom
error page to the viewer.
· ResponseCode (string) – The HTTP status code that you
want CloudFront to return with the custom error page to the
viewer. For a list of HTTP status codes that you can replace,
see CloudFront Documentation.
· ErrorCachingMinTTL (integer) – The minimum amount of
time you want HTTP error codes to stay in CloudFront caches
before CloudFront queries your origin to see whether the ob-
ject has been updated. You can specify a value from 0 to
31,536,000.
· Comment (string) – Any comments you want to include
about the distribution.
· Logging (dict) – A complex type that controls whether access
logs are written for the distribution.
· Enabled (boolean) – Specifies whether you want CloudFront
to save access logs to an Amazon S3 bucket. If you do not
want to enable logging when you create a distribution or if
you want to disable logging for an existing distribution, spec-
ify false for Enabled, and specify empty Bucket and Prefix
elements. If you specify false for Enabled but you specify
values for Bucket, prefix and IncludeCookies, the values are
automatically deleted.
· IncludeCookies (boolean) – Specifies whether you want
CloudFront to include cookies in access logs, specify true for
IncludeCookies. If you choose to include cookies in logs,
CloudFront logs all cookies regardless of how you configure
the cache behaviors for this distribution. If you do not want to
include cookies when you create a distribution or if you want
to disable include cookies for an existing distribution, specify
false for IncludeCookies.
· Bucket (string) – The Amazon S3 bucket to store the access
logs in, for example, myawslogbucket.s3.amazonaws.com.
· Prefix (string) – An optional string that you want CloudFront
to prefix to the access log filenames for this distribution, for
example, myprefix/. If you want to enable logging, but you do
not want to specify a prefix, you still must include an empty
Prefix element in the Logging element.
· PriceClass (string) – A complex type that contains informa-
tion about price class for this distribution.
· Enabled (boolean) – Whether the distribution is enabled to
accept end user requests for content.
· ViewerCertificate (dict) – A complex type that contains in-
formation about viewer certificates for this distribution.
· IAMCertificateId (string) – If you want viewers to use
HTTPS to request your objects and you’re using an al-
ternate domain name in your object URLs (for example,
https://example.com/logo.jpg), specify the IAM certificate
identifier of the custom viewer certificate for this distribution.
3.1. Services 289
Boto3 Documentation, Release 1.1.4
Specify either this value or CloudFrontDefaultCertificate.
· CloudFrontDefaultCertificate (boolean) – If you
want viewers to use HTTPS to request your objects
and you’re using the CloudFront domain name of
your distribution in your object URLs (for example,
https://d111111abcdef8.cloudfront.net/logo.jpg), set to true.
Omit this value if you are setting an IAMCertificateId.
· SSLSupportMethod (string) – If you specify a value for
IAMCertificateId, you must also specify how you want
CloudFront to serve HTTPS requests. Valid values are vip and
sni-only. If you specify vip, CloudFront uses dedicated IP ad-
dresses for your content and can respond to HTTPS requests
from any viewer. However, you must request permission to
use this feature, and you incur additional monthly charges. If
you specify sni-only, CloudFront can only respond to HTTPS
requests from viewers that support Server Name Indication
(SNI). All modern browsers support SNI, but some browsers
still in use don’t support SNI. Do not specify a value for
SSLSupportMethod if you specified true for CloudFrontDe-
faultCertificate.
· MinimumProtocolVersion (string) – Specify the minimum
version of the SSL protocol that you want CloudFront to use,
SSLv3 or TLSv1, for HTTPS connections. CloudFront will
serve your objects only to browsers or devices that support at
least the SSL version that you specify. The TLSv1 protocol is
more secure, so we recommend that you specify SSLv3 only
if your users are using browsers or devices that don’t support
TLSv1. If you’re using a custom certificate (if you specify a
value for IAMCertificateId) and if you’re using dedicated IP
(if you specify vip for SSLSupportMethod), you can choose
SSLv3 or TLSv1 as the MinimumProtocolVersion. If you’re
using a custom certificate (if you specify a value for IAM-
CertificateId) and if you’re using SNI (if you specify sni-only
for SSLSupportMethod), you must specify TLSv1 for Mini-
mumProtocolVersion.
· Restrictions (dict) – A complex type that identifies ways in
which you want to restrict distribution of your content.
· GeoRestriction (dict) – A complex type that controls the
countries in which your content is distributed. For more in-
formation about geo restriction, go to Customizing Error Re-
sponses in the Amazon CloudFront Developer Guide. Cloud-
Front determines the location of your users using MaxMind
GeoIP databases. For information about the accuracy of these
databases, see How accurate are your GeoIP databases? on
the MaxMind website.
· RestrictionType (string) – The method that you want to use
to restrict distribution of your content by country: - none: No
geo restriction is enabled, meaning access to content is not
restricted by client geo location. - blacklist: The Location el-
ements specify the countries in which you do not want Cloud-
Front to distribute your content. - whitelist: The Location el-
ements specify the countries in which you want CloudFront
to distribute your content.
· Quantity (integer) – When geo restriction is enabled, this is
290 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
the number of countries in your whitelist or blacklist. Other-
wise, when it is not enabled, Quantity is 0, and you can omit
Items.
· Items (list) – A complex type that contains a Location ele-
ment for each country in which you want CloudFront either to
distribute your content (whitelist) or not distribute your con-
tent (blacklist). The Location element is a two-letter, upper-
case country code for a country that you want to include in
your blacklist or whitelist. Include one Location element for
each country. CloudFront and MaxMind both use ISO 3166
country codes. For the current list of countries and the cor-
responding codes, see ISO 3166-1-alpha-2 code on the Inter-
national Organization for Standardization website. You can
also refer to the country list in the CloudFront console, which
includes both country names and codes.
· (string) –
– ETag (string) – The current version of the configuration. For example:
E2QWRUHAPOMQZL.
update_streaming_distribution(**kwargs)
Update a streaming distribution.
Request Syntax
response = client.update_streaming_distribution(
StreamingDistributionConfig={
'CallerReference': 'string',
'S3Origin': {
'DomainName': 'string',
'OriginAccessIdentity': 'string'
},
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False
},
Id='string',
IfMatch='string'
)
Parameters
3.1. Services 291
Boto3 Documentation, Release 1.1.4
• StreamingDistributionConfig (dict) – [REQUIRED] The streaming distribu-
tion’s configuration information.
– CallerReference (string) – [REQUIRED] A unique number that ensures
the request can’t be replayed. If the CallerReference is new (no matter the
content of the StreamingDistributionConfig object), a new streaming dis-
tribution is created. If the CallerReference is a value you already sent in a
previous request to create a streaming distribution, and the content of the
StreamingDistributionConfig is identical to the original request (ignoring
white space), the response includes the same information returned to the
original request. If the CallerReference is a value you already sent in a
previous request to create a streaming distribution but the content of the
StreamingDistributionConfig is different from the original request, Cloud-
Front returns a DistributionAlreadyExists error.
– S3Origin (dict) – [REQUIRED] A complex type that contains informa-
tion about the Amazon S3 bucket from which you want CloudFront to get
your media files for distribution.
* DomainName (string) – [REQUIRED] The DNS name of the S3
origin.
* OriginAccessIdentity (string) – [REQUIRED] Your S3 origin’s
origin access identity.
– Aliases (dict) – A complex type that contains information about CNAMEs
(alternate domain names), if any, for this streaming distribution.
* Quantity (integer) – [REQUIRED] The number of CNAMEs, if
any, for this distribution.
* Items (list) – Optional: A complex type that contains CNAME el-
ements, if any, for this distribution. If Quantity is 0, you can omit
Items.
· (string) –
– Comment (string) – [REQUIRED] Any comments you want to include
about the streaming distribution.
– Logging (dict) – A complex type that controls whether access logs are
written for the streaming distribution.
* Enabled (boolean) – [REQUIRED] Specifies whether you want
CloudFront to save access logs to an Amazon S3 bucket. If you do
not want to enable logging when you create a streaming distribution
or if you want to disable logging for an existing streaming distribu-
tion, specify false for Enabled, and specify empty Bucket and Prefix
elements. If you specify false for Enabled but you specify values for
Bucket and Prefix, the values are automatically deleted.
* Bucket (string) – [REQUIRED] The Amazon S3 bucket
to store the access logs in, for example, myawslog-
bucket.s3.amazonaws.com.
* Prefix (string) – [REQUIRED] An optional string that you want
CloudFront to prefix to the access log filenames for this streaming
distribution, for example, myprefix/. If you want to enable logging,
but you do not want to specify a prefix, you still must include an
empty Prefix element in the Logging element.
– TrustedSigners (dict) – [REQUIRED] A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed URLs for
private content. If you want to require signed URLs in requests for ob-
jects in the target origin that match the PathPattern for this cache behavior,
specify true for Enabled, and specify the applicable values for Quantity
and Items. For more information, go to Using a Signed URL to Serve Pri-
vate Content in the Amazon CloudFront Developer Guide. If you don’t
292 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
want to require signed URLs in requests for objects that match PathPat-
tern, specify false for Enabled and 0 for Quantity. Omit Items. To add,
change, or remove one or more trusted signers, change Enabled to true (if
it’s currently false), change Quantity as applicable, and specify all of the
trusted signers that you want to include in the updated distribution.
* Enabled (boolean) – [REQUIRED] Specifies whether you want to
require end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
* Quantity (integer) – [REQUIRED] The number of trusted signers
for this cache behavior.
* Items (list) – Optional: A complex type that contains trusted signers
for this cache behavior. If Quantity is 0, you can omit Items.
· (string) –
– PriceClass (string) – A complex type that contains information about
price class for this streaming distribution.
– Enabled (boolean) – [REQUIRED] Whether the streaming distribution
is enabled to accept end user requests for content.
• Id (string) – [REQUIRED] The streaming distribution’s id.
• IfMatch (string) – The value of the ETag header you received when
retrieving the streaming distribution’s configuration. For example:
E2QWRUHAPOMQZL.
Return type dict
Returns
Response Syntax
{
'StreamingDistribution': {
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'DomainName': 'string',
'ActiveTrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
{
'AwsAccountNumber': 'string',
'KeyPairIds': {
'Quantity': 123,
'Items': [
'string',
]
}
},
]
},
'StreamingDistributionConfig': {
'CallerReference': 'string',
'S3Origin': {
'DomainName': 'string',
'OriginAccessIdentity': 'string'
},
'Aliases': {
'Quantity': 123,
'Items': [
'string',
3.1. Services 293
Boto3 Documentation, Release 1.1.4
]
},
'Comment': 'string',
'Logging': {
'Enabled': True|False,
'Bucket': 'string',
'Prefix': 'string'
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False
}
},
'ETag': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– StreamingDistribution (dict) – The streaming distribution’s information.
* Id (string) – The identifier for the streaming distribution. For exam-
ple: EGTXBD79H29TRA8.
* Status (string) – The current status of the streaming distribution.
When the status is Deployed, the distribution’s information is fully
propagated throughout the Amazon CloudFront system.
* LastModifiedTime (datetime) – The date and time the distribution
was last modified.
* DomainName (string) – The domain name corre-
sponding to the streaming distribution. For example:
s5c39gqb8ow64r.cloudfront.net.
* ActiveTrustedSigners (dict) – CloudFront automatically adds this
element to the response only if you’ve set up the distribution to serve
private content with signed URLs. The element lists the key pair IDs
that CloudFront is aware of for each trusted signer. The Signer child
element lists the AWS account number of the trusted signer (or an
empty Self element if the signer is you). The Signer element also
includes the IDs of any active key pairs associated with the trusted
signer’s AWS account. If no KeyPairId element appears for a Signer,
that signer can’t create working signed URLs.
· Enabled (boolean) – Each active trusted signer.
· Quantity (integer) – The number of unique trusted signers
included in all cache behaviors. For example, if three cache
behaviors all list the same three AWS accounts, the value of
Quantity for ActiveTrustedSigners will be 3.
· Items (list) – A complex type that contains one Signer com-
plex type for each unique trusted signer that is specified in the
TrustedSigners complex type, including trusted signers in the
default cache behavior and in all of the other cache behaviors.
· (dict) – A complex type that lists the AWS accounts that were
included in the TrustedSigners complex type, as well as their
294 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
active CloudFront key pair IDs, if any.
· AwsAccountNumber (string) – Specifies an AWS account
that can create signed URLs. Values: self, which indicates
that the AWS account that was used to create the distribution
can created signed URLs, or an AWS account number. Omit
the dashes in the account number.
· KeyPairIds (dict) – A complex type that lists the active
CloudFront key pairs, if any, that are associated with AwsAc-
countNumber.
· Quantity (integer) – The number of active CloudFront key
pairs for AwsAccountNumber.
· Items (list) – A complex type that lists the active CloudFront
key pairs, if any, that are associated with AwsAccountNum-
ber.
· (string) –
* StreamingDistributionConfig (dict) – The current configuration
information for the streaming distribution.
· CallerReference (string) – A unique number that ensures
the request can’t be replayed. If the CallerReference is new
(no matter the content of the StreamingDistributionConfig ob-
ject), a new streaming distribution is created. If the Caller-
Reference is a value you already sent in a previous request to
create a streaming distribution, and the content of the Stream-
ingDistributionConfig is identical to the original request (ig-
noring white space), the response includes the same informa-
tion returned to the original request. If the CallerReference
is a value you already sent in a previous request to create a
streaming distribution but the content of the StreamingDis-
tributionConfig is different from the original request, Cloud-
Front returns a DistributionAlreadyExists error.
· S3Origin (dict) – A complex type that contains information
about the Amazon S3 bucket from which you want Cloud-
Front to get your media files for distribution.
· DomainName (string) – The DNS name of the S3 origin.
· OriginAccessIdentity (string) – Your S3 origin’s origin ac-
cess identity.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this
streaming distribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· Comment (string) – Any comments you want to include
about the streaming distribution.
· Logging (dict) – A complex type that controls whether access
logs are written for the streaming distribution.
· Enabled (boolean) – Specifies whether you want CloudFront
to save access logs to an Amazon S3 bucket. If you do not
want to enable logging when you create a streaming distribu-
tion or if you want to disable logging for an existing stream-
ing distribution, specify false for Enabled, and specify empty
3.1. Services 295
Boto3 Documentation, Release 1.1.4
Bucket and Prefix elements. If you specify false for Enabled
but you specify values for Bucket and Prefix, the values are
automatically deleted.
· Bucket (string) – The Amazon S3 bucket to store the access
logs in, for example, myawslogbucket.s3.amazonaws.com.
· Prefix (string) – An optional string that you want CloudFront
to prefix to the access log filenames for this streaming distri-
bution, for example, myprefix/. If you want to enable logging,
but you do not want to specify a prefix, you still must include
an empty Prefix element in the Logging element.
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· PriceClass (string) – A complex type that contains informa-
tion about price class for this streaming distribution.
· Enabled (boolean) – Whether the streaming distribution is
enabled to accept end user requests for content.
– ETag (string) – The current version of the configuration. For example:
E2QWRUHAPOMQZL.
Paginators
The available paginators are:
• CloudFront.Paginator.ListCloudFrontOriginAccessIdentities
• CloudFront.Paginator.ListDistributions
• CloudFront.Paginator.ListInvalidations
• CloudFront.Paginator.ListStreamingDistributions
class CloudFront.Paginator.ListCloudFrontOriginAccessIdentities
296 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
paginator = client.get_paginator('list_cloud_front_origin_access_identities')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudFront.Client.list_cloud_front_origin_access_identities().
Request Syntax
response_iterator = paginator.paginate(
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
• MaxItems (integer) –
The total number of items to return. If the total number of items available is
more than the value specified in max-items then a NextToken will be provided
in the output that you can use to resume pagination.
• PageSize (integer) –
The size of each page.
• StartingToken (string) –
A token to specify where to start paginating. This is the NextToken from a
previous response.
Return type dict
Returns
Response Syntax
{
'CloudFrontOriginAccessIdentityList': {
'Marker': 'string',
'NextMarker': 'string',
'MaxItems': 123,
'IsTruncated': True|False,
'Quantity': 123,
'Items': [
{
'Id': 'string',
'S3CanonicalUserId': 'string',
'Comment': 'string'
},
]
},
'NextToken': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– CloudFrontOriginAccessIdentityList (dict) – The CloudFrontOriginAc-
cessIdentityList type.
3.1. Services 297
Boto3 Documentation, Release 1.1.4
* Marker (string) – The value you provided for the Marker request
parameter.
* NextMarker (string) – If IsTruncated is true, this element is present
and contains the value you can use for the Marker request parameter
to continue listing your origin access identities where they left off.
* MaxItems (integer) – The value you provided for the MaxItems
request parameter.
* IsTruncated (boolean) – A flag that indicates whether more origin
access identities remain to be listed. If your results were truncated,
you can make a follow-up pagination request using the Marker re-
quest parameter to retrieve more items in the list.
* Quantity (integer) – The number of CloudFront origin access iden-
tities that were created by the current AWS account.
* Items (list) – A complex type that contains one CloudFrontOrig-
inAccessIdentitySummary element for each origin access identity
that was created by the current AWS account.
· (dict) – Summary of the information about a CloudFront ori-
gin access identity.
· Id (string) – The ID for the origin access identity. For exam-
ple: E74FTE3AJFJ256A.
· S3CanonicalUserId (string) – The Amazon S3 canonical
user ID for the origin access identity, which you use when
giving the origin access identity read permission to an object
in Amazon S3.
· Comment (string) – The comment for this origin access iden-
tity, as originally specified when created.
– NextToken (string) –
A token to resume pagination.
class CloudFront.Paginator.ListDistributions
paginator = client.get_paginator('list_distributions')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudFront.Client.list_distributions().
Request Syntax
response_iterator = paginator.paginate(
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
• MaxItems (integer) –
The total number of items to return. If the total number of items available is
more than the value specified in max-items then a NextToken will be provided
in the output that you can use to resume pagination.
298 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• PageSize (integer) –
The size of each page.
• StartingToken (string) –
A token to specify where to start paginating. This is the NextToken from a
previous response.
Return type dict
Returns
Response Syntax
{
'DistributionList': {
'Marker': 'string',
'NextMarker': 'string',
'MaxItems': 123,
'IsTruncated': True|False,
'Quantity': 123,
'Items': [
{
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'DomainName': 'string',
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'Origins': {
'Quantity': 123,
'Items': [
{
'Id': 'string',
'DomainName': 'string',
'OriginPath': 'string',
'S3OriginConfig': {
'OriginAccessIdentity': 'string'
},
'CustomOriginConfig': {
'HTTPPort': 123,
'HTTPSPort': 123,
'OriginProtocolPolicy': 'http-only'|'match-viewer'
}
},
]
},
'DefaultCacheBehavior': {
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
3.1. Services 299
Boto3 Documentation, Release 1.1.4
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redirect-to-
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELETE',
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'DELET
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
'CacheBehaviors': {
'Quantity': 123,
'Items': [
{
'PathPattern': 'string',
'TargetOriginId': 'string',
'ForwardedValues': {
'QueryString': True|False,
'Cookies': {
'Forward': 'none'|'whitelist'|'all',
'WhitelistedNames': {
'Quantity': 123,
'Items': [
'string',
]
}
},
'Headers': {
'Quantity': 123,
'Items': [
'string',
]
}
300 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'ViewerProtocolPolicy': 'allow-all'|'https-only'|'redi
'MinTTL': 123,
'AllowedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS'|'D
],
'CachedMethods': {
'Quantity': 123,
'Items': [
'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'OPTIONS
]
}
},
'SmoothStreaming': True|False,
'DefaultTTL': 123,
'MaxTTL': 123
},
]
},
'CustomErrorResponses': {
'Quantity': 123,
'Items': [
{
'ErrorCode': 123,
'ResponsePagePath': 'string',
'ResponseCode': 'string',
'ErrorCachingMinTTL': 123
},
]
},
'Comment': 'string',
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False,
'ViewerCertificate': {
'IAMCertificateId': 'string',
'CloudFrontDefaultCertificate': True|False,
'SSLSupportMethod': 'sni-only'|'vip',
'MinimumProtocolVersion': 'SSLv3'|'TLSv1'
},
'Restrictions': {
'GeoRestriction': {
'RestrictionType': 'blacklist'|'whitelist'|'none',
'Quantity': 123,
'Items': [
'string',
]
}
}
},
3.1. Services 301
Boto3 Documentation, Release 1.1.4
]
},
'NextToken': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– DistributionList (dict) – The DistributionList type.
* Marker (string) – The value you provided for the Marker request
parameter.
* NextMarker (string) – If IsTruncated is true, this element is present
and contains the value you can use for the Marker request parameter
to continue listing your distributions where they left off.
* MaxItems (integer) – The value you provided for the MaxItems
request parameter.
* IsTruncated (boolean) – A flag that indicates whether more dis-
tributions remain to be listed. If your results were truncated, you
can make a follow-up pagination request using the Marker request
parameter to retrieve more distributions in the list.
* Quantity (integer) – The number of distributions that were created
by the current AWS account.
* Items (list) – A complex type that contains one DistributionSum-
mary element for each distribution that was created by the current
AWS account.
· (dict) – A summary of the information for an Amazon Cloud-
Front distribution.
· Id (string) – The identifier for the distribution. For example:
EDFDVBD632BHDS5.
· Status (string) – This response element indicates the current
status of the distribution. When the status is Deployed, the
distribution’s information is fully propagated throughout the
Amazon CloudFront system.
· LastModifiedTime (datetime) – The date and time the distri-
bution was last modified.
· DomainName (string) – The domain name cor-
responding to the distribution. For example:
d604721fxaaqy9.cloudfront.net.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this dis-
tribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· Origins (dict) – A complex type that contains information
about origins for this distribution.
· Quantity (integer) – The number of origins for this distribu-
tion.
· Items (list) – A complex type that contains origins for this
distribution.
· (dict) – A complex type that describes the Amazon S3 bucket
or the HTTP server (for example, a web server) from which
302 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
CloudFront gets your files.You must create at least one origin.
· Id (string) – A unique identifier for the origin. The value of
Id must be unique within the distribution. You use the value
of Id when you create a cache behavior. The Id identifies the
origin that CloudFront routes a request to when the request
matches the path pattern for that cache behavior.
· DomainName (string) – Amazon S3 origins: The DNS name
of the Amazon S3 bucket from which you want Cloud-
Front to get objects for this origin, for example, myaws-
bucket.s3.amazonaws.com. Custom origins: The DNS do-
main name for the HTTP server from which you want
CloudFront to get objects for this origin, for example,
www.example.com.
· OriginPath (string) – An optional element that causes Cloud-
Front to request your content from a directory in your Ama-
zon S3 bucket or your custom origin. When you include the
OriginPath element, specify the directory name, beginning
with a /. CloudFront appends the directory name to the value
of DomainName.
· S3OriginConfig (dict) – A complex type that contains infor-
mation about the Amazon S3 origin. If the origin is a custom
origin, use the CustomOriginConfig element instead.
· OriginAccessIdentity (string) – The CloudFront origin ac-
cess identity to associate with the origin. Use an origin ac-
cess identity to configure the origin so that end users can only
access objects in an Amazon S3 bucket through CloudFront.
If you want end users to be able to access objects using ei-
ther the CloudFront URL or the Amazon S3 URL, specify
an empty OriginAccessIdentity element. To delete the origin
access identity from an existing distribution, update the distri-
bution configuration and include an empty OriginAccessIden-
tity element. To replace the origin access identity, update the
distribution configuration and specify the new origin access
identity. Use the format origin-access-identity/cloudfront/Id
where Id is the value that CloudFront returned in the Id ele-
ment when you created the origin access identity.
· CustomOriginConfig (dict) – A complex type that contains
information about a custom origin. If the origin is an Amazon
S3 bucket, use the S3OriginConfig element instead.
· HTTPPort (integer) – The HTTP port the custom origin lis-
tens on.
· HTTPSPort (integer) – The HTTPS port the custom origin
listens on.
· OriginProtocolPolicy (string) – The origin protocol policy
to apply to your origin.
· DefaultCacheBehavior (dict) – A complex type that de-
scribes the default cache behavior if you do not specify a
CacheBehavior element or if files don’t match any of the val-
ues of PathPattern in CacheBehavior elements.You must cre-
ate exactly one default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
3.1. Services 303
Boto3 Documentation, Release 1.1.4
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
304 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
3.1. Services 305
Boto3 Documentation, Release 1.1.4
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CacheBehaviors (dict) – A complex type that contains zero
or more CacheBehavior elements.
· Quantity (integer) – The number of cache behaviors for this
distribution.
· Items (list) – Optional: A complex type that contains cache
behaviors for this distribution. If Quantity is 0, you can omit
Items.
· (dict) – A complex type that describes how CloudFront pro-
cesses requests. You can create up to 10 cache behav-
iors.You must create at least as many cache behaviors (in-
cluding the default cache behavior) as you have origins if you
want CloudFront to distribute objects from all of the origins.
Each cache behavior specifies the one origin from which you
want CloudFront to get objects. If you have two origins and
only the default cache behavior, the default cache behavior
will cause CloudFront to get objects from one of the ori-
gins, but the other origin will never be used. If you don’t
want to specify any cache behaviors, include only an empty
CacheBehaviors element. Don’t include an empty CacheBe-
havior element, or CloudFront returns a MalformedXML er-
ror. To delete all cache behaviors in an existing distribu-
tion, update the distribution configuration and include only an
empty CacheBehaviors element. To add, change, or remove
one or more cache behaviors, update the distribution configu-
ration and specify all of the cache behaviors that you want to
include in the updated distribution.
· PathPattern (string) – The pattern (for example, im-
306 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
ages/*.jpg) that specifies which requests you want this cache
behavior to apply to. When CloudFront receives an end-user
request, the requested path is compared with path patterns in
the order in which cache behaviors are listed in the distribu-
tion. The path pattern for the default cache behavior is * and
cannot be changed. If the request for an object does not match
the path pattern for any cache behaviors, CloudFront applies
the behavior in the default cache behavior.
· TargetOriginId (string) – The value of ID for the origin that
you want CloudFront to route requests to when a request
matches the path pattern either for a cache behavior or for
the default cache behavior.
· ForwardedValues (dict) – A complex type that specifies how
CloudFront handles query strings, cookies and headers.
· QueryString (boolean) – Indicates whether you want Cloud-
Front to forward query strings to the origin that is associated
with this cache behavior. If so, specify true; if not, specify
false.
· Cookies (dict) – A complex type that specifies how Cloud-
Front handles cookies.
· Forward (string) – Use this element to specify whether you
want CloudFront to forward cookies to the origin that is asso-
ciated with this cache behavior. You can specify all, none or
whitelist. If you choose All, CloudFront forwards all cookies
regardless of how many your application uses.
· WhitelistedNames (dict) – A complex type that specifies the
whitelisted cookies, if any, that you want CloudFront to for-
ward to your origin that is associated with this cache behavior.
· Quantity (integer) – The number of whitelisted cookies for
this cache behavior.
· Items (list) – Optional: A complex type that contains
whitelisted cookies for this cache behavior. If Quantity is 0,
you can omit Items.
· (string) –
· Headers (dict) – A complex type that specifies the Headers,
if any, that you want CloudFront to vary upon for this cache
behavior.
· Quantity (integer) – The number of different headers that you
want CloudFront to forward to the origin and to vary on for
this cache behavior. The maximum number of headers that
you can specify by name is 10. If you want CloudFront to for-
ward all headers to the origin and vary on all of them, specify
1 for Quantity and * for Name. If you don’t want CloudFront
to forward any additional headers to the origin or to vary on
any headers, specify 0 for Quantity and omit Items.
· Items (list) – Optional: A complex type that contains a Name
element for each header that you want CloudFront to forward
to the origin and to vary on for this cache behavior. If Quantity
is 0, omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
3.1. Services 307
Boto3 Documentation, Release 1.1.4
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· ViewerProtocolPolicy (string) – Use this element to specify
the protocol that users can use to access the files in the origin
specified by TargetOriginId when a request matches the path
pattern in PathPattern. If you want CloudFront to allow end
users to use any available protocol, specify allow-all. If you
want CloudFront to require HTTPS, specify https. If you want
CloudFront to respond to an HTTP request with an HTTP sta-
tus code of 301 (Moved Permanently) and the HTTPS URL,
specify redirect-to-https. The viewer then resubmits the re-
quest using the HTTPS URL.
· MinTTL (integer) – The minimum amount of time that you
want objects to stay in CloudFront caches before CloudFront
queries your origin to see whether the object has been up-
dated.You can specify a value from 0 to 3,153,600,000 sec-
onds (100 years).
· AllowedMethods (dict) – A complex type that controls which
HTTP methods CloudFront processes and forwards to your
Amazon S3 bucket or your custom origin. There are three
choices: - CloudFront forwards only GET and HEAD re-
quests. - CloudFront forwards only GET, HEAD and OP-
TIONS requests. - CloudFront forwards GET, HEAD, OP-
TIONS, PUT, PATCH, POST, and DELETE requests. If you
pick the third choice, you may need to restrict access to your
Amazon S3 bucket or to your custom origin so users can’t
perform operations that you don’t want them to. For example,
you may not want users to have permission to delete objects
from your origin.
· Quantity (integer) – The number of HTTP methods that you
want CloudFront to forward to your origin. Valid values are 2
(for GET and HEAD requests), 3 (for GET, HEAD and OP-
TIONS requests) and 7 (for GET, HEAD, OPTIONS, PUT,
PATCH, POST, and DELETE requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to process and forward to your
origin.
308 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (string) –
· CachedMethods (dict) – A complex type that controls
whether CloudFront caches the response to requests using the
specified HTTP methods. There are two choices: - Cloud-
Front caches responses to GET and HEAD requests. - Cloud-
Front caches responses to GET, HEAD, and OPTIONS re-
quests. If you pick the second choice for your S3 Origin,
you may need to forward Access-Control-Request-Method,
Access-Control-Request-Headers and Origin headers for the
responses to be cached correctly.
· Quantity (integer) – The number of HTTP methods for which
you want CloudFront to cache responses. Valid values are 2
(for caching responses to GET and HEAD requests) and 3 (for
caching responses to GET, HEAD, and OPTIONS requests).
· Items (list) – A complex type that contains the HTTP meth-
ods that you want CloudFront to cache responses to.
· (string) –
· SmoothStreaming (boolean) – Indicates whether you want to
distribute media files in Microsoft Smooth Streaming format
using the origin that is associated with this cache behavior. If
so, specify true; if not, specify false.
· DefaultTTL (integer) – If you don’t configure your origin to
add a Cache-Control max-age directive or an Expires header,
DefaultTTL is the default amount of time (in seconds) that an
object is in a CloudFront cache before CloudFront forwards
another request to your origin to determine whether the ob-
ject has been updated. The value that you specify applies only
when your origin does not add HTTP headers such as Cache-
Control max-age, Cache-Control s-maxage, and Expires to
objects. You can specify a value from 0 to 3,153,600,000
seconds (100 years).
· MaxTTL (integer) – The maximum amount of time (in sec-
onds) that an object is in a CloudFront cache before Cloud-
Front forwards another request to your origin to determine
whether the object has been updated. The value that you
specify applies only when your origin adds HTTP headers
such as Cache-Control max-age, Cache-Control s-maxage,
and Expires to objects. You can specify a value from 0 to
3,153,600,000 seconds (100 years).
· CustomErrorResponses (dict) – A complex type that con-
tains zero or more CustomErrorResponses elements.
· Quantity (integer) – The number of custom error responses
for this distribution.
· Items (list) – Optional: A complex type that contains custom
error responses for this distribution. If Quantity is 0, you can
omit Items.
· (dict) – A complex type that describes how you’d prefer
CloudFront to respond to requests that result in either a 4xx or
5xx response. You can control whether a custom error page
should be displayed, what the desired response code should
be for this error page and how long should the error response
be cached by CloudFront. If you don’t want to specify any
custom error responses, include only an empty CustomEr-
rorResponses element. To delete all custom error responses
3.1. Services 309
Boto3 Documentation, Release 1.1.4
in an existing distribution, update the distribution configura-
tion and include only an empty CustomErrorResponses ele-
ment. To add, change, or remove one or more custom error
responses, update the distribution configuration and specify
all of the custom error responses that you want to include in
the updated distribution.
· ErrorCode (integer) – The 4xx or 5xx HTTP status code that
you want to customize. For a list of HTTP status codes that
you can customize, see CloudFront documentation.
· ResponsePagePath (string) – The path of the custom error
page (for example, /custom_404.html). The path is relative
to the distribution and must begin with a slash (/). If the path
includes any non-ASCII characters or unsafe characters as de-
fined in RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt), URL
encode those characters. Do not URL encode any other char-
acters in the path, or CloudFront will not return the custom
error page to the viewer.
· ResponseCode (string) – The HTTP status code that you
want CloudFront to return with the custom error page to the
viewer. For a list of HTTP status codes that you can replace,
see CloudFront Documentation.
· ErrorCachingMinTTL (integer) – The minimum amount of
time you want HTTP error codes to stay in CloudFront caches
before CloudFront queries your origin to see whether the ob-
ject has been updated. You can specify a value from 0 to
31,536,000.
· Comment (string) – The comment originally specified when
this distribution was created.
· PriceClass (string) –
· Enabled (boolean) – Whether the distribution is enabled to
accept end user requests for content.
· ViewerCertificate (dict) – A complex type that contains in-
formation about viewer certificates for this distribution.
· IAMCertificateId (string) – If you want viewers to use
HTTPS to request your objects and you’re using an al-
ternate domain name in your object URLs (for example,
https://example.com/logo.jpg), specify the IAM certificate
identifier of the custom viewer certificate for this distribution.
Specify either this value or CloudFrontDefaultCertificate.
· CloudFrontDefaultCertificate (boolean) – If you
want viewers to use HTTPS to request your objects
and you’re using the CloudFront domain name of
your distribution in your object URLs (for example,
https://d111111abcdef8.cloudfront.net/logo.jpg), set to true.
Omit this value if you are setting an IAMCertificateId.
· SSLSupportMethod (string) – If you specify a value for
IAMCertificateId, you must also specify how you want
CloudFront to serve HTTPS requests. Valid values are vip and
sni-only. If you specify vip, CloudFront uses dedicated IP ad-
dresses for your content and can respond to HTTPS requests
from any viewer. However, you must request permission to
use this feature, and you incur additional monthly charges. If
you specify sni-only, CloudFront can only respond to HTTPS
requests from viewers that support Server Name Indication
310 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
(SNI). All modern browsers support SNI, but some browsers
still in use don’t support SNI. Do not specify a value for
SSLSupportMethod if you specified true for CloudFrontDe-
faultCertificate.
· MinimumProtocolVersion (string) – Specify the minimum
version of the SSL protocol that you want CloudFront to use,
SSLv3 or TLSv1, for HTTPS connections. CloudFront will
serve your objects only to browsers or devices that support at
least the SSL version that you specify. The TLSv1 protocol is
more secure, so we recommend that you specify SSLv3 only
if your users are using browsers or devices that don’t support
TLSv1. If you’re using a custom certificate (if you specify a
value for IAMCertificateId) and if you’re using dedicated IP
(if you specify vip for SSLSupportMethod), you can choose
SSLv3 or TLSv1 as the MinimumProtocolVersion. If you’re
using a custom certificate (if you specify a value for IAM-
CertificateId) and if you’re using SNI (if you specify sni-only
for SSLSupportMethod), you must specify TLSv1 for Mini-
mumProtocolVersion.
· Restrictions (dict) – A complex type that identifies ways in
which you want to restrict distribution of your content.
· GeoRestriction (dict) – A complex type that controls the
countries in which your content is distributed. For more in-
formation about geo restriction, go to Customizing Error Re-
sponses in the Amazon CloudFront Developer Guide. Cloud-
Front determines the location of your users using MaxMind
GeoIP databases. For information about the accuracy of these
databases, see How accurate are your GeoIP databases? on
the MaxMind website.
· RestrictionType (string) – The method that you want to use
to restrict distribution of your content by country: - none: No
geo restriction is enabled, meaning access to content is not
restricted by client geo location. - blacklist: The Location el-
ements specify the countries in which you do not want Cloud-
Front to distribute your content. - whitelist: The Location el-
ements specify the countries in which you want CloudFront
to distribute your content.
· Quantity (integer) – When geo restriction is enabled, this is
the number of countries in your whitelist or blacklist. Other-
wise, when it is not enabled, Quantity is 0, and you can omit
Items.
· Items (list) – A complex type that contains a Location ele-
ment for each country in which you want CloudFront either to
distribute your content (whitelist) or not distribute your con-
tent (blacklist). The Location element is a two-letter, upper-
case country code for a country that you want to include in
your blacklist or whitelist. Include one Location element for
each country. CloudFront and MaxMind both use ISO 3166
country codes. For the current list of countries and the cor-
responding codes, see ISO 3166-1-alpha-2 code on the Inter-
national Organization for Standardization website. You can
also refer to the country list in the CloudFront console, which
includes both country names and codes.
· (string) –
3.1. Services 311
Boto3 Documentation, Release 1.1.4
– NextToken (string) –
A token to resume pagination.
class CloudFront.Paginator.ListInvalidations
paginator = client.get_paginator('list_invalidations')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudFront.Client.list_invalidations().
Request Syntax
response_iterator = paginator.paginate(
DistributionId='string',
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• DistributionId (string) – [REQUIRED] The distribution’s id.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'InvalidationList': {
'Marker': 'string',
'NextMarker': 'string',
'MaxItems': 123,
'IsTruncated': True|False,
'Quantity': 123,
'Items': [
{
'Id': 'string',
'CreateTime': datetime(2015, 1, 1),
'Status': 'string'
},
]
312 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
'NextToken': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– InvalidationList (dict) – Information about invalidation batches.
* Marker (string) – The value you provided for the Marker request
parameter.
* NextMarker (string) – If IsTruncated is true, this element is present
and contains the value you can use for the Marker request parameter
to continue listing your invalidation batches where they left off.
* MaxItems (integer) – The value you provided for the MaxItems
request parameter.
* IsTruncated (boolean) – A flag that indicates whether more in-
validation batch requests remain to be listed. If your results were
truncated, you can make a follow-up pagination request using the
Marker request parameter to retrieve more invalidation batches in
the list.
* Quantity (integer) – The number of invalidation batches that were
created by the current AWS account.
* Items (list) – A complex type that contains one InvalidationSum-
mary element for each invalidation batch that was created by the
current AWS account.
· (dict) – Summary of an invalidation request.
· Id (string) – The unique ID for an invalidation request.
· CreateTime (datetime) –
· Status (string) – The status of an invalidation request.
– NextToken (string) –
A token to resume pagination.
class CloudFront.Paginator.ListStreamingDistributions
paginator = client.get_paginator('list_streaming_distributions')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudFront.Client.list_streaming_distributions().
Request Syntax
response_iterator = paginator.paginate(
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
• MaxItems (integer) –
The total number of items to return. If the total number of items available is
more than the value specified in max-items then a NextToken will be provided
3.1. Services 313
Boto3 Documentation, Release 1.1.4
in the output that you can use to resume pagination.
• PageSize (integer) –
The size of each page.
• StartingToken (string) –
A token to specify where to start paginating. This is the NextToken from a
previous response.
Return type dict
Returns
Response Syntax
{
'StreamingDistributionList': {
'Marker': 'string',
'NextMarker': 'string',
'MaxItems': 123,
'IsTruncated': True|False,
'Quantity': 123,
'Items': [
{
'Id': 'string',
'Status': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'DomainName': 'string',
'S3Origin': {
'DomainName': 'string',
'OriginAccessIdentity': 'string'
},
'Aliases': {
'Quantity': 123,
'Items': [
'string',
]
},
'TrustedSigners': {
'Enabled': True|False,
'Quantity': 123,
'Items': [
'string',
]
},
'Comment': 'string',
'PriceClass': 'PriceClass_100'|'PriceClass_200'|'PriceClass_All',
'Enabled': True|False
},
]
},
'NextToken': 'string'
}
Response Structure
• (dict) – The returned result of the corresponding request.
– StreamingDistributionList (dict) – The StreamingDistributionList type.
* Marker (string) – The value you provided for the Marker request
parameter.
* NextMarker (string) – If IsTruncated is true, this element is present
and contains the value you can use for the Marker request parameter
314 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
to continue listing your streaming distributions where they left off.
* MaxItems (integer) – The value you provided for the MaxItems
request parameter.
* IsTruncated (boolean) – A flag that indicates whether more stream-
ing distributions remain to be listed. If your results were truncated,
you can make a follow-up pagination request using the Marker re-
quest parameter to retrieve more distributions in the list.
* Quantity (integer) – The number of streaming distributions that
were created by the current AWS account.
* Items (list) – A complex type that contains one StreamingDistribu-
tionSummary element for each distribution that was created by the
current AWS account.
· (dict) – A summary of the information for an Amazon Cloud-
Front streaming distribution.
· Id (string) – The identifier for the distribution. For example:
EDFDVBD632BHDS5.
· Status (string) – Indicates the current status of the distribu-
tion. When the status is Deployed, the distribution’s informa-
tion is fully propagated throughout the Amazon CloudFront
system.
· LastModifiedTime (datetime) – The date and time the distri-
bution was last modified.
· DomainName (string) – The domain name cor-
responding to the distribution. For example:
d604721fxaaqy9.cloudfront.net.
· S3Origin (dict) – A complex type that contains information
about the Amazon S3 bucket from which you want Cloud-
Front to get your media files for distribution.
· DomainName (string) – The DNS name of the S3 origin.
· OriginAccessIdentity (string) – Your S3 origin’s origin ac-
cess identity.
· Aliases (dict) – A complex type that contains information
about CNAMEs (alternate domain names), if any, for this
streaming distribution.
· Quantity (integer) – The number of CNAMEs, if any, for this
distribution.
· Items (list) – Optional: A complex type that contains
CNAME elements, if any, for this distribution. If Quantity
is 0, you can omit Items.
· (string) –
· TrustedSigners (dict) – A complex type that specifies the
AWS accounts, if any, that you want to allow to create signed
URLs for private content. If you want to require signed URLs
in requests for objects in the target origin that match the Path-
Pattern for this cache behavior, specify true for Enabled, and
specify the applicable values for Quantity and Items. For
more information, go to Using a Signed URL to Serve Private
Content in the Amazon CloudFront Developer Guide. If you
don’t want to require signed URLs in requests for objects that
match PathPattern, specify false for Enabled and 0 for Quan-
tity. Omit Items. To add, change, or remove one or more
trusted signers, change Enabled to true (if it’s currently false),
change Quantity as applicable, and specify all of the trusted
signers that you want to include in the updated distribution.
3.1. Services 315
Boto3 Documentation, Release 1.1.4
· Enabled (boolean) – Specifies whether you want to require
end users to use signed URLs to access the files specified by
PathPattern and TargetOriginId.
· Quantity (integer) – The number of trusted signers for this
cache behavior.
· Items (list) – Optional: A complex type that contains trusted
signers for this cache behavior. If Quantity is 0, you can omit
Items.
· (string) –
· Comment (string) – The comment originally specified when
this distribution was created.
· PriceClass (string) –
· Enabled (boolean) – Whether the distribution is enabled to
accept end user requests for content.
– NextToken (string) –
A token to resume pagination.
Waiters
The available waiters are:
• CloudFront.Waiter.DistributionDeployed
• CloudFront.Waiter.InvalidationCompleted
• CloudFront.Waiter.StreamingDistributionDeployed
class CloudFront.Waiter.DistributionDeployed
waiter = client.get_waiter('distribution_deployed')
wait(**kwargs)
Polls CloudFront.Client.get_distribution() every 60 seconds until a successful state is
reached. An error is returned after 25 failed checks.
Request Syntax
waiter.wait(
Id='string'
)
Parameters Id (string) – [REQUIRED] The distribution’s id.
Returns None
class CloudFront.Waiter.InvalidationCompleted
waiter = client.get_waiter('invalidation_completed')
wait(**kwargs)
Polls CloudFront.Client.get_invalidation() every 20 seconds until a successful state is
reached. An error is returned after 60 failed checks.
Request Syntax
316 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
waiter.wait(
DistributionId='string',
Id='string'
)
Parameters
• DistributionId (string) – [REQUIRED] The distribution’s id.
• Id (string) – [REQUIRED] The invalidation’s id.
Returns None
class CloudFront.Waiter.StreamingDistributionDeployed
waiter = client.get_waiter('streaming_distribution_deployed')
wait(**kwargs)
Polls CloudFront.Client.get_streaming_distribution() every 60 seconds until a suc-
cessful state is reached. An error is returned after 25 failed checks.
Request Syntax
waiter.wait(
Id='string'
)
Parameters Id (string) – [REQUIRED] The streaming distribution’s id.
Returns None
CloudHSM
Table of Contents
• CloudHSM
– Client
Client
class CloudHSM.Client
A low-level client representing Amazon CloudHSM:
import boto3
client = boto3.client('cloudhsm')
These are the available methods:
•can_paginate()
•create_hapg()
•create_hsm()
•create_luna_client()
•delete_hapg()
•delete_hsm()
•delete_luna_client()
3.1. Services 317
Boto3 Documentation, Release 1.1.4
•describe_hapg()
•describe_hsm()
•describe_luna_client()
•generate_presigned_url()
•get_config()
•get_paginator()
•get_waiter()
•list_available_zones()
•list_hapgs()
•list_hsms()
•list_luna_clients()
•modify_hapg()
•modify_hsm()
•modify_luna_client()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
create_hapg(**kwargs)
Creates a high-availability partition group. A high-availability partition group is a group of partitions that
spans multiple physical HSMs.
Request Syntax
response = client.create_hapg(
Label='string'
)
Parameters Label (string) – [REQUIRED]
The label of the new high-availability partition group.
Return type dict
Returns
Response Syntax
{
'HapgArn': 'string'
}
Response Structure
• (dict) –
Contains the output of the CreateHAPartitionGroup action.
– HapgArn (string) –
The ARN of the high-availability partition group.
create_hsm(**kwargs)
Creates an uninitialized HSM instance. Running this command provisions an HSM appliance and will
result in charges to your AWS account for the HSM.
Request Syntax
318 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.create_hsm(
SubnetId='string',
SshKey='string',
EniIp='string',
IamRoleArn='string',
ExternalId='string',
SubscriptionType='PRODUCTION',
ClientToken='string',
SyslogIp='string'
)
Parameters
• SubnetId (string) – [REQUIRED]
The identifier of the subnet in your VPC in which to place the HSM.
• SshKey (string) – [REQUIRED]
The SSH public key to install on the HSM.
• EniIp (string) – The IP address to assign to the HSM’s ENI.
• IamRoleArn (string) – [REQUIRED]
The ARN of an IAM role to enable the AWS CloudHSM service to allocate an
ENI on your behalf.
• ExternalId (string) – The external ID from IamRoleArn , if present.
• SubscriptionType (string) – [REQUIRED]
The subscription type.
• ClientToken (string) – A user-defined token to ensure idempotence. Subsequent
calls to this action with the same token will be ignored.
• SyslogIp (string) – The IP address for the syslog monitoring server.
Return type dict
Returns
Response Syntax
{
'HsmArn': 'string'
}
Response Structure
• (dict) –
Contains the output of the CreateHsm action.
– HsmArn (string) –
The ARN of the HSM.
create_luna_client(**kwargs)
Creates an HSM client.
Request Syntax
response = client.create_luna_client(
Label='string',
Certificate='string'
)
Parameters
• Label (string) – The label for the client.
3.1. Services 319
Boto3 Documentation, Release 1.1.4
• Certificate (string) – [REQUIRED]
The contents of a Base64-Encoded X.509 v3 certificate to be installed on the
HSMs used by this client.
Return type dict
Returns
Response Syntax
{
'ClientArn': 'string'
}
Response Structure
• (dict) –
Contains the output of the CreateLunaClient action.
– ClientArn (string) –
The ARN of the client.
delete_hapg(**kwargs)
Deletes a high-availability partition group.
Request Syntax
response = client.delete_hapg(
HapgArn='string'
)
Parameters HapgArn (string) – [REQUIRED]
The ARN of the high-availability partition group to delete.
Return type dict
Returns
Response Syntax
{
'Status': 'string'
}
Response Structure
• (dict) –
Contains the output of the DeleteHapg action.
– Status (string) –
The status of the action.
delete_hsm(**kwargs)
Deletes an HSM. Once complete, this operation cannot be undone and your key material cannot be recov-
ered.
Request Syntax
response = client.delete_hsm(
HsmArn='string'
)
320 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters HsmArn (string) – [REQUIRED]
The ARN of the HSM to delete.
Return type dict
Returns
Response Syntax
{
'Status': 'string'
}
Response Structure
• (dict) –
Contains the output of the DeleteHsm action.
– Status (string) –
The status of the action.
delete_luna_client(**kwargs)
Deletes a client.
Request Syntax
response = client.delete_luna_client(
ClientArn='string'
)
Parameters ClientArn (string) – [REQUIRED]
The ARN of the client to delete.
Return type dict
Returns
Response Syntax
{
'Status': 'string'
}
Response Structure
• (dict) –
– Status (string) –
The status of the action.
describe_hapg(**kwargs)
Retrieves information about a high-availability partition group.
Request Syntax
response = client.describe_hapg(
HapgArn='string'
)
Parameters HapgArn (string) – [REQUIRED]
The ARN of the high-availability partition group to describe.
Return type dict
3.1. Services 321
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'HapgArn': 'string',
'HapgSerial': 'string',
'HsmsLastActionFailed': [
'string',
],
'HsmsPendingDeletion': [
'string',
],
'HsmsPendingRegistration': [
'string',
],
'Label': 'string',
'LastModifiedTimestamp': 'string',
'PartitionSerialList': [
'string',
],
'State': 'READY'|'UPDATING'|'DEGRADED'
}
Response Structure
• (dict) –
Contains the output of the DescribeHapg action.
– HapgArn (string) –
The ARN of the high-availability partition group.
– HapgSerial (string) –
The serial number of the high-availability partition group.
– HsmsLastActionFailed (list) –
Contains a list of ARNs that identify the HSMs.
* (string) –
An ARN that identifies an HSM.
– HsmsPendingDeletion (list) –
Contains a list of ARNs that identify the HSMs.
* (string) –
An ARN that identifies an HSM.
– HsmsPendingRegistration (list) –
Contains a list of ARNs that identify the HSMs.
* (string) –
An ARN that identifies an HSM.
– Label (string) –
The label for the high-availability partition group.
– LastModifiedTimestamp (string) –
The date and time the high-availability partition group was last modified.
– PartitionSerialList (list) –
The list of partition serial numbers that belong to the high-availability par-
tition group.
322 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* (string) –
– State (string) –
The state of the high-availability partition group.
describe_hsm(**kwargs)
Retrieves information about an HSM. You can identify the HSM by its ARN or its serial number.
Request Syntax
response = client.describe_hsm(
HsmArn='string',
HsmSerialNumber='string'
)
Parameters
• HsmArn (string) – The ARN of the HSM. Either the HsmArn or the SerialNum-
ber parameter must be specified.
• HsmSerialNumber (string) – The serial number of the HSM. Either the HsmArn
or the HsmSerialNumber parameter must be specified.
Return type dict
Returns
Response Syntax
{
'HsmArn': 'string',
'Status': 'PENDING'|'RUNNING'|'UPDATING'|'SUSPENDED'|'TERMINATING'|'TERMINATED
'StatusDetails': 'string',
'AvailabilityZone': 'string',
'EniId': 'string',
'EniIp': 'string',
'SubscriptionType': 'PRODUCTION',
'SubscriptionStartDate': 'string',
'SubscriptionEndDate': 'string',
'VpcId': 'string',
'SubnetId': 'string',
'IamRoleArn': 'string',
'SerialNumber': 'string',
'VendorName': 'string',
'HsmType': 'string',
'SoftwareVersion': 'string',
'SshPublicKey': 'string',
'SshKeyLastUpdated': 'string',
'ServerCertUri': 'string',
'ServerCertLastUpdated': 'string',
'Partitions': [
'string',
]
}
Response Structure
• (dict) –
Contains the output of the DescribeHsm action.
– HsmArn (string) –
The ARN of the HSM.
3.1. Services 323
Boto3 Documentation, Release 1.1.4
– Status (string) –
The status of the HSM.
– StatusDetails (string) –
Contains additional information about the status of the HSM.
– AvailabilityZone (string) –
The Availability Zone that the HSM is in.
– EniId (string) –
The identifier of the elastic network interface (ENI) attached to the HSM.
– EniIp (string) –
The IP address assigned to the HSM’s ENI.
– SubscriptionType (string) –
The subscription type.
– SubscriptionStartDate (string) –
The subscription start date.
– SubscriptionEndDate (string) –
The subscription end date.
– VpcId (string) –
The identifier of the VPC that the HSM is in.
– SubnetId (string) –
The identifier of the subnet the HSM is in.
– IamRoleArn (string) –
The ARN of the IAM role assigned to the HSM.
– SerialNumber (string) –
The serial number of the HSM.
– VendorName (string) –
The name of the HSM vendor.
– HsmType (string) –
The HSM model type.
– SoftwareVersion (string) –
The HSM software version.
– SshPublicKey (string) –
The public SSH key.
– SshKeyLastUpdated (string) –
The date and time the SSH key was last updated.
– ServerCertUri (string) –
The URI of the certificate server.
– ServerCertLastUpdated (string) –
The date and time the server certificate was last updated.
– Partitions (list) –
The list of partitions on the HSM.
* (string) –
describe_luna_client(**kwargs)
Retrieves information about an HSM client.
324 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.describe_luna_client(
ClientArn='string',
CertificateFingerprint='string'
)
Parameters
• ClientArn (string) – The ARN of the client.
• CertificateFingerprint (string) – The certificate fingerprint.
Return type dict
Returns
Response Syntax
{
'ClientArn': 'string',
'Certificate': 'string',
'CertificateFingerprint': 'string',
'LastModifiedTimestamp': 'string',
'Label': 'string'
}
Response Structure
• (dict) –
– ClientArn (string) –
The ARN of the client.
– Certificate (string) –
The certificate installed on the HSMs used by this client.
– CertificateFingerprint (string) –
The certificate fingerprint.
– LastModifiedTimestamp (string) –
The date and time the client was last modified.
– Label (string) –
The label of the client.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_config(**kwargs)
Gets the configuration files necessary to connect to all high availability partition groups the client is
associated with.
Request Syntax
3.1. Services 325
Boto3 Documentation, Release 1.1.4
response = client.get_config(
ClientArn='string',
ClientVersion='5.1'|'5.3',
HapgList=[
'string',
]
)
Parameters
• ClientArn (string) – [REQUIRED]
The ARN of the client.
• ClientVersion (string) – [REQUIRED]
The client version.
• HapgList (list) – [REQUIRED]
A list of ARNs that identify the high-availability partition groups that are asso-
ciated with the client.
– (string) –
Return type dict
Returns
Response Syntax
{
'ConfigType': 'string',
'ConfigFile': 'string',
'ConfigCred': 'string'
}
Response Structure
• (dict) –
– ConfigType (string) –
The type of credentials.
– ConfigFile (string) –
The chrystoki.conf configuration file.
– ConfigCred (string) –
The certificate file containing the server.pem files of the HSMs.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
list_available_zones()
Lists the Availability Zones that have available AWS CloudHSM capacity.
326 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.list_available_zones()
Return type dict
Returns
Response Syntax
{
'AZList': [
'string',
]
}
Response Structure
• (dict) –
– AZList (list) –
The list of Availability Zones that have available AWS CloudHSM capac-
ity.
* (string) –
list_hapgs(**kwargs)
Lists the high-availability partition groups for the account.
This operation supports pagination with the use of the NextToken member. If more results are available,
the NextToken member of the response contains a token that you pass in the next call to ListHapgs to
retrieve the next set of items.
Request Syntax
response = client.list_hapgs(
NextToken='string'
)
Parameters NextToken (string) – The NextToken value from a previous call to ListHapgs .
Pass null if this is the first call.
Return type dict
Returns
Response Syntax
{
'HapgList': [
'string',
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– HapgList (list) –
The list of high-availability partition groups.
* (string) –
3.1. Services 327
Boto3 Documentation, Release 1.1.4
– NextToken (string) –
If not null, more results are available. Pass this value to ListHapgs to
retrieve the next set of items.
list_hsms(**kwargs)
Retrieves the identifiers of all of the HSMs provisioned for the current customer.
This operation supports pagination with the use of the NextToken member. If more results are available,
the NextToken member of the response contains a token that you pass in the next call to ListHsms to
retrieve the next set of items.
Request Syntax
response = client.list_hsms(
NextToken='string'
)
Parameters NextToken (string) – The NextToken value from a previous call to ListHsms .
Pass null if this is the first call.
Return type dict
Returns
Response Syntax
{
'HsmList': [
'string',
],
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the output of the ListHsms action.
– HsmList (list) –
The list of ARNs that identify the HSMs.
* (string) –
An ARN that identifies an HSM.
– NextToken (string) –
If not null, more results are available. Pass this value to ListHsms to re-
trieve the next set of items.
list_luna_clients(**kwargs)
Lists all of the clients.
This operation supports pagination with the use of the NextToken member. If more results are available,
the NextToken member of the response contains a token that you pass in the next call to ListLunaClients
to retrieve the next set of items.
Request Syntax
response = client.list_luna_clients(
NextToken='string'
)
328 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters NextToken (string) – The NextToken value from a previous call to ListLuna-
Clients . Pass null if this is the first call.
Return type dict
Returns
Response Syntax
{
'ClientList': [
'string',
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– ClientList (list) –
The list of clients.
* (string) –
– NextToken (string) –
If not null, more results are available. Pass this to ListLunaClients to re-
trieve the next set of items.
modify_hapg(**kwargs)
Modifies an existing high-availability partition group.
Request Syntax
response = client.modify_hapg(
HapgArn='string',
Label='string',
PartitionSerialList=[
'string',
]
)
Parameters
• HapgArn (string) – [REQUIRED]
The ARN of the high-availability partition group to modify.
• Label (string) – The new label for the high-availability partition group.
• PartitionSerialList (list) – The list of partition serial numbers to make members
of the high-availability partition group.
– (string) –
Return type dict
Returns
Response Syntax
{
'HapgArn': 'string'
}
Response Structure
• (dict) –
3.1. Services 329
Boto3 Documentation, Release 1.1.4
– HapgArn (string) –
The ARN of the high-availability partition group.
modify_hsm(**kwargs)
Modifies an HSM.
Request Syntax
response = client.modify_hsm(
HsmArn='string',
SubnetId='string',
EniIp='string',
IamRoleArn='string',
ExternalId='string',
SyslogIp='string'
)
Parameters
• HsmArn (string) – [REQUIRED]
The ARN of the HSM to modify.
• SubnetId (string) – The new identifier of the subnet that the HSM is in.
• EniIp (string) – The new IP address for the elastic network interface attached to
the HSM.
• IamRoleArn (string) – The new IAM role ARN.
• ExternalId (string) – The new external ID.
• SyslogIp (string) – The new IP address for the syslog monitoring server.
Return type dict
Returns
Response Syntax
{
'HsmArn': 'string'
}
Response Structure
• (dict) –
Contains the output of the ModifyHsm action.
– HsmArn (string) –
The ARN of the HSM.
modify_luna_client(**kwargs)
Modifies the certificate used by the client.
This action can potentially start a workflow to install the new certificate on the client’s HSMs.
Request Syntax
response = client.modify_luna_client(
ClientArn='string',
Certificate='string'
)
Parameters
• ClientArn (string) – [REQUIRED]
The ARN of the client.
330 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• Certificate (string) – [REQUIRED]
The new certificate for the client.
Return type dict
Returns
Response Syntax
{
'ClientArn': 'string'
}
Response Structure
• (dict) –
– ClientArn (string) –
The ARN of the client.
CloudSearch
Table of Contents
• CloudSearch
– Client
Client
class CloudSearch.Client
A low-level client representing Amazon CloudSearch:
import boto3
client = boto3.client('cloudsearch')
These are the available methods:
•build_suggesters()
•can_paginate()
•create_domain()
•define_analysis_scheme()
•define_expression()
•define_index_field()
•define_suggester()
•delete_analysis_scheme()
•delete_domain()
•delete_expression()
•delete_index_field()
•delete_suggester()
•describe_analysis_schemes()
•describe_availability_options()
•describe_domains()
•describe_expressions()
•describe_index_fields()
•describe_scaling_parameters()
3.1. Services 331
Boto3 Documentation, Release 1.1.4
•describe_service_access_policies()
•describe_suggesters()
•generate_presigned_url()
•get_paginator()
•get_waiter()
•index_documents()
•list_domain_names()
•update_availability_options()
•update_scaling_parameters()
•update_service_access_policies()
build_suggesters(**kwargs)
Indexes the search suggestions. For more information, see Configuring Suggesters in the Amazon Cloud-
Search Developer Guide .
Request Syntax
response = client.build_suggesters(
DomainName='string'
)
Parameters DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across the
domains owned by an account within an AWS region. Domain names start with a
letter or number and can contain the following characters: a-z (lowercase), 0-9, and -
(hyphen).
Return type dict
Returns
Response Syntax
{
'FieldNames': [
'string',
]
}
Response Structure
• (dict) –
The result of a BuildSuggester request. Contains a list of the fields used for
suggestions.
– FieldNames (list) –
A list of field names.
* (string) –
A string that represents the name of an index field. CloudSearch
supports regular index fields as well as dynamic fields. A dynamic
field’s name defines a pattern that begins or ends with a wildcard.
Any document fields that don’t map to a regular index field but do
match a dynamic field’s pattern are configured with the dynamic
field’s indexing options.
Regular field names begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore). Dynamic field
names must begin or end with a wildcard (*). The wildcard can also
332 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
be the only character in a dynamic field name. Multiple wildcards,
and wildcards embedded within a string are not supported.
The name score is reserved and cannot be used as a field name.
To reference a document’s ID, you can use the name _id .
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
create_domain(**kwargs)
Creates a new search domain. For more information, see Creating a Search Domain in the Amazon
CloudSearch Developer Guide .
Request Syntax
response = client.create_domain(
DomainName='string'
)
Parameters DomainName (string) – [REQUIRED]
A name for the domain you are creating. Allowed characters are a-z (lower-case let-
ters), 0-9, and hyphen (-). Domain names must start with a letter or number and be at
least 3 and no more than 28 characters long.
Return type dict
Returns
Response Syntax
{
'DomainStatus': {
'DomainId': 'string',
'DomainName': 'string',
'ARN': 'string',
'Created': True|False,
'Deleted': True|False,
'DocService': {
'Endpoint': 'string'
},
'SearchService': {
'Endpoint': 'string'
},
'RequiresIndexDocuments': True|False,
'Processing': True|False,
'SearchInstanceType': 'string',
'SearchPartitionCount': 123,
'SearchInstanceCount': 123,
'Limits': {
'MaximumReplicationCount': 123,
'MaximumPartitionCount': 123
}
}
}
3.1. Services 333
Boto3 Documentation, Release 1.1.4
Response Structure
• (dict) –
The result of a CreateDomainRequest . Contains the status of a newly
created domain.
– DomainStatus (dict) –
The current status of the search domain.
* DomainId (string) –
An internally generated unique identifier for a domain.
* DomainName (string) –
A string that represents the name of a domain. Domain names are
unique across the domains owned by an account within an AWS
region. Domain names start with a letter or number and can contain
the following characters: a-z (lowercase), 0-9, and - (hyphen).
* ARN (string) –
The Amazon Resource Name (ARN) of the search domain. See
Identifiers for IAM Entities in Using AWS Identity and Access Man-
agement for more information.
* Created (boolean) –
True if the search domain is created. It can take several minutes to
initialize a domain when CreateDomain is called. Newly created
search domains are returned from DescribeDomains with a false
value for Created until domain creation is complete.
* Deleted (boolean) –
True if the search domain has been deleted. The system must clean
up resources dedicated to the search domain when DeleteDomain
is called. Newly deleted search domains are returned from De-
scribeDomains with a true value for IsDeleted for several minutes
until resource cleanup is complete.
* DocService (dict) –
The service endpoint for updating documents in a search domain.
· Endpoint (string) –
The endpoint to which service re-
quests can be submitted. For example,
search-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.cl
or doc-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.clo
.
* SearchService (dict) –
The service endpoint for requesting search results from a search do-
main.
· Endpoint (string) –
The endpoint to which service re-
quests can be submitted. For example,
search-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.cl
or doc-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.clo
.
* RequiresIndexDocuments (boolean) –
True if IndexDocuments needs to be called to activate the current
domain configuration.
334 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Processing (boolean) –
True if processing is being done to activate the current domain con-
figuration.
* SearchInstanceType (string) –
The instance type that is being used to process search requests.
* SearchPartitionCount (integer) –
The number of partitions across which the search index is spread.
* SearchInstanceCount (integer) –
The number of search instances that are available to process search
requests.
* Limits (dict) –
· MaximumReplicationCount (integer) –
· MaximumPartitionCount (integer) –
define_analysis_scheme(**kwargs)
Configures an analysis scheme that can be applied to a text or text-array field to define language-
specific text processing options. For more information, see Configuring Analysis Schemes in the Amazon
CloudSearch Developer Guide .
Request Syntax
response = client.define_analysis_scheme(
DomainName='string',
AnalysisScheme={
'AnalysisSchemeName': 'string',
'AnalysisSchemeLanguage': 'ar'|'bg'|'ca'|'cs'|'da'|'de'|'el'|'en'|'es'|'eu'|'fa'|'fi
'AnalysisOptions': {
'Synonyms': 'string',
'Stopwords': 'string',
'StemmingDictionary': 'string',
'JapaneseTokenizationDictionary': 'string',
'AlgorithmicStemming': 'none'|'minimal'|'light'|'full'
}
}
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• AnalysisScheme (dict) – [REQUIRED]
Configuration information for an analysis scheme. Each analysis scheme
has a unique name and specifies the language of the text to be
processed. The following options can be configured for an analy-
sis scheme: Synonyms , Stopwords , StemmingDictionary ,
JapaneseTokenizationDictionary and AlgorithmicStemming .
– AnalysisSchemeName (string) – [REQUIRED]
Names must begin with a letter and can contain the following characters:
a-z (lowercase), 0-9, and _ (underscore).
– AnalysisSchemeLanguage (string) – [REQUIRED]
3.1. Services 335
Boto3 Documentation, Release 1.1.4
An IETF RFC 4646 language code or mul for multiple languages.
– AnalysisOptions (dict) –
Synonyms, stopwords, and stemming options for an analysis scheme. In-
cludes tokenization dictionary for Japanese.
* Synonyms (string) –
A JSON object that defines synonym groups and aliases. A syn-
onym group is an array of arrays, where each sub-array is a group
of terms where each term in the group is considered a synonym of
every other term in the group. The aliases value is an object that
contains a collection of string:value pairs where the string specifies
a term and the array of values specifies each of the aliases for that
term. An alias is considered a synonym of the specified term, but
the term is not considered a synonym of the alias. For more infor-
mation about specifying synonyms, see Synonyms in the Amazon
CloudSearch Developer Guide .
* Stopwords (string) –
A JSON array of terms to ignore during indexing and searching. For
example, ["a", "an", "the", "of"] . The stopwords dic-
tionary must explicitly list each word you want to ignore. Wildcards
and regular expressions are not supported.
* StemmingDictionary (string) –
A JSON object that contains a collection of string:value
pairs that each map a term to its stem. For example,
{"term1": "stem1", "term2": "stem2",
"term3": "stem3"} . The stemming dictionary is ap-
plied in addition to any algorithmic stemming. This enables you to
override the results of the algorithmic stemming to correct specific
cases of overstemming or understemming. The maximum size of a
stemming dictionary is 500 KB.
* JapaneseTokenizationDictionary (string) –
A JSON array that contains a collection of terms, tokens, readings
and part of speech for Japanese Tokenizaiton. The Japanese tok-
enization dictionary enables you to override the default tokenization
for selected terms. This is only valid for Japanese language fields.
* AlgorithmicStemming (string) –
The level of algorithmic stemming to perform: none , minimal
, light , or full . The available levels vary depending on the
language. For more information, see Language Specific Text Pro-
cessing Settings in the Amazon CloudSearch Developer Guide
Return type dict
Returns
Response Syntax
{
'AnalysisScheme': {
'Options': {
'AnalysisSchemeName': 'string',
'AnalysisSchemeLanguage': 'ar'|'bg'|'ca'|'cs'|'da'|'de'|'el'|'en'|'es'
'AnalysisOptions': {
'Synonyms': 'string',
'Stopwords': 'string',
336 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'StemmingDictionary': 'string',
'JapaneseTokenizationDictionary': 'string',
'AlgorithmicStemming': 'none'|'minimal'|'light'|'full'
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a ‘‘ DefineAnalysisScheme‘‘ request. Contains the status of the
newly-configured analysis scheme.
– AnalysisScheme (dict) –
The status and configuration of an AnalysisScheme .
* Options (dict) –
Configuration information for an analysis scheme. Each
analysis scheme has a unique name and specifies the
language of the text to be processed. The follow-
ing options can be configured for an analysis scheme:
Synonyms , Stopwords , StemmingDictionary
, JapaneseTokenizationDictionary and
AlgorithmicStemming .
· AnalysisSchemeName (string) –
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· AnalysisSchemeLanguage (string) –
An IETF RFC 4646 language code or mul for multiple lan-
guages.
· AnalysisOptions (dict) –
Synonyms, stopwords, and stemming options for an analysis
scheme. Includes tokenization dictionary for Japanese.
· Synonyms (string) –
A JSON object that defines synonym groups and aliases. A
synonym group is an array of arrays, where each sub-array is
a group of terms where each term in the group is considered a
synonym of every other term in the group. The aliases value is
an object that contains a collection of string:value pairs where
the string specifies a term and the array of values specifies
each of the aliases for that term. An alias is considered a syn-
onym of the specified term, but the term is not considered a
synonym of the alias. For more information about specifying
synonyms, see Synonyms in the Amazon CloudSearch Devel-
oper Guide .
· Stopwords (string) –
3.1. Services 337
Boto3 Documentation, Release 1.1.4
A JSON array of terms to ignore during indexing and search-
ing. For example, ["a", "an", "the", "of"] . The
stopwords dictionary must explicitly list each word you want
to ignore. Wildcards and regular expressions are not sup-
ported.
· StemmingDictionary (string) –
A JSON object that contains a collection of string:value
pairs that each map a term to its stem. For exam-
ple, {"term1": "stem1", "term2": "stem2",
"term3": "stem3"} . The stemming dictionary is ap-
plied in addition to any algorithmic stemming. This enables
you to override the results of the algorithmic stemming to cor-
rect specific cases of overstemming or understemming. The
maximum size of a stemming dictionary is 500 KB.
· JapaneseTokenizationDictionary (string) –
A JSON array that contains a collection of terms, tokens,
readings and part of speech for Japanese Tokenizaiton. The
Japanese tokenization dictionary enables you to override the
default tokenization for selected terms. This is only valid for
Japanese language fields.
· AlgorithmicStemming (string) –
The level of algorithmic stemming to perform: none ,
minimal , light , or full . The available levels vary
depending on the language. For more information, see Lan-
guage Specific Text Processing Settings in the Amazon Cloud-
Search Developer Guide
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
338 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
complete.
define_expression(**kwargs)
Configures an ‘‘ Expression‘‘ for the search domain. Used to create new expressions and modify existing
ones. If the expression exists, the new configuration replaces the old one. For more information, see
Configuring Expressions in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.define_expression(
DomainName='string',
Expression={
'ExpressionName': 'string',
'ExpressionValue': 'string'
}
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• Expression (dict) – [REQUIRED]
A named expression that can be evaluated at search time. Can be used to sort the
search results, define other expressions, or return computed information in the
search results.
– ExpressionName (string) – [REQUIRED]
Names must begin with a letter and can contain the following characters:
a-z (lowercase), 0-9, and _ (underscore).
– ExpressionValue (string) – [REQUIRED]
The expression to evaluate for sorting while processing a search request.
The Expression syntax is based on JavaScript expressions. For more
information, see Configuring Expressions in the Amazon CloudSearch De-
veloper Guide .
Return type dict
Returns
Response Syntax
{
'Expression': {
'Options': {
'ExpressionName': 'string',
'ExpressionValue': 'string'
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
3.1. Services 339
Boto3 Documentation, Release 1.1.4
Response Structure
• (dict) –
The result of a DefineExpression request. Contains the status of the newly-
configured expression.
– Expression (dict) –
The value of an Expression and its current status.
* Options (dict) –
The expression that is evaluated for sorting while processing a
search request.
· ExpressionName (string) –
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· ExpressionValue (string) –
The expression to evaluate for sorting while processing a
search request. The Expression syntax is based on
JavaScript expressions. For more information, see Configur-
ing Expressions in the Amazon CloudSearch Developer Guide
.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
define_index_field(**kwargs)
Configures an ‘‘ IndexField‘‘ for the search domain. Used to create new fields and modify existing ones.
You must specify the name of the domain you are configuring and an index field configuration. The index
field configuration specifies a unique name, the index field type, and the options you want to configure
for the field. The options you can specify depend on the ‘‘ IndexFieldType‘‘ . If the field exists, the new
340 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
configuration replaces the old one. For more information, see Configuring Index Fields in the Amazon
CloudSearch Developer Guide .
Request Syntax
response = client.define_index_field(
DomainName='string',
IndexField={
'IndexFieldName': 'string',
'IndexFieldType': 'int'|'double'|'literal'|'text'|'date'|'latlon'|'int-array'|'doubl
'IntOptions': {
'DefaultValue': 123,
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'DoubleOptions': {
'DefaultValue': 123.0,
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'LiteralOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'TextOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'ReturnEnabled': True|False,
'SortEnabled': True|False,
'HighlightEnabled': True|False,
'AnalysisScheme': 'string'
},
'DateOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'LatLonOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'IntArrayOptions': {
3.1. Services 341
Boto3 Documentation, Release 1.1.4
'DefaultValue': 123,
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'DoubleArrayOptions': {
'DefaultValue': 123.0,
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'LiteralArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'TextArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'ReturnEnabled': True|False,
'HighlightEnabled': True|False,
'AnalysisScheme': 'string'
},
'DateArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
}
}
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• IndexField (dict) – [REQUIRED]
The index field and field options you want to configure.
– IndexFieldName (string) – [REQUIRED]
A string that represents the name of an index field. CloudSearch supports
regular index fields as well as dynamic fields. A dynamic field’s name
defines a pattern that begins or ends with a wildcard. Any document fields
that don’t map to a regular index field but do match a dynamic field’s
pattern are configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the following char-
acters: a-z (lowercase), 0-9, and _ (underscore). Dynamic field names
must begin or end with a wildcard (*). The wildcard can also be the only
character in a dynamic field name. Multiple wildcards, and wildcards em-
342 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
bedded within a string are not supported.
The name score is reserved and cannot be used as a field name. To
reference a document’s ID, you can use the name _id .
– IndexFieldType (string) – [REQUIRED]
The type of field. The valid options for a field depend on the field type. For
more information about the supported field types, see Configuring Index
Fields in the Amazon CloudSearch Developer Guide .
– IntOptions (dict) –
Options for a 64-bit signed integer field. Present if IndexFieldType
specifies the field is of type int . All options are enabled by default.
* DefaultValue (integer) – A value to use for the field if the field isn’t
specified for a document. This can be important if you are using the
field in an expression and that field is not present in every document.
* SourceField (string) –
The name of the source field to map to the field.
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
* SortEnabled (boolean) –
Whether the field can be used to sort the search results.
– DoubleOptions (dict) –
Options for a double-precision 64-bit floating point field. Present if
IndexFieldType specifies the field is of type double . All options
are enabled by default.
* DefaultValue (float) –
A value to use for the field if the field isn’t specified for a document.
This can be important if you are using the field in an expression and
that field is not present in every document.
* SourceField (string) –
The name of the source field to map to the field.
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
* SortEnabled (boolean) –
Whether the field can be used to sort the search results.
– LiteralOptions (dict) –
Options for literal field. Present if IndexFieldType specifies the field
is of type literal . All options are enabled by default.
3.1. Services 343
Boto3 Documentation, Release 1.1.4
* DefaultValue (string) – A value to use for the field if the field isn’t
specified for a document.
* SourceField (string) –
A string that represents the name of an index field. CloudSearch
supports regular index fields as well as dynamic fields. A dynamic
field’s name defines a pattern that begins or ends with a wildcard.
Any document fields that don’t map to a regular index field but do
match a dynamic field’s pattern are configured with the dynamic
field’s indexing options.
Regular field names begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore). Dynamic field
names must begin or end with a wildcard (*). The wildcard can also
be the only character in a dynamic field name. Multiple wildcards,
and wildcards embedded within a string are not supported.
The name score is reserved and cannot be used as a field name.
To reference a document’s ID, you can use the name _id .
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
* SortEnabled (boolean) –
Whether the field can be used to sort the search results.
– TextOptions (dict) –
Options for text field. Present if IndexFieldType specifies the field is
of type text . A text field is always searchable. All options are enabled
by default.
* DefaultValue (string) – A value to use for the field if the field isn’t
specified for a document.
* SourceField (string) –
A string that represents the name of an index field. CloudSearch
supports regular index fields as well as dynamic fields. A dynamic
field’s name defines a pattern that begins or ends with a wildcard.
Any document fields that don’t map to a regular index field but do
match a dynamic field’s pattern are configured with the dynamic
field’s indexing options.
Regular field names begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore). Dynamic field
names must begin or end with a wildcard (*). The wildcard can also
be the only character in a dynamic field name. Multiple wildcards,
and wildcards embedded within a string are not supported.
The name score is reserved and cannot be used as a field name.
To reference a document’s ID, you can use the name _id .
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
344 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* SortEnabled (boolean) –
Whether the field can be used to sort the search results.
* HighlightEnabled (boolean) –
Whether highlights can be returned for the field.
* AnalysisScheme (string) –
The name of an analysis scheme for a text field.
– DateOptions (dict) –
Options for a date field. Dates and times are specified in UTC (Co-
ordinated Universal Time) according to IETF RFC3339: yyyy-mm-
ddT00:00:00Z. Present if IndexFieldType specifies the field is of type
date . All options are enabled by default.
* DefaultValue (string) – A value to use for the field if the field isn’t
specified for a document.
* SourceField (string) –
A string that represents the name of an index field. CloudSearch
supports regular index fields as well as dynamic fields. A dynamic
field’s name defines a pattern that begins or ends with a wildcard.
Any document fields that don’t map to a regular index field but do
match a dynamic field’s pattern are configured with the dynamic
field’s indexing options.
Regular field names begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore). Dynamic field
names must begin or end with a wildcard (*). The wildcard can also
be the only character in a dynamic field name. Multiple wildcards,
and wildcards embedded within a string are not supported.
The name score is reserved and cannot be used as a field name.
To reference a document’s ID, you can use the name _id .
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
* SortEnabled (boolean) –
Whether the field can be used to sort the search results.
– LatLonOptions (dict) –
Options for a latlon field. A latlon field contains a location stored as a
latitude and longitude value pair. Present if IndexFieldType specifies
the field is of type latlon . All options are enabled by default.
* DefaultValue (string) – A value to use for the field if the field isn’t
specified for a document.
* SourceField (string) –
A string that represents the name of an index field. CloudSearch
supports regular index fields as well as dynamic fields. A dynamic
field’s name defines a pattern that begins or ends with a wildcard.
Any document fields that don’t map to a regular index field but do
3.1. Services 345
Boto3 Documentation, Release 1.1.4
match a dynamic field’s pattern are configured with the dynamic
field’s indexing options.
Regular field names begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore). Dynamic field
names must begin or end with a wildcard (*). The wildcard can also
be the only character in a dynamic field name. Multiple wildcards,
and wildcards embedded within a string are not supported.
The name score is reserved and cannot be used as a field name.
To reference a document’s ID, you can use the name _id .
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
* SortEnabled (boolean) –
Whether the field can be used to sort the search results.
– IntArrayOptions (dict) –
Options for a field that contains an array of 64-bit signed integers. Present
if IndexFieldType specifies the field is of type int-array . All
options are enabled by default.
* DefaultValue (integer) – A value to use for the field if the field isn’t
specified for a document.
* SourceFields (string) –
A list of source fields to map to the field.
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
– DoubleArrayOptions (dict) –
Options for a field that contains an array of double-precision 64-bit floating
point values. Present if IndexFieldType specifies the field is of type
double-array . All options are enabled by default.
* DefaultValue (float) – A value to use for the field if the field isn’t
specified for a document.
* SourceFields (string) –
A list of source fields to map to the field.
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
346 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
– LiteralArrayOptions (dict) –
Options for a field that contains an array of literal strings. Present if
IndexFieldType specifies the field is of type literal-array . All
options are enabled by default.
* DefaultValue (string) – A value to use for the field if the field isn’t
specified for a document.
* SourceFields (string) –
A list of source fields to map to the field.
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
– TextArrayOptions (dict) –
Options for a field that contains an array of text strings. Present if
IndexFieldType specifies the field is of type text-array . A
text-array field is always searchable. All options are enabled by de-
fault.
* DefaultValue (string) – A value to use for the field if the field isn’t
specified for a document.
* SourceFields (string) –
A list of source fields to map to the field.
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
* HighlightEnabled (boolean) –
Whether highlights can be returned for the field.
* AnalysisScheme (string) –
The name of an analysis scheme for a text-array field.
– DateArrayOptions (dict) –
Options for a field that contains an array of dates. Present if
IndexFieldType specifies the field is of type date-array . All
options are enabled by default.
* DefaultValue (string) – A value to use for the field if the field isn’t
specified for a document.
* SourceFields (string) –
A list of source fields to map to the field.
* FacetEnabled (boolean) –
Whether facet information can be returned for the field.
* SearchEnabled (boolean) –
Whether the contents of the field are searchable.
3.1. Services 347
Boto3 Documentation, Release 1.1.4
* ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search re-
sults.
Return type dict
Returns
Response Syntax
{
'IndexField': {
'Options': {
'IndexFieldName': 'string',
'IndexFieldType': 'int'|'double'|'literal'|'text'|'date'|'latlon'|'int
'IntOptions': {
'DefaultValue': 123,
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'DoubleOptions': {
'DefaultValue': 123.0,
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'LiteralOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'TextOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'ReturnEnabled': True|False,
'SortEnabled': True|False,
'HighlightEnabled': True|False,
'AnalysisScheme': 'string'
},
'DateOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'LatLonOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
348 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'IntArrayOptions': {
'DefaultValue': 123,
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'DoubleArrayOptions': {
'DefaultValue': 123.0,
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'LiteralArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'TextArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'ReturnEnabled': True|False,
'HighlightEnabled': True|False,
'AnalysisScheme': 'string'
},
'DateArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a ‘‘ DefineIndexField‘‘ request. Contains the status of the newly-
configured index field.
– IndexField (dict) –
The value of an IndexField and its current status.
* Options (dict) –
3.1. Services 349
Boto3 Documentation, Release 1.1.4
Configuration information for a field in the index, including its
name, type, and options. The supported options depend on the ‘‘
IndexFieldType‘‘ .
· IndexFieldName (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· IndexFieldType (string) –
The type of field. The valid options for a field depend on the
field type. For more information about the supported field
types, see Configuring Index Fields in the Amazon Cloud-
Search Developer Guide .
· IntOptions (dict) –
Options for a 64-bit signed integer field. Present if
IndexFieldType specifies the field is of type int . All
options are enabled by default.
· DefaultValue (integer) – A value to use for the field if the
field isn’t specified for a document. This can be important if
you are using the field in an expression and that field is not
present in every document.
· SourceField (string) –
The name of the source field to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· DoubleOptions (dict) –
Options for a double-precision 64-bit floating point field.
Present if IndexFieldType specifies the field is of type
double . All options are enabled by default.
· DefaultValue (float) –
350 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A value to use for the field if the field isn’t specified for a
document. This can be important if you are using the field in
an expression and that field is not present in every document.
· SourceField (string) –
The name of the source field to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· LiteralOptions (dict) –
Options for literal field. Present if IndexFieldType spec-
ifies the field is of type literal . All options are enabled
by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· TextOptions (dict) –
3.1. Services 351
Boto3 Documentation, Release 1.1.4
Options for text field. Present if IndexFieldType speci-
fies the field is of type text . A text field is always search-
able. All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· HighlightEnabled (boolean) –
Whether highlights can be returned for the field.
· AnalysisScheme (string) –
The name of an analysis scheme for a text field.
· DateOptions (dict) –
Options for a date field. Dates and times are specified in UTC
(Coordinated Universal Time) according to IETF RFC3339:
yyyy-mm-ddT00:00:00Z. Present if IndexFieldType
specifies the field is of type date . All options are enabled
by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
352 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· LatLonOptions (dict) –
Options for a latlon field. A latlon field contains a loca-
tion stored as a latitude and longitude value pair. Present if
IndexFieldType specifies the field is of type latlon .
All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· IntArrayOptions (dict) –
3.1. Services 353
Boto3 Documentation, Release 1.1.4
Options for a field that contains an array of 64-bit signed in-
tegers. Present if IndexFieldType specifies the field is of
type int-array . All options are enabled by default.
· DefaultValue (integer) – A value to use for the field if the
field isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· DoubleArrayOptions (dict) –
Options for a field that contains an array of double-precision
64-bit floating point values. Present if IndexFieldType
specifies the field is of type double-array . All options
are enabled by default.
· DefaultValue (float) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· LiteralArrayOptions (dict) –
Options for a field that contains an array of literal strings.
Present if IndexFieldType specifies the field is of type
literal-array . All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· TextArrayOptions (dict) –
354 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Options for a field that contains an array of text strings.
Present if IndexFieldType specifies the field is of type
text-array . A text-array field is always searchable.
All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· HighlightEnabled (boolean) –
Whether highlights can be returned for the field.
· AnalysisScheme (string) –
The name of an analysis scheme for a text-array field.
· DateArrayOptions (dict) –
Options for a field that contains an array of dates.
Present if IndexFieldType specifies the field is of type
date-array . All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
3.1. Services 355
Boto3 Documentation, Release 1.1.4
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
define_suggester(**kwargs)
Configures a suggester for a domain. A suggester enables you to display possible matches before users
finish typing their queries. When you configure a suggester, you must specify the name of the text field
you want to search for possible matches and a unique name for the suggester. For more information, see
Getting Search Suggestions in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.define_suggester(
DomainName='string',
Suggester={
'SuggesterName': 'string',
'DocumentSuggesterOptions': {
'SourceField': 'string',
'FuzzyMatching': 'none'|'low'|'high',
'SortExpression': 'string'
}
}
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• Suggester (dict) – [REQUIRED]
Configuration information for a search suggester. Each suggester has a unique
name and specifies the text field you want to use for suggestions. The
following options can be configured for a suggester: FuzzyMatching ,
SortExpression .
– SuggesterName (string) – [REQUIRED]
Names must begin with a letter and can contain the following characters:
a-z (lowercase), 0-9, and _ (underscore).
– DocumentSuggesterOptions (dict) – [REQUIRED]
Options for a search suggester.
* SourceField (string) – [REQUIRED]
The name of the index field you want to use for suggestions.
* FuzzyMatching (string) –
The level of fuzziness allowed when suggesting matches for a string:
none , low , or high . With none, the specified string is treated as
an exact prefix. With low, suggestions must differ from the specified
string by no more than one character. With high, suggestions can
differ by up to two characters. The default is none.
356 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* SortExpression (string) –
An expression that computes a score for each suggestion to control
how they are sorted. The scores are rounded to the nearest integer,
with a floor of 0 and a ceiling of 2^31-1. A document’s relevance
score is not computed for suggestions, so sort expressions cannot
reference the _score value. To sort suggestions using a numeric
field or existing expression, simply specify the name of the field
or expression. If no expression is configured for the suggester, the
suggestions are sorted with the closest matches listed first.
Return type dict
Returns
Response Syntax
{
'Suggester': {
'Options': {
'SuggesterName': 'string',
'DocumentSuggesterOptions': {
'SourceField': 'string',
'FuzzyMatching': 'none'|'low'|'high',
'SortExpression': 'string'
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a DefineSuggester request. Contains the status of the newly-
configured suggester.
– Suggester (dict) –
The value of a Suggester and its current status.
* Options (dict) –
Configuration information for a search suggester. Each suggester
has a unique name and specifies the text field you want to use for
suggestions. The following options can be configured for a sug-
gester: FuzzyMatching , SortExpression .
· SuggesterName (string) –
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· DocumentSuggesterOptions (dict) –
Options for a search suggester.
· SourceField (string) –
The name of the index field you want to use for suggestions.
3.1. Services 357
Boto3 Documentation, Release 1.1.4
· FuzzyMatching (string) –
The level of fuzziness allowed when suggesting matches for
a string: none , low , or high . With none, the specified
string is treated as an exact prefix. With low, suggestions must
differ from the specified string by no more than one character.
With high, suggestions can differ by up to two characters. The
default is none.
· SortExpression (string) –
An expression that computes a score for each suggestion to
control how they are sorted. The scores are rounded to the
nearest integer, with a floor of 0 and a ceiling of 2^31-1. A
document’s relevance score is not computed for suggestions,
so sort expressions cannot reference the _score value. To
sort suggestions using a numeric field or existing expression,
simply specify the name of the field or expression. If no ex-
pression is configured for the suggester, the suggestions are
sorted with the closest matches listed first.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
delete_analysis_scheme(**kwargs)
Deletes an analysis scheme. For more information, see Configuring Analysis Schemes in the Amazon
CloudSearch Developer Guide .
Request Syntax
response = client.delete_analysis_scheme(
DomainName='string',
358 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
AnalysisSchemeName='string'
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• AnalysisSchemeName (string) – [REQUIRED]
The name of the analysis scheme you want to delete.
Return type dict
Returns
Response Syntax
{
'AnalysisScheme': {
'Options': {
'AnalysisSchemeName': 'string',
'AnalysisSchemeLanguage': 'ar'|'bg'|'ca'|'cs'|'da'|'de'|'el'|'en'|'es'
'AnalysisOptions': {
'Synonyms': 'string',
'Stopwords': 'string',
'StemmingDictionary': 'string',
'JapaneseTokenizationDictionary': 'string',
'AlgorithmicStemming': 'none'|'minimal'|'light'|'full'
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a DeleteAnalysisScheme request. Contains the status of the
deleted analysis scheme.
– AnalysisScheme (dict) –
The status of the analysis scheme being deleted.
* Options (dict) –
Configuration information for an analysis scheme. Each
analysis scheme has a unique name and specifies the
language of the text to be processed. The follow-
ing options can be configured for an analysis scheme:
Synonyms , Stopwords , StemmingDictionary
, JapaneseTokenizationDictionary and
AlgorithmicStemming .
3.1. Services 359
Boto3 Documentation, Release 1.1.4
· AnalysisSchemeName (string) –
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· AnalysisSchemeLanguage (string) –
An IETF RFC 4646 language code or mul for multiple lan-
guages.
· AnalysisOptions (dict) –
Synonyms, stopwords, and stemming options for an analysis
scheme. Includes tokenization dictionary for Japanese.
· Synonyms (string) –
A JSON object that defines synonym groups and aliases. A
synonym group is an array of arrays, where each sub-array is
a group of terms where each term in the group is considered a
synonym of every other term in the group. The aliases value is
an object that contains a collection of string:value pairs where
the string specifies a term and the array of values specifies
each of the aliases for that term. An alias is considered a syn-
onym of the specified term, but the term is not considered a
synonym of the alias. For more information about specifying
synonyms, see Synonyms in the Amazon CloudSearch Devel-
oper Guide .
· Stopwords (string) –
A JSON array of terms to ignore during indexing and search-
ing. For example, ["a", "an", "the", "of"] . The
stopwords dictionary must explicitly list each word you want
to ignore. Wildcards and regular expressions are not sup-
ported.
· StemmingDictionary (string) –
A JSON object that contains a collection of string:value
pairs that each map a term to its stem. For exam-
ple, {"term1": "stem1", "term2": "stem2",
"term3": "stem3"} . The stemming dictionary is ap-
plied in addition to any algorithmic stemming. This enables
you to override the results of the algorithmic stemming to cor-
rect specific cases of overstemming or understemming. The
maximum size of a stemming dictionary is 500 KB.
· JapaneseTokenizationDictionary (string) –
A JSON array that contains a collection of terms, tokens,
readings and part of speech for Japanese Tokenizaiton. The
Japanese tokenization dictionary enables you to override the
default tokenization for selected terms. This is only valid for
Japanese language fields.
· AlgorithmicStemming (string) –
The level of algorithmic stemming to perform: none ,
minimal , light , or full . The available levels vary
depending on the language. For more information, see Lan-
guage Specific Text Processing Settings in the Amazon Cloud-
Search Developer Guide
* Status (dict) –
360 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
delete_domain(**kwargs)
Permanently deletes a search domain and all of its data. Once a domain has been deleted, it cannot be
recovered. For more information, see Deleting a Search Domain in the Amazon CloudSearch Developer
Guide .
Request Syntax
response = client.delete_domain(
DomainName='string'
)
Parameters DomainName (string) – [REQUIRED]
The name of the domain you want to permanently delete.
Return type dict
Returns
Response Syntax
{
'DomainStatus': {
'DomainId': 'string',
'DomainName': 'string',
'ARN': 'string',
'Created': True|False,
'Deleted': True|False,
'DocService': {
'Endpoint': 'string'
},
'SearchService': {
3.1. Services 361
Boto3 Documentation, Release 1.1.4
'Endpoint': 'string'
},
'RequiresIndexDocuments': True|False,
'Processing': True|False,
'SearchInstanceType': 'string',
'SearchPartitionCount': 123,
'SearchInstanceCount': 123,
'Limits': {
'MaximumReplicationCount': 123,
'MaximumPartitionCount': 123
}
}
}
Response Structure
• (dict) –
The result of a DeleteDomain request. Contains the status of a newly deleted
domain, or no status if the domain has already been completely deleted.
– DomainStatus (dict) –
The current status of the search domain.
* DomainId (string) –
An internally generated unique identifier for a domain.
* DomainName (string) –
A string that represents the name of a domain. Domain names are
unique across the domains owned by an account within an AWS
region. Domain names start with a letter or number and can contain
the following characters: a-z (lowercase), 0-9, and - (hyphen).
* ARN (string) –
The Amazon Resource Name (ARN) of the search domain. See
Identifiers for IAM Entities in Using AWS Identity and Access Man-
agement for more information.
* Created (boolean) –
True if the search domain is created. It can take several minutes to
initialize a domain when CreateDomain is called. Newly created
search domains are returned from DescribeDomains with a false
value for Created until domain creation is complete.
* Deleted (boolean) –
True if the search domain has been deleted. The system must clean
up resources dedicated to the search domain when DeleteDomain
is called. Newly deleted search domains are returned from De-
scribeDomains with a true value for IsDeleted for several minutes
until resource cleanup is complete.
* DocService (dict) –
The service endpoint for updating documents in a search domain.
· Endpoint (string) –
The endpoint to which service re-
quests can be submitted. For example,
search-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.cl
or doc-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.clo
.
362 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* SearchService (dict) –
The service endpoint for requesting search results from a search do-
main.
· Endpoint (string) –
The endpoint to which service re-
quests can be submitted. For example,
search-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.cl
or doc-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.clo
.
* RequiresIndexDocuments (boolean) –
True if IndexDocuments needs to be called to activate the current
domain configuration.
* Processing (boolean) –
True if processing is being done to activate the current domain con-
figuration.
* SearchInstanceType (string) –
The instance type that is being used to process search requests.
* SearchPartitionCount (integer) –
The number of partitions across which the search index is spread.
* SearchInstanceCount (integer) –
The number of search instances that are available to process search
requests.
* Limits (dict) –
· MaximumReplicationCount (integer) –
· MaximumPartitionCount (integer) –
delete_expression(**kwargs)
Removes an ‘‘ Expression‘‘ from the search domain. For more information, see Configuring Expressions
in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.delete_expression(
DomainName='string',
ExpressionName='string'
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• ExpressionName (string) – [REQUIRED]
The name of the ‘‘ Expression‘‘ to delete.
Return type dict
Returns
Response Syntax
3.1. Services 363
Boto3 Documentation, Release 1.1.4
{
'Expression': {
'Options': {
'ExpressionName': 'string',
'ExpressionValue': 'string'
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a ‘‘ DeleteExpression‘‘ request. Specifies the expression being
deleted.
– Expression (dict) –
The status of the expression being deleted.
* Options (dict) –
The expression that is evaluated for sorting while processing a
search request.
· ExpressionName (string) –
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· ExpressionValue (string) –
The expression to evaluate for sorting while processing a
search request. The Expression syntax is based on
JavaScript expressions. For more information, see Configur-
ing Expressions in the Amazon CloudSearch Developer Guide
.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
364 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
delete_index_field(**kwargs)
Removes an ‘‘ IndexField‘‘ from the search domain. For more information, see Configuring Index Fields
in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.delete_index_field(
DomainName='string',
IndexFieldName='string'
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• IndexFieldName (string) – [REQUIRED]
The name of the index field your want to remove from the domain’s indexing
options.
Return type dict
Returns
Response Syntax
{
'IndexField': {
'Options': {
'IndexFieldName': 'string',
'IndexFieldType': 'int'|'double'|'literal'|'text'|'date'|'latlon'|'int
'IntOptions': {
'DefaultValue': 123,
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'DoubleOptions': {
'DefaultValue': 123.0,
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
3.1. Services 365
Boto3 Documentation, Release 1.1.4
},
'LiteralOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'TextOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'ReturnEnabled': True|False,
'SortEnabled': True|False,
'HighlightEnabled': True|False,
'AnalysisScheme': 'string'
},
'DateOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'LatLonOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'IntArrayOptions': {
'DefaultValue': 123,
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'DoubleArrayOptions': {
'DefaultValue': 123.0,
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'LiteralArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'TextArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'ReturnEnabled': True|False,
366 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'HighlightEnabled': True|False,
'AnalysisScheme': 'string'
},
'DateArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a ‘‘ DeleteIndexField‘‘ request.
– IndexField (dict) –
The status of the index field being deleted.
* Options (dict) –
Configuration information for a field in the index, including its
name, type, and options. The supported options depend on the ‘‘
IndexFieldType‘‘ .
· IndexFieldName (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· IndexFieldType (string) –
The type of field. The valid options for a field depend on the
field type. For more information about the supported field
types, see Configuring Index Fields in the Amazon Cloud-
Search Developer Guide .
· IntOptions (dict) –
3.1. Services 367
Boto3 Documentation, Release 1.1.4
Options for a 64-bit signed integer field. Present if
IndexFieldType specifies the field is of type int . All
options are enabled by default.
· DefaultValue (integer) – A value to use for the field if the
field isn’t specified for a document. This can be important if
you are using the field in an expression and that field is not
present in every document.
· SourceField (string) –
The name of the source field to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· DoubleOptions (dict) –
Options for a double-precision 64-bit floating point field.
Present if IndexFieldType specifies the field is of type
double . All options are enabled by default.
· DefaultValue (float) –
A value to use for the field if the field isn’t specified for a
document. This can be important if you are using the field in
an expression and that field is not present in every document.
· SourceField (string) –
The name of the source field to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· LiteralOptions (dict) –
Options for literal field. Present if IndexFieldType spec-
ifies the field is of type literal . All options are enabled
by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
368 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· TextOptions (dict) –
Options for text field. Present if IndexFieldType speci-
fies the field is of type text . A text field is always search-
able. All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
3.1. Services 369
Boto3 Documentation, Release 1.1.4
· HighlightEnabled (boolean) –
Whether highlights can be returned for the field.
· AnalysisScheme (string) –
The name of an analysis scheme for a text field.
· DateOptions (dict) –
Options for a date field. Dates and times are specified in UTC
(Coordinated Universal Time) according to IETF RFC3339:
yyyy-mm-ddT00:00:00Z. Present if IndexFieldType
specifies the field is of type date . All options are enabled
by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· LatLonOptions (dict) –
Options for a latlon field. A latlon field contains a loca-
tion stored as a latitude and longitude value pair. Present if
IndexFieldType specifies the field is of type latlon .
All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
370 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· IntArrayOptions (dict) –
Options for a field that contains an array of 64-bit signed in-
tegers. Present if IndexFieldType specifies the field is of
type int-array . All options are enabled by default.
· DefaultValue (integer) – A value to use for the field if the
field isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· DoubleArrayOptions (dict) –
Options for a field that contains an array of double-precision
64-bit floating point values. Present if IndexFieldType
specifies the field is of type double-array . All options
are enabled by default.
· DefaultValue (float) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
3.1. Services 371
Boto3 Documentation, Release 1.1.4
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· LiteralArrayOptions (dict) –
Options for a field that contains an array of literal strings.
Present if IndexFieldType specifies the field is of type
literal-array . All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· TextArrayOptions (dict) –
Options for a field that contains an array of text strings.
Present if IndexFieldType specifies the field is of type
text-array . A text-array field is always searchable.
All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· HighlightEnabled (boolean) –
Whether highlights can be returned for the field.
· AnalysisScheme (string) –
The name of an analysis scheme for a text-array field.
· DateArrayOptions (dict) –
Options for a field that contains an array of dates.
Present if IndexFieldType specifies the field is of type
date-array . All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
372 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
delete_suggester(**kwargs)
Deletes a suggester. For more information, see Getting Search Suggestions in the Amazon CloudSearch
Developer Guide .
Request Syntax
response = client.delete_suggester(
DomainName='string',
SuggesterName='string'
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• SuggesterName (string) – [REQUIRED]
Specifies the name of the suggester you want to delete.
Return type dict
3.1. Services 373
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'Suggester': {
'Options': {
'SuggesterName': 'string',
'DocumentSuggesterOptions': {
'SourceField': 'string',
'FuzzyMatching': 'none'|'low'|'high',
'SortExpression': 'string'
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a DeleteSuggester request. Contains the status of the deleted
suggester.
– Suggester (dict) –
The status of the suggester being deleted.
* Options (dict) –
Configuration information for a search suggester. Each suggester
has a unique name and specifies the text field you want to use for
suggestions. The following options can be configured for a sug-
gester: FuzzyMatching , SortExpression .
· SuggesterName (string) –
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· DocumentSuggesterOptions (dict) –
Options for a search suggester.
· SourceField (string) –
The name of the index field you want to use for suggestions.
· FuzzyMatching (string) –
The level of fuzziness allowed when suggesting matches for
a string: none , low , or high . With none, the specified
string is treated as an exact prefix. With low, suggestions must
differ from the specified string by no more than one character.
With high, suggestions can differ by up to two characters. The
default is none.
· SortExpression (string) –
An expression that computes a score for each suggestion to
control how they are sorted. The scores are rounded to the
374 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
nearest integer, with a floor of 0 and a ceiling of 2^31-1. A
document’s relevance score is not computed for suggestions,
so sort expressions cannot reference the _score value. To
sort suggestions using a numeric field or existing expression,
simply specify the name of the field or expression. If no ex-
pression is configured for the suggester, the suggestions are
sorted with the closest matches listed first.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
describe_analysis_schemes(**kwargs)
Gets the analysis schemes configured for a domain. An analysis scheme defines language-specific text
processing options for a text field. Can be limited to specific analysis schemes by name. By default,
shows all analysis schemes and includes any pending changes to the configuration. Set the Deployed
option to true to show the active configuration and exclude pending changes. For more information, see
Configuring Analysis Schemes in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.describe_analysis_schemes(
DomainName='string',
AnalysisSchemeNames=[
'string',
],
Deployed=True|False
)
Parameters
• DomainName (string) – [REQUIRED]
The name of the domain you want to describe.
3.1. Services 375
Boto3 Documentation, Release 1.1.4
• AnalysisSchemeNames (list) – The analysis schemes you want to describe.
– (string) –
Names must begin with a letter and can contain the following characters:
a-z (lowercase), 0-9, and _ (underscore).
• Deployed (boolean) – Whether to display the deployed configuration (true )
or include any pending changes (false ). Defaults to false .
Return type dict
Returns
Response Syntax
{
'AnalysisSchemes': [
{
'Options': {
'AnalysisSchemeName': 'string',
'AnalysisSchemeLanguage': 'ar'|'bg'|'ca'|'cs'|'da'|'de'|'el'|'en'|
'AnalysisOptions': {
'Synonyms': 'string',
'Stopwords': 'string',
'StemmingDictionary': 'string',
'JapaneseTokenizationDictionary': 'string',
'AlgorithmicStemming': 'none'|'minimal'|'light'|'full'
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToV
'PendingDeletion': True|False
}
},
]
}
Response Structure
• (dict) –
The result of a DescribeAnalysisSchemes request. Contains the analysis
schemes configured for the domain specified in the request.
– AnalysisSchemes (list) –
The analysis scheme descriptions.
* (dict) –
The status and configuration of an AnalysisScheme .
· Options (dict) –
Configuration information for an analysis scheme. Each
analysis scheme has a unique name and specifies the
language of the text to be processed. The follow-
ing options can be configured for an analysis scheme:
Synonyms , Stopwords , StemmingDictionary
, JapaneseTokenizationDictionary and
AlgorithmicStemming .
· AnalysisSchemeName (string) –
376 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· AnalysisSchemeLanguage (string) –
An IETF RFC 4646 language code or mul for multiple lan-
guages.
· AnalysisOptions (dict) –
Synonyms, stopwords, and stemming options for an analysis
scheme. Includes tokenization dictionary for Japanese.
· Synonyms (string) –
A JSON object that defines synonym groups and aliases. A
synonym group is an array of arrays, where each sub-array is
a group of terms where each term in the group is considered a
synonym of every other term in the group. The aliases value is
an object that contains a collection of string:value pairs where
the string specifies a term and the array of values specifies
each of the aliases for that term. An alias is considered a syn-
onym of the specified term, but the term is not considered a
synonym of the alias. For more information about specifying
synonyms, see Synonyms in the Amazon CloudSearch Devel-
oper Guide .
· Stopwords (string) –
A JSON array of terms to ignore during indexing and search-
ing. For example, ["a", "an", "the", "of"] . The
stopwords dictionary must explicitly list each word you want
to ignore. Wildcards and regular expressions are not sup-
ported.
· StemmingDictionary (string) –
A JSON object that contains a collection of string:value
pairs that each map a term to its stem. For exam-
ple, {"term1": "stem1", "term2": "stem2",
"term3": "stem3"} . The stemming dictionary is ap-
plied in addition to any algorithmic stemming. This enables
you to override the results of the algorithmic stemming to cor-
rect specific cases of overstemming or understemming. The
maximum size of a stemming dictionary is 500 KB.
· JapaneseTokenizationDictionary (string) –
A JSON array that contains a collection of terms, tokens,
readings and part of speech for Japanese Tokenizaiton. The
Japanese tokenization dictionary enables you to override the
default tokenization for selected terms. This is only valid for
Japanese language fields.
· AlgorithmicStemming (string) –
The level of algorithmic stemming to perform: none ,
minimal , light , or full . The available levels vary
depending on the language. For more information, see Lan-
guage Specific Text Processing Settings in the Amazon Cloud-
Search Developer Guide
· Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
3.1. Services 377
Boto3 Documentation, Release 1.1.4
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
describe_availability_options(**kwargs)
Gets the availability options configured for a domain. By default, shows the configuration with any
pending changes. Set the Deployed option to true to show the active configuration and exclude
pending changes. For more information, see Configuring Availability Options in the Amazon CloudSearch
Developer Guide .
Request Syntax
response = client.describe_availability_options(
DomainName='string',
Deployed=True|False
)
Parameters
• DomainName (string) – [REQUIRED]
The name of the domain you want to describe.
• Deployed (boolean) – Whether to display the deployed configuration (true )
or include any pending changes (false ). Defaults to false .
Return type dict
Returns
Response Syntax
{
'AvailabilityOptions': {
'Options': True|False,
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
378 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
}
}
}
Response Structure
• (dict) –
The result of a DescribeAvailabilityOptions request. Indicates
whether or not the Multi-AZ option is enabled for the domain specified in the
request.
– AvailabilityOptions (dict) –
The availability options configured for the domain. Indicates whether
Multi-AZ is enabled for the domain.
* Options (boolean) –
The availability options configured for the domain.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
describe_domains(**kwargs)
Gets information about the search domains owned by this account. Can be limited to spe-
cific domains. Shows all domains by default. To get the number of searchable documents in
a domain, use the console or submit a matchall request to your domain’s search endpoint:
q=matchallamp;q.parser=structuredamp;size=0 . For more information, see Getting In-
formation about a Search Domain in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.describe_domains(
DomainNames=[
3.1. Services 379
Boto3 Documentation, Release 1.1.4
'string',
]
)
Parameters DomainNames (list) – The names of the domains you want to include in the
response.
• (string) –
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
Return type dict
Returns
Response Syntax
{
'DomainStatusList': [
{
'DomainId': 'string',
'DomainName': 'string',
'ARN': 'string',
'Created': True|False,
'Deleted': True|False,
'DocService': {
'Endpoint': 'string'
},
'SearchService': {
'Endpoint': 'string'
},
'RequiresIndexDocuments': True|False,
'Processing': True|False,
'SearchInstanceType': 'string',
'SearchPartitionCount': 123,
'SearchInstanceCount': 123,
'Limits': {
'MaximumReplicationCount': 123,
'MaximumPartitionCount': 123
}
},
]
}
Response Structure
• (dict) –
The result of a DescribeDomains request. Contains the status of the domains
specified in the request or all domains owned by the account.
– DomainStatusList (list) –
A list that contains the status of each requested domain.
* (dict) –
The current status of the search domain.
· DomainId (string) –
An internally generated unique identifier for a domain.
· DomainName (string) –
380 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A string that represents the name of a domain. Domain names
are unique across the domains owned by an account within an
AWS region. Domain names start with a letter or number and
can contain the following characters: a-z (lowercase), 0-9,
and - (hyphen).
· ARN (string) –
The Amazon Resource Name (ARN) of the search domain.
See Identifiers for IAM Entities in Using AWS Identity and
Access Management for more information.
· Created (boolean) –
True if the search domain is created. It can take several
minutes to initialize a domain when CreateDomain is called.
Newly created search domains are returned from DescribeDo-
mains with a false value for Created until domain creation is
complete.
· Deleted (boolean) –
True if the search domain has been deleted. The system
must clean up resources dedicated to the search domain when
DeleteDomain is called. Newly deleted search domains are
returned from DescribeDomains with a true value for Is-
Deleted for several minutes until resource cleanup is com-
plete.
· DocService (dict) –
The service endpoint for updating documents in a search do-
main.
· Endpoint (string) –
The endpoint to which service re-
quests can be submitted. For example,
search-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.cl
or doc-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.clo
.
· SearchService (dict) –
The service endpoint for requesting search results from a
search domain.
· Endpoint (string) –
The endpoint to which service re-
quests can be submitted. For example,
search-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.cl
or doc-imdb-movies-oopcnjfn6ugofer3zx5iadxxca.eu-west-1.clo
.
· RequiresIndexDocuments (boolean) –
True if IndexDocuments needs to be called to activate the cur-
rent domain configuration.
· Processing (boolean) –
True if processing is being done to activate the current domain
configuration.
· SearchInstanceType (string) –
The instance type that is being used to process search re-
quests.
3.1. Services 381
Boto3 Documentation, Release 1.1.4
· SearchPartitionCount (integer) –
The number of partitions across which the search index is
spread.
· SearchInstanceCount (integer) –
The number of search instances that are available to process
search requests.
· Limits (dict) –
· MaximumReplicationCount (integer) –
· MaximumPartitionCount (integer) –
describe_expressions(**kwargs)
Gets the expressions configured for the search domain. Can be limited to specific expressions by name. By
default, shows all expressions and includes any pending changes to the configuration. Set the Deployed
option to true to show the active configuration and exclude pending changes. For more information, see
Configuring Expressions in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.describe_expressions(
DomainName='string',
ExpressionNames=[
'string',
],
Deployed=True|False
)
Parameters
• DomainName (string) – [REQUIRED]
The name of the domain you want to describe.
• ExpressionNames (list) – Limits the ‘‘ DescribeExpressions‘‘ response to the
specified expressions. If not specified, all expressions are shown.
– (string) –
Names must begin with a letter and can contain the following characters:
a-z (lowercase), 0-9, and _ (underscore).
• Deployed (boolean) – Whether to display the deployed configuration (true )
or include any pending changes (false ). Defaults to false .
Return type dict
Returns
Response Syntax
{
'Expressions': [
{
'Options': {
'ExpressionName': 'string',
'ExpressionValue': 'string'
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToV
'PendingDeletion': True|False
}
382 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
]
}
Response Structure
• (dict) –
The result of a DescribeExpressions request. Contains the expressions
configured for the domain specified in the request.
– Expressions (list) –
The expressions configured for the domain.
* (dict) –
The value of an Expression and its current status.
· Options (dict) –
The expression that is evaluated for sorting while processing
a search request.
· ExpressionName (string) –
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· ExpressionValue (string) –
The expression to evaluate for sorting while processing a
search request. The Expression syntax is based on
JavaScript expressions. For more information, see Configur-
ing Expressions in the Amazon CloudSearch Developer Guide
.
· Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
3.1. Services 383
Boto3 Documentation, Release 1.1.4
describe_index_fields(**kwargs)
Gets information about the index fields configured for the search domain. Can be limited to specific fields
by name. By default, shows all fields and includes any pending changes to the configuration. Set the
Deployed option to true to show the active configuration and exclude pending changes. For more
information, see Getting Domain Information in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.describe_index_fields(
DomainName='string',
FieldNames=[
'string',
],
Deployed=True|False
)
Parameters
• DomainName (string) – [REQUIRED]
The name of the domain you want to describe.
• FieldNames (list) – A list of the index fields you want to describe. If not speci-
fied, information is returned for all configured index fields.
– (string) –
• Deployed (boolean) – Whether to display the deployed configuration (true )
or include any pending changes (false ). Defaults to false .
Return type dict
Returns
Response Syntax
{
'IndexFields': [
{
'Options': {
'IndexFieldName': 'string',
'IndexFieldType': 'int'|'double'|'literal'|'text'|'date'|'latlon'|
'IntOptions': {
'DefaultValue': 123,
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'DoubleOptions': {
'DefaultValue': 123.0,
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'LiteralOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
384 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'SortEnabled': True|False
},
'TextOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'ReturnEnabled': True|False,
'SortEnabled': True|False,
'HighlightEnabled': True|False,
'AnalysisScheme': 'string'
},
'DateOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'LatLonOptions': {
'DefaultValue': 'string',
'SourceField': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False,
'SortEnabled': True|False
},
'IntArrayOptions': {
'DefaultValue': 123,
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'DoubleArrayOptions': {
'DefaultValue': 123.0,
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'LiteralArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'FacetEnabled': True|False,
'SearchEnabled': True|False,
'ReturnEnabled': True|False
},
'TextArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'ReturnEnabled': True|False,
'HighlightEnabled': True|False,
'AnalysisScheme': 'string'
},
'DateArrayOptions': {
'DefaultValue': 'string',
'SourceFields': 'string',
'FacetEnabled': True|False,
3.1. Services 385
Boto3 Documentation, Release 1.1.4
'SearchEnabled': True|False,
'ReturnEnabled': True|False
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToV
'PendingDeletion': True|False
}
},
]
}
Response Structure
• (dict) –
The result of a DescribeIndexFields request. Contains the index fields
configured for the domain specified in the request.
– IndexFields (list) –
The index fields configured for the domain.
* (dict) –
The value of an IndexField and its current status.
· Options (dict) –
Configuration information for a field in the index, including
its name, type, and options. The supported options depend on
the ‘‘ IndexFieldType‘‘ .
· IndexFieldName (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· IndexFieldType (string) –
The type of field. The valid options for a field depend on the
field type. For more information about the supported field
types, see Configuring Index Fields in the Amazon Cloud-
Search Developer Guide .
· IntOptions (dict) –
Options for a 64-bit signed integer field. Present if
386 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
IndexFieldType specifies the field is of type int . All
options are enabled by default.
· DefaultValue (integer) – A value to use for the field if the
field isn’t specified for a document. This can be important if
you are using the field in an expression and that field is not
present in every document.
· SourceField (string) –
The name of the source field to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· DoubleOptions (dict) –
Options for a double-precision 64-bit floating point field.
Present if IndexFieldType specifies the field is of type
double . All options are enabled by default.
· DefaultValue (float) –
A value to use for the field if the field isn’t specified for a
document. This can be important if you are using the field in
an expression and that field is not present in every document.
· SourceField (string) –
The name of the source field to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· LiteralOptions (dict) –
Options for literal field. Present if IndexFieldType spec-
ifies the field is of type literal . All options are enabled
by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
3.1. Services 387
Boto3 Documentation, Release 1.1.4
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· TextOptions (dict) –
Options for text field. Present if IndexFieldType speci-
fies the field is of type text . A text field is always search-
able. All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
388 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· HighlightEnabled (boolean) –
Whether highlights can be returned for the field.
· AnalysisScheme (string) –
The name of an analysis scheme for a text field.
· DateOptions (dict) –
Options for a date field. Dates and times are specified in UTC
(Coordinated Universal Time) according to IETF RFC3339:
yyyy-mm-ddT00:00:00Z. Present if IndexFieldType
specifies the field is of type date . All options are enabled
by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· LatLonOptions (dict) –
Options for a latlon field. A latlon field contains a loca-
tion stored as a latitude and longitude value pair. Present if
IndexFieldType specifies the field is of type latlon .
All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceField (string) –
A string that represents the name of an index field. Cloud-
Search supports regular index fields as well as dynamic fields.
A dynamic field’s name defines a pattern that begins or ends
3.1. Services 389
Boto3 Documentation, Release 1.1.4
with a wildcard. Any document fields that don’t map to a
regular index field but do match a dynamic field’s pattern are
configured with the dynamic field’s indexing options.
Regular field names begin with a letter and can contain the
following characters: a-z (lowercase), 0-9, and _ (under-
score). Dynamic field names must begin or end with a wild-
card (*). The wildcard can also be the only character in a
dynamic field name. Multiple wildcards, and wildcards em-
bedded within a string are not supported.
The name score is reserved and cannot be used as a field
name. To reference a document’s ID, you can use the name
_id .
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· SortEnabled (boolean) –
Whether the field can be used to sort the search results.
· IntArrayOptions (dict) –
Options for a field that contains an array of 64-bit signed in-
tegers. Present if IndexFieldType specifies the field is of
type int-array . All options are enabled by default.
· DefaultValue (integer) – A value to use for the field if the
field isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· DoubleArrayOptions (dict) –
Options for a field that contains an array of double-precision
64-bit floating point values. Present if IndexFieldType
specifies the field is of type double-array . All options
are enabled by default.
· DefaultValue (float) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
390 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· LiteralArrayOptions (dict) –
Options for a field that contains an array of literal strings.
Present if IndexFieldType specifies the field is of type
literal-array . All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· TextArrayOptions (dict) –
Options for a field that contains an array of text strings.
Present if IndexFieldType specifies the field is of type
text-array . A text-array field is always searchable.
All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· HighlightEnabled (boolean) –
Whether highlights can be returned for the field.
· AnalysisScheme (string) –
The name of an analysis scheme for a text-array field.
· DateArrayOptions (dict) –
Options for a field that contains an array of dates.
Present if IndexFieldType specifies the field is of type
date-array . All options are enabled by default.
· DefaultValue (string) – A value to use for the field if the field
isn’t specified for a document.
· SourceFields (string) –
A list of source fields to map to the field.
· FacetEnabled (boolean) –
Whether facet information can be returned for the field.
3.1. Services 391
Boto3 Documentation, Release 1.1.4
· SearchEnabled (boolean) –
Whether the contents of the field are searchable.
· ReturnEnabled (boolean) –
Whether the contents of the field can be returned in the search
results.
· Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
describe_scaling_parameters(**kwargs)
Gets the scaling parameters configured for a domain. A domain’s scaling parameters specify the desired
search instance type and replication count. For more information, see Configuring Scaling Options in the
Amazon CloudSearch Developer Guide .
Request Syntax
response = client.describe_scaling_parameters(
DomainName='string'
)
Parameters DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across the
domains owned by an account within an AWS region. Domain names start with a
letter or number and can contain the following characters: a-z (lowercase), 0-9, and -
(hyphen).
Return type dict
Returns
Response Syntax
392 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'ScalingParameters': {
'Options': {
'DesiredInstanceType': 'search.m1.small'|'search.m1.large'|'search.m2.
'DesiredReplicationCount': 123,
'DesiredPartitionCount': 123
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a DescribeScalingParameters request. Contains the scal-
ing parameters configured for the domain specified in the request.
– ScalingParameters (dict) –
The status and configuration of a search domain’s scaling parameters.
* Options (dict) –
The desired instance type and desired number of replicas of each
index partition.
· DesiredInstanceType (string) –
The instance type that you want to preconfigure for your do-
main. For example, search.m1.small .
· DesiredReplicationCount (integer) –
The number of replicas you want to preconfigure for each in-
dex partition.
· DesiredPartitionCount (integer) –
The number of partitions you want to preconfigure for your
domain. Only valid when you select m2.2xlarge as the
desired instance type.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
3.1. Services 393
Boto3 Documentation, Release 1.1.4
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
describe_service_access_policies(**kwargs)
Gets information about the access policies that control access to the domain’s document and search end-
points. By default, shows the configuration with any pending changes. Set the Deployed option to
true to show the active configuration and exclude pending changes. For more information, see Config-
uring Access for a Search Domain in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.describe_service_access_policies(
DomainName='string',
Deployed=True|False
)
Parameters
• DomainName (string) – [REQUIRED]
The name of the domain you want to describe.
• Deployed (boolean) – Whether to display the deployed configuration (true )
or include any pending changes (false ). Defaults to false .
Return type dict
Returns
Response Syntax
{
'AccessPolicies': {
'Options': 'string',
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a DescribeServiceAccessPolicies request.
– AccessPolicies (dict) –
The access rules configured for the domain specified in the request.
394 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Options (string) –
Access rules for a domain’s document or search service endpoints.
For more information, see Configuring Access for a Search Domain
in the Amazon CloudSearch Developer Guide . The maximum size
of a policy document is 100 KB.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
describe_suggesters(**kwargs)
Gets the suggesters configured for a domain. A suggester enables you to display possible matches before
users finish typing their queries. Can be limited to specific suggesters by name. By default, shows all
suggesters and includes any pending changes to the configuration. Set the Deployed option to true
to show the active configuration and exclude pending changes. For more information, see Getting Search
Suggestions in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.describe_suggesters(
DomainName='string',
SuggesterNames=[
'string',
],
Deployed=True|False
)
Parameters
• DomainName (string) – [REQUIRED]
The name of the domain you want to describe.
• SuggesterNames (list) – The suggesters you want to describe.
3.1. Services 395
Boto3 Documentation, Release 1.1.4
– (string) –
Names must begin with a letter and can contain the following characters:
a-z (lowercase), 0-9, and _ (underscore).
• Deployed (boolean) – Whether to display the deployed configuration (true )
or include any pending changes (false ). Defaults to false .
Return type dict
Returns
Response Syntax
{
'Suggesters': [
{
'Options': {
'SuggesterName': 'string',
'DocumentSuggesterOptions': {
'SourceField': 'string',
'FuzzyMatching': 'none'|'low'|'high',
'SortExpression': 'string'
}
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToV
'PendingDeletion': True|False
}
},
]
}
Response Structure
• (dict) –
The result of a DescribeSuggesters request.
– Suggesters (list) –
The suggesters configured for the domain specified in the request.
* (dict) –
The value of a Suggester and its current status.
· Options (dict) –
Configuration information for a search suggester. Each
suggester has a unique name and specifies the text field
you want to use for suggestions. The following options
can be configured for a suggester: FuzzyMatching ,
SortExpression .
· SuggesterName (string) –
Names must begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore).
· DocumentSuggesterOptions (dict) –
Options for a search suggester.
· SourceField (string) –
The name of the index field you want to use for suggestions.
396 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· FuzzyMatching (string) –
The level of fuzziness allowed when suggesting matches for
a string: none , low , or high . With none, the specified
string is treated as an exact prefix. With low, suggestions must
differ from the specified string by no more than one character.
With high, suggestions can differ by up to two characters. The
default is none.
· SortExpression (string) –
An expression that computes a score for each suggestion to
control how they are sorted. The scores are rounded to the
nearest integer, with a floor of 0 and a ceiling of 2^31-1. A
document’s relevance score is not computed for suggestions,
so sort expressions cannot reference the _score value. To
sort suggestions using a numeric field or existing expression,
simply specify the name of the field or expression. If no ex-
pression is configured for the suggester, the suggestions are
sorted with the closest matches listed first.
· Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
3.1. Services 397
Boto3 Documentation, Release 1.1.4
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
index_documents(**kwargs)
Tells the search domain to start indexing its documents using the latest indexing options. This operation
must be invoked to activate options whose OptionStatus is RequiresIndexDocuments .
Request Syntax
response = client.index_documents(
DomainName='string'
)
Parameters DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across the
domains owned by an account within an AWS region. Domain names start with a
letter or number and can contain the following characters: a-z (lowercase), 0-9, and -
(hyphen).
Return type dict
Returns
Response Syntax
{
'FieldNames': [
'string',
]
}
Response Structure
• (dict) –
The result of an IndexDocuments request. Contains the status of the indexing
operation, including the fields being indexed.
– FieldNames (list) –
The names of the fields that are currently being indexed.
* (string) –
A string that represents the name of an index field. CloudSearch
supports regular index fields as well as dynamic fields. A dynamic
field’s name defines a pattern that begins or ends with a wildcard.
Any document fields that don’t map to a regular index field but do
398 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
match a dynamic field’s pattern are configured with the dynamic
field’s indexing options.
Regular field names begin with a letter and can contain the following
characters: a-z (lowercase), 0-9, and _ (underscore). Dynamic field
names must begin or end with a wildcard (*). The wildcard can also
be the only character in a dynamic field name. Multiple wildcards,
and wildcards embedded within a string are not supported.
The name score is reserved and cannot be used as a field name.
To reference a document’s ID, you can use the name _id .
list_domain_names()
Lists all search domains owned by an account.
Request Syntax
response = client.list_domain_names()
Return type dict
Returns
Response Syntax
{
'DomainNames': {
'string': 'string'
}
}
Response Structure
• (dict) –
The result of a ListDomainNames request. Contains a list of the domains
owned by an account.
– DomainNames (dict) –
The names of the search domains owned by an account.
* (string) –
A string that represents the name of a domain. Domain names are
unique across the domains owned by an account within an AWS
region. Domain names start with a letter or number and can contain
the following characters: a-z (lowercase), 0-9, and - (hyphen).
· (string) –
The Amazon CloudSearch API version for a domain: 2011-
02-01 or 2013-01-01.
update_availability_options(**kwargs)
Configures the availability options for a domain. Enabling the Multi-AZ option expands an Amazon
CloudSearch domain to an additional Availability Zone in the same Region to increase fault tolerance in
the event of a service disruption. Changes to the Multi-AZ option can take about half an hour to become
active. For more information, see Configuring Availability Options in the Amazon CloudSearch Developer
Guide .
Request Syntax
3.1. Services 399
Boto3 Documentation, Release 1.1.4
response = client.update_availability_options(
DomainName='string',
MultiAZ=True|False
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• MultiAZ (boolean) – [REQUIRED]
You expand an existing search domain to a second Availability Zone by setting
the Multi-AZ option to true. Similarly, you can turn off the Multi-AZ option
to downgrade the domain to a single Availability Zone by setting the Multi-AZ
option to false .
Return type dict
Returns
Response Syntax
{
'AvailabilityOptions': {
'Options': True|False,
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a UpdateAvailabilityOptions request. Contains the status
of the domain’s availability options.
– AvailabilityOptions (dict) –
The newly-configured availability options. Indicates whether Multi-AZ is
enabled for the domain.
* Options (boolean) –
The availability options configured for the domain.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
400 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
update_scaling_parameters(**kwargs)
Configures scaling parameters for a domain. A domain’s scaling parameters specify the desired search
instance type and replication count. Amazon CloudSearch will still automatically scale your domain
based on the volume of data and traffic, but not below the desired instance type and replication count. If
the Multi-AZ option is enabled, these values control the resources used per Availability Zone. For more
information, see Configuring Scaling Options in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.update_scaling_parameters(
DomainName='string',
ScalingParameters={
'DesiredInstanceType': 'search.m1.small'|'search.m1.large'|'search.m2.xlarge'|'searc
'DesiredReplicationCount': 123,
'DesiredPartitionCount': 123
}
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• ScalingParameters (dict) – [REQUIRED]
The desired instance type and desired number of replicas of each index partition.
– DesiredInstanceType (string) –
The instance type that you want to preconfigure for your domain. For
example, search.m1.small .
– DesiredReplicationCount (integer) –
The number of replicas you want to preconfigure for each index partition.
– DesiredPartitionCount (integer) –
The number of partitions you want to preconfigure for your domain. Only
valid when you select m2.2xlarge as the desired instance type.
3.1. Services 401
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'ScalingParameters': {
'Options': {
'DesiredInstanceType': 'search.m1.small'|'search.m1.large'|'search.m2.
'DesiredReplicationCount': 123,
'DesiredPartitionCount': 123
},
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
• (dict) –
The result of a UpdateScalingParameters request. Contains the status of
the newly-configured scaling parameters.
– ScalingParameters (dict) –
The status and configuration of a search domain’s scaling parameters.
* Options (dict) –
The desired instance type and desired number of replicas of each
index partition.
· DesiredInstanceType (string) –
The instance type that you want to preconfigure for your do-
main. For example, search.m1.small .
· DesiredReplicationCount (integer) –
The number of replicas you want to preconfigure for each in-
dex partition.
· DesiredPartitionCount (integer) –
The number of partitions you want to preconfigure for your
domain. Only valid when you select m2.2xlarge as the
desired instance type.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
402 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
update_service_access_policies(**kwargs)
Configures the access rules that control access to the domain’s document and search endpoints. For more
information, see Configuring Access for an Amazon CloudSearch Domain .
Request Syntax
response = client.update_service_access_policies(
DomainName='string',
AccessPolicies='string'
)
Parameters
• DomainName (string) – [REQUIRED]
A string that represents the name of a domain. Domain names are unique across
the domains owned by an account within an AWS region. Domain names start
with a letter or number and can contain the following characters: a-z (lowercase),
0-9, and - (hyphen).
• AccessPolicies (string) – [REQUIRED]
The access rules you want to configure. These rules replace any existing rules.
Return type dict
Returns
Response Syntax
{
'AccessPolicies': {
'Options': 'string',
'Status': {
'CreationDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'UpdateVersion': 123,
'State': 'RequiresIndexDocuments'|'Processing'|'Active'|'FailedToValid
'PendingDeletion': True|False
}
}
}
Response Structure
3.1. Services 403
Boto3 Documentation, Release 1.1.4
• (dict) –
The result of an UpdateServiceAccessPolicies request. Contains the
new access policies.
– AccessPolicies (dict) –
The access rules configured for the domain.
* Options (string) –
Access rules for a domain’s document or search service endpoints.
For more information, see Configuring Access for a Search Domain
in the Amazon CloudSearch Developer Guide . The maximum size
of a policy document is 100 KB.
* Status (dict) –
The status of domain configuration option.
· CreationDate (datetime) –
A timestamp for when this option was created.
· UpdateDate (datetime) –
A timestamp for when this option was last updated.
· UpdateVersion (integer) –
A unique integer that indicates when this option was last up-
dated.
· State (string) –
The state of processing a change to an option. Possible values:
· RequiresIndexDocuments : the option’s latest value
will not be deployed until IndexDocuments has been called
and indexing is complete.
· Processing : the option’s latest value is in the process of
being activated.
· Active : the option’s latest value is completely deployed.
· FailedToValidate : the option value is not compatible
with the domain’s data and cannot be used to index the data.
You must either modify the option value or update or remove
the incompatible documents.
· PendingDeletion (boolean) –
Indicates that the option will be deleted once processing is
complete.
CloudSearchDomain
Table of Contents
• CloudSearchDomain
– Client
Client
class CloudSearchDomain.Client
A low-level client representing Amazon CloudSearch Domain:
404 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
import boto3
client = boto3.client('cloudsearchdomain')
These are the available methods:
•can_paginate()
•generate_presigned_url()
•get_paginator()
•get_waiter()
•search()
•suggest()
•upload_documents()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
search(**kwargs)
Retrieves a list of documents that match the specified search criteria. How you specify the search criteria
depends on which query parser you use. Amazon CloudSearch supports four query parsers:
•simple : search all text and text-array fields for the specified string. Search for phrases,
individual terms, and prefixes.
•structured : search specific fields, construct compound queries using Boolean operators, and
use advanced features such as term boosting and proximity searching.
•lucene : specify search criteria using the Apache Lucene query parser syntax.
•dismax : specify search criteria using the simplified subset of the Apache Lucene query parser
3.1. Services 405
Boto3 Documentation, Release 1.1.4
syntax defined by the DisMax query parser.
For more information, see Searching Your Data in the Amazon CloudSearch Developer Guide .
The endpoint for submitting Search requests is domain-specific. You submit search requests to a do-
main’s search endpoint. To get the search endpoint for your domain, use the Amazon CloudSearch con-
figuration service DescribeDomains action. A domain’s endpoints are also displayed on the domain
dashboard in the Amazon CloudSearch console.
Request Syntax
response = client.search(
cursor='string',
expr='string',
facet='string',
filterQuery='string',
highlight='string',
partial=True|False,
query='string',
queryOptions='string',
queryParser='simple'|'structured'|'lucene'|'dismax',
return='string',
size=123,
sort='string',
start=123
)
Parameters
• cursor (string) – Retrieves a cursor value you can use to page through large
result sets. Use the size parameter to control the number of hits to include in
each response. You can specify either the cursor or start parameter in a
request; they are mutually exclusive. To get the first cursor, set the cursor value
to initial . In subsequent requests, specify the cursor value returned in the
hits section of the response.
For more information, see Paginating Results in the Amazon CloudSearch De-
veloper Guide .
• expr (string) – Defines one or more numeric expressions that can be used to sort
results or specify search or filter criteria. You can also specify expressions as
return fields.
You specify the expressions in JSON using the form
{"EXPRESSIONNAME":"EXPRESSION"} . You can define and use
multiple expressions in a search request. For example:
{"expression1":"_score*rating", "expression2":"(1/rank)*year"}
For information about the variables, operators, and functions you can use in ex-
pressions, see Writing Expressions in the Amazon CloudSearch Developer Guide
.
• facet (string) – Specifies one or more fields for which to get facet in-
formation, and options that control how the facet information is re-
turned. Each specified field must be facet-enabled in the domain con-
figuration. The fields and options are specified in JSON using the form
{"FIELD":{"OPTION":VALUE,"OPTION:"STRING"},"FIELD":{"OPTION":VALUE,"OP
.
You can specify the following faceting options:
– buckets specifies an array of the facet values or ranges to count. Ranges
are specified using the same syntax that you use to search for a range of
406 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
values. For more information, see Searching for a Range of Values in the
Amazon CloudSearch Developer Guide . Buckets are returned in the order
they are specified in the request. The sort and size options are not
valid if you specify buckets .
– size specifies the maximum number of facets to include in the results.
By default, Amazon CloudSearch returns counts for the top 10. The size
parameter is only valid when you specify the sort option; it cannot be
used in conjunction with buckets .
– sort specifies how you want to sort the facets in the results: bucket or
count . Specify bucket to sort alphabetically or numerically by facet
value (in ascending order). Specify count to sort by the facet counts
computed for each facet value (in descending order). To retrieve facet
counts for particular values or ranges of values, use the buckets option
instead of sort .
If no facet options are specified, facet counts are computed for all field values,
the facets are sorted by facet count, and the top 10 facets are returned in the
results.
To count particular buckets of values, use the buckets option. For example,
the following request uses the buckets option to calculate and return facet
counts by decade.
{"year":{"buckets":["[1970,1979]","[1980,1989]","[1990,1999]","[2000,2
To sort facets by facet count, use the count option. For example, the following
request sets the sort option to count to sort the facet values by facet count,
with the facet values that have the most matching documents listed first. Setting
the size option to 3 returns only the top three facet values.
{"year":{"sort":"count","size":3}}
To sort the facets by value, use the bucket option. For example, the following
request sets the sort option to bucket to sort the facet values numerically by
year, with earliest year listed first.
{"year":{"sort":"bucket"}}
For more information, see Getting and Using Facet Information in the Amazon
CloudSearch Developer Guide .
• filterQuery (string) – Specifies a structured query that filters the results of
a search without affecting how the results are scored and sorted. You use
filterQuery in conjunction with the query parameter to filter the docu-
ments that match the constraints specified in the query parameter. Specifying
a filter controls only which matching documents are included in the results, it
has no effect on how they are scored and sorted. The filterQuery parameter
supports the full structured query syntax.
For more information about using filters, see Filtering Matching Documents in
the Amazon CloudSearch Developer Guide .
• highlight (string) – Retrieves highlights for matches in the specified text or
text-array fields. Each specified field must be highlight enabled in the do-
main configuration. The fields and options are specified in JSON using the form
{"FIELD":{"OPTION":VALUE,"OPTION:"STRING"},"FIELD":{"OPTION":VALUE,"OP
.
You can specify the following highlight options:
– format : specifies the format of the data in the text field: text or html
. When data is returned as HTML, all non-alphanumeric characters are
3.1. Services 407
Boto3 Documentation, Release 1.1.4
encoded. The default is html .
– max_phrases : specifies the maximum number of occurrences of the
search term(s) you want to highlight. By default, the first occurrence is
highlighted.
– pre_tag : specifies the string to prepend to an occurrence of a search
term. The default for HTML highlights is lt;emgt; . The default for
text highlights is * .
– post_tag : specifies the string to append to an occurrence of a search
term. The default for HTML highlights is lt;/emgt; . The default for
text highlights is * .
If no highlight options are specified for a field, the returned field text is
treated as HTML and the first match is highlighted with emphasis tags:
lt;emsearch-termlt;/emgt; .
For example, the following request retrieves highlights for the actors and
title fields.
{ "actors": {}, "title": {"format":
"text","max_phrases": 2,"pre_tag":
"**","post_tag": "** "} }
• partial (boolean) – Enables partial results to be returned if one or more index
partitions are unavailable. When your search index is partitioned across mul-
tiple search instances, by default Amazon CloudSearch only returns results if
every partition can be queried. This means that the failure of a single search
instance can result in 5xx (internal server) errors. When you enable partial re-
sults, Amazon CloudSearch returns whatever results are available and includes
the percentage of documents searched in the search results (percent-searched).
This enables you to more gracefully degrade your users’ search experience. For
example, rather than displaying no results, you could display the partial results
and a message indicating that the results might be incomplete due to a temporary
system outage.
• query (string) – [REQUIRED]
Specifies the search criteria for the request. How you specify the search criteria
depends on the query parser used for the request and the parser options specified
in the queryOptions parameter. By default, the simple query parser is
used to process requests. To use the structured , lucene , or dismax
query parser, you must also specify the queryParser parameter.
For more information about specifying search criteria, see Searching Your Data
in the Amazon CloudSearch Developer Guide .
• queryOptions (string) – Configures options for the query
parser specified in the queryParser parameter. You
specify the options in JSON using the following form
{"OPTION1":"VALUE1","OPTION2":VALUE2"..."OPTIONN":"VALUEN"}.
The options you can configure vary according to which parser you use:
– defaultOperator : The default operator used to combine individual
terms in the search string. For example: defaultOperator: ’or’
. For the dismax parser, you specify a percentage that represents the
percentage of terms in the search string (rounded down) that must match,
rather than a default operator. A value of 0% is the equivalent to OR, and
a value of 100% is equivalent to AND. The percentage must be specified
as a value in the range 0-100 followed by the percent (%) symbol. For
example, defaultOperator: 50% . Valid values: and , or , a
percentage in the range 0%-100% (dismax ). Default: and (simple
, structured , lucene ) or 100 (dismax ). Valid for: simple ,
408 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
structured , lucene , and dismax .
– fields : An array of the fields to search when no fields are specified in
a search. If no fields are specified in a search and this option is not spec-
ified, all text and text-array fields are searched. You can specify a weight
for each field to control the relative importance of each field when Amazon
CloudSearch calculates relevance scores. To specify a field weight, append
a caret (^ ) symbol and the weight to the field name. For example, to boost
the importance of the title field over the description field you
could specify: "fields":["title^5","description"] . Valid
values: The name of any configured field and an optional numeric value
greater than zero. Default: All text and text-array fields. Valid for:
simple , structured , lucene , and dismax .
– operators : An array of the operators or special characters you want
to disable for the simple query parser. If you disable the and , or , or
not operators, the corresponding operators (+ , | , - ) have no spe-
cial meaning and are dropped from the search string. Similarly, dis-
abling prefix disables the wildcard operator (* ) and disabling phrase
disables the ability to search for phrases by enclosing phrases in dou-
ble quotes. Disabling precedence disables the ability to control order
of precedence using parentheses. Disabling near disables the ability
to use the ~ operator to perform a sloppy phrase search. Disabling
the fuzzy operator disables the ability to use the ~ operator to per-
form a fuzzy search. escape disables the ability to use a backslash
(\ ) to escape special characters within the search string. Disabling
whitespace is an advanced option that prevents the parser from tokeniz-
ing on whitespace, which can be useful for Vietnamese. (It prevents
Vietnamese words from being split incorrectly.) For example, you could
disable all operators other than the phrase operator to support just sim-
ple term and phrase queries: "operators":["and","not","or",
"prefix"] . Valid values: and , escape , fuzzy , near , not ,
or , phrase , precedence , prefix , whitespace . Default: All
operators and special characters are enabled. Valid for: simple .
– phraseFields : An array of the text or text-array fields you
want to use for phrase searches. When the terms in the search string ap-
pear in close proximity within a field, the field scores higher. You can
specify a weight for each field to boost that score. The phraseSlop op-
tion controls how much the matches can deviate from the search string
and still be boosted. To specify a field weight, append a caret (^ )
symbol and the weight to the field name. For example, to boost phrase
matches in the title field over the abstract field, you could spec-
ify: "phraseFields":["title^3", "plot"] Valid values: The
name of any text or text-array field and an optional numeric value
greater than zero. Default: No fields. If you don’t specify any fields with
phraseFields , proximity scoring is disabled even if phraseSlop is
specified. Valid for: dismax .
– phraseSlop : An integer value that specifies how much matches can de-
viate from the search phrase and still be boosted according to the weights
specified in the phraseFields option; for example, phraseSlop:
2 . You must also specify phraseFields to enable proximity scoring.
Valid values: positive integers. Default: 0. Valid for: dismax .
– explicitPhraseSlop : An integer value that specifies how much
a match can deviate from the search phrase when the phrase is en-
closed in double quotes in the search string. (Phrases that exceed
this proximity distance are not considered a match.) For example, to
3.1. Services 409
Boto3 Documentation, Release 1.1.4
specify a slop of three for dismax phrase queries, you would specify
"explicitPhraseSlop":3 . Valid values: positive integers. De-
fault: 0. Valid for: dismax .
– tieBreaker : When a term in the search string is found in a document’s
field, a score is calculated for that field based on how common the word
is in that field compared to other documents. If the term occurs in
multiple fields within a document, by default only the highest scoring
field contributes to the document’s overall score. You can specify a
tieBreaker value to enable the matches in lower-scoring fields to
contribute to the document’s score. That way, if two documents have the
same max field score for a particular term, the score for the document that
has matches in more fields will be higher. The formula for calculating the
score with a tieBreaker is (max field score) + (tieBreaker)
* (sum of the scores for the rest of the matching
fields) . Set tieBreaker to 0 to disregard all but the highest
scoring field (pure max): "tieBreaker":0 . Set to 1 to sum the scores
from all fields (pure sum): "tieBreaker":1 . Valid values: 0.0 to 1.0.
Default: 0.0. Valid for: dismax .
• queryParser (string) – Specifies which query parser to use to process the
request. If queryParser is not specified, Amazon CloudSearch uses the
simple query parser.
Amazon CloudSearch supports four query parsers:
– simple : perform simple searches of text and text-array
fields. By default, the simple query parser searches all text and
text-array fields. You can specify which fields to search by with
the queryOptions parameter. If you prefix a search term with a plus
sign (+) documents must contain the term to be considered a match.
(This is the default, unless you configure the default operator with the
queryOptions parameter.) You can use the - (NOT), | (OR), and *
(wildcard) operators to exclude particular terms, find results that match
any of the specified terms, or search for a prefix. To search for a phrase
rather than individual terms, enclose the phrase in double quotes. For more
information, see Searching for Text in the Amazon CloudSearch Developer
Guide .
– structured : perform advanced searches by combining multiple ex-
pressions to define the search criteria. You can also search within particu-
lar fields, search for values and ranges of values, and use advanced options
such as term boosting, matchall , and near . For more information,
see Constructing Compound Queries in the Amazon CloudSearch Devel-
oper Guide .
– lucene : search using the Apache Lucene query parser syntax. For more
information, see Apache Lucene Query Parser Syntax .
– dismax : search using the simplified subset of the Apache Lucene query
parser syntax defined by the DisMax query parser. For more information,
see DisMax Query Parser Syntax .
• return (string) – Specifies the field and expression values to include in the re-
sponse. Multiple fields or expressions are specified as a comma-separated list.
By default, a search response includes all return enabled fields (_all_fields
). To return only the document IDs for the matching documents, specify
_no_fields . To retrieve the relevance score calculated for each document,
specify _score .
• size (integer) – Specifies the maximum number of search hits to include in the
response.
410 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• sort (string) – Specifies the fields or custom expressions to use to sort the search
results. Multiple fields or expressions are specified as a comma-separated list.
You must specify the sort direction (asc or desc ) for each field; for example,
year desc,title asc . To use a field to sort results, the field must be
sort-enabled in the domain configuration. Array type fields cannot be used for
sorting. If no sort parameter is specified, results are sorted by their default
relevance scores in descending order: _score desc . You can also sort by
document ID (_id asc ) and version (_version desc ).
For more information, see Sorting Results in the Amazon CloudSearch Devel-
oper Guide .
• start (integer) – Specifies the offset of the first search hit you want to return.
Note that the result set is zero-based; the first result is at index 0. You can
specify either the start or cursor parameter in a request, they are mutually
exclusive.
For more information, see Paginating Results in the Amazon CloudSearch De-
veloper Guide .
Return type dict
Returns
Response Syntax
{
'status': {
'timems': 123,
'rid': 'string'
},
'hits': {
'found': 123,
'start': 123,
'cursor': 'string',
'hit': [
{
'id': 'string',
'fields': {
'string': [
'string',
]
},
'exprs': {
'string': 'string'
},
'highlights': {
'string': 'string'
}
},
]
},
'facets': {
'string': {
'buckets': [
{
'value': 'string',
'count': 123
},
]
}
3.1. Services 411
Boto3 Documentation, Release 1.1.4
}
}
Response Structure
• (dict) –
The result of a Search request. Contains the documents that match the speci-
fied search criteria and any requested fields, highlights, and facet information.
– status (dict) –
The status information returned for the search request.
* timems (integer) –
How long it took to process the request, in milliseconds.
* rid (string) –
The encrypted resource ID for the request.
– hits (dict) –
The documents that match the search criteria.
* found (integer) –
The total number of documents that match the search request.
* start (integer) –
The index of the first matching document.
* cursor (string) –
A cursor that can be used to retrieve the next set of matching docu-
ments when you want to page through a large result set.
* hit (list) –
A document that matches the search request.
· (dict) –
Information about a document that matches the search re-
quest.
· id (string) –
The document ID of a document that matches the search re-
quest.
· fields (dict) –
The fields returned from a document that matches the search
request.
· (string) –
· (list) –
· (string) –
· exprs (dict) –
The expressions returned from a document that matches the
search request.
· (string) –
· (string) –
· highlights (dict) –
The highlights returned from a document that matches the
search request.
· (string) –
· (string) –
412 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– facets (dict) –
The requested facet information.
* (string) –
· (dict) –
A container for the calculated facet values and counts.
· buckets (list) –
A list of the calculated facet values and counts.
· (dict) –
A container for facet information.
· value (string) –
The facet value being counted.
· count (integer) –
The number of hits that contain the facet value in the specified
facet field.
suggest(**kwargs)
Retrieves autocomplete suggestions for a partial query string. You can use suggestions enable you to
display likely matches before users finish typing. In Amazon CloudSearch, suggestions are based on the
contents of a particular text field. When you request suggestions, Amazon CloudSearch finds all of the
documents whose values in the suggester field start with the specified query string. The beginning of the
field must match the query string to be considered a match.
For more information about configuring suggesters and retrieving suggestions, see Getting Suggestions in
the Amazon CloudSearch Developer Guide .
The endpoint for submitting Suggest requests is domain-specific. You submit suggest requests to a
domain’s search endpoint. To get the search endpoint for your domain, use the Amazon CloudSearch
configuration service DescribeDomains action. A domain’s endpoints are also displayed on the do-
main dashboard in the Amazon CloudSearch console.
Request Syntax
response = client.suggest(
query='string',
suggester='string',
size=123
)
Parameters
• query (string) – [REQUIRED]
Specifies the string for which you want to get suggestions.
• suggester (string) – [REQUIRED]
Specifies the name of the suggester to use to find suggested matches.
• size (integer) – Specifies the maximum number of suggestions to return.
Return type dict
Returns
Response Syntax
{
'status': {
'timems': 123,
'rid': 'string'
3.1. Services 413
Boto3 Documentation, Release 1.1.4
},
'suggest': {
'query': 'string',
'found': 123,
'suggestions': [
{
'suggestion': 'string',
'score': 123,
'id': 'string'
},
]
}
}
Response Structure
• (dict) –
Contains the response to a Suggest request.
– status (dict) –
The status of a SuggestRequest . Contains the resource ID (rid )
and how long it took to process the request (timems ).
* timems (integer) –
How long it took to process the request, in milliseconds.
* rid (string) –
The encrypted resource ID for the request.
– suggest (dict) –
Container for the matching search suggestion information.
* query (string) –
The query string specified in the suggest request.
* found (integer) –
The number of documents that were found to match the query string.
* suggestions (list) –
The documents that match the query string.
· (dict) –
An autocomplete suggestion that matches the query string
specified in a SuggestRequest .
· suggestion (string) –
The string that matches the query string specified in the
SuggestRequest .
· score (integer) –
The relevance score of a suggested match.
· id (string) –
The document ID of the suggested document.
upload_documents(**kwargs)
Posts a batch of documents to a search domain for indexing. A document batch is a collection of add
and delete operations that represent the documents you want to add, update, or delete from your domain.
Batches can be described in either JSON or XML. Each item that you want Amazon CloudSearch to
return as a search result (such as a product) is represented as a document. Every document has a unique
ID and one or more fields that contain the data that you want to search and return in results. Individual
414 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
documents cannot contain more than 1 MB of data. The entire batch cannot exceed 5 MB. To get the best
possible upload performance, group add and delete operations in batches that are close the 5 MB limit.
Submitting a large volume of single-document batches can overload a domain’s document service.
The endpoint for submitting UploadDocuments requests is domain-specific. To get the document
endpoint for your domain, use the Amazon CloudSearch configuration service DescribeDomains
action. A domain’s endpoints are also displayed on the domain dashboard in the Amazon CloudSearch
console.
For more information about formatting your data for Amazon CloudSearch, see Preparing Your Data in
the Amazon CloudSearch Developer Guide . For more information about uploading data for indexing, see
Uploading Data in the Amazon CloudSearch Developer Guide .
Request Syntax
response = client.upload_documents(
documents=b'bytes',
contentType='application/json'|'application/xml'
)
Parameters
• documents (bytes) – [REQUIRED]
A batch of documents formatted in JSON or HTML.
• contentType (string) – [REQUIRED]
The format of the batch you are uploading. Amazon CloudSearch supports two
document batch formats:
– application/json
– application/xml
Return type dict
Returns
Response Syntax
{
'status': 'string',
'adds': 123,
'deletes': 123,
'warnings': [
{
'message': 'string'
},
]
}
Response Structure
• (dict) –
Contains the response to an UploadDocuments request.
– status (string) –
The status of an UploadDocumentsRequest .
– adds (integer) –
The number of documents that were added to the search domain.
– deletes (integer) –
The number of documents that were deleted from the search domain.
3.1. Services 415
Boto3 Documentation, Release 1.1.4
– warnings (list) –
Any warnings returned by the document service about the documents be-
ing uploaded.
* (dict) –
A warning returned by the document service when an issue is dis-
covered while processing an upload request.
· message (string) –
The description for a warning returned by the document ser-
vice.
CloudTrail
Table of Contents
• CloudTrail
– Client
Client
class CloudTrail.Client
A low-level client representing AWS CloudTrail:
import boto3
client = boto3.client('cloudtrail')
These are the available methods:
•can_paginate()
•create_trail()
•delete_trail()
•describe_trails()
•generate_presigned_url()
•get_paginator()
•get_trail_status()
•get_waiter()
•lookup_events()
•start_logging()
•stop_logging()
•update_trail()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
create_trail(**kwargs)
From the command line, use create-subscription .
416 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Creates a trail that specifies the settings for delivery of log data to an Amazon S3 bucket.
Request Syntax
response = client.create_trail(
Name='string',
S3BucketName='string',
S3KeyPrefix='string',
SnsTopicName='string',
IncludeGlobalServiceEvents=True|False,
CloudWatchLogsLogGroupArn='string',
CloudWatchLogsRoleArn='string'
)
Parameters
• Name (string) – [REQUIRED]
Specifies the name of the trail.
• S3BucketName (string) – [REQUIRED]
Specifies the name of the Amazon S3 bucket designated for publishing log files.
• S3KeyPrefix (string) – Specifies the Amazon S3 key prefix that precedes the
name of the bucket you have designated for log file delivery.
• SnsTopicName (string) – Specifies the name of the Amazon SNS topic defined
for notification of log file delivery.
• IncludeGlobalServiceEvents (boolean) – Specifies whether the trail is publish-
ing events from global services such as IAM to the log files.
• CloudWatchLogsLogGroupArn (string) – Specifies a log group name using an
Amazon Resource Name (ARN), a unique identifier that represents the log group
to which CloudTrail logs will be delivered. Not required unless you specify
CloudWatchLogsRoleArn.
• CloudWatchLogsRoleArn (string) – Specifies the role for the CloudWatch
Logs endpoint to assume to write to a user’s log group.
Return type dict
Returns
Response Syntax
{
'Name': 'string',
'S3BucketName': 'string',
'S3KeyPrefix': 'string',
'SnsTopicName': 'string',
'IncludeGlobalServiceEvents': True|False,
'CloudWatchLogsLogGroupArn': 'string',
'CloudWatchLogsRoleArn': 'string'
}
Response Structure
• (dict) – Returns the objects or data listed below if successful. Otherwise, returns
an error.
– Name (string) –
Specifies the name of the trail.
– S3BucketName (string) –
Specifies the name of the Amazon S3 bucket designated for publishing log
files.
3.1. Services 417
Boto3 Documentation, Release 1.1.4
– S3KeyPrefix (string) –
Specifies the Amazon S3 key prefix that precedes the name of the bucket
you have designated for log file delivery.
– SnsTopicName (string) –
Specifies the name of the Amazon SNS topic defined for notification of
log file delivery.
– IncludeGlobalServiceEvents (boolean) –
Specifies whether the trail is publishing events from global services such
as IAM to the log files.
– CloudWatchLogsLogGroupArn (string) –
Specifies the Amazon Resource Name (ARN) of the log group to which
CloudTrail logs will be delivered.
– CloudWatchLogsRoleArn (string) –
Specifies the role for the CloudWatch Logs endpoint to assume to write to
a user’s log group.
delete_trail(**kwargs)
Deletes a trail.
Request Syntax
response = client.delete_trail(
Name='string'
)
Parameters Name (string) – [REQUIRED]
The name of a trail to be deleted.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Returns the objects or data listed below if successful. Otherwise, returns an error.
describe_trails(**kwargs)
Retrieves settings for the trail associated with the current region for your account.
Request Syntax
response = client.describe_trails(
trailNameList=[
'string',
]
)
Parameters trailNameList (list) – The trail returned.
• (string) –
Return type dict
418 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'trailList': [
{
'Name': 'string',
'S3BucketName': 'string',
'S3KeyPrefix': 'string',
'SnsTopicName': 'string',
'IncludeGlobalServiceEvents': True|False,
'CloudWatchLogsLogGroupArn': 'string',
'CloudWatchLogsRoleArn': 'string'
},
]
}
Response Structure
• (dict) –
Returns the objects or data listed below if successful. Otherwise, returns an error.
– trailList (list) –
The list of trails.
* (dict) –
The settings for a trail.
· Name (string) –
Name of the trail set by calling CreateTrail .
· S3BucketName (string) –
Name of the Amazon S3 bucket into which CloudTrail deliv-
ers your trail files.
· S3KeyPrefix (string) –
Value of the Amazon S3 prefix.
· SnsTopicName (string) –
Name of the existing Amazon SNS topic that CloudTrail uses
to notify the account owner when new CloudTrail log files
have been delivered.
· IncludeGlobalServiceEvents (boolean) –
Set to True to include AWS API calls from AWS global ser-
vices such as IAM. Otherwise, False .
· CloudWatchLogsLogGroupArn (string) –
Specifies an Amazon Resource Name (ARN), a unique iden-
tifier that represents the log group to which CloudTrail logs
will be delivered.
· CloudWatchLogsRoleArn (string) –
Specifies the role for the CloudWatch Logs endpoint to as-
sume to write to a user’s log group.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
3.1. Services 419
Boto3 Documentation, Release 1.1.4
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_trail_status(**kwargs)
Returns a JSON-formatted list of information about the specified trail. Fields include information on
delivery errors, Amazon SNS and Amazon S3 errors, and start and stop logging times for each trail.
Request Syntax
response = client.get_trail_status(
Name='string'
)
Parameters Name (string) – [REQUIRED]
The name of the trail for which you are requesting the current status.
Return type dict
Returns
Response Syntax
{
'IsLogging': True|False,
'LatestDeliveryError': 'string',
'LatestNotificationError': 'string',
'LatestDeliveryTime': datetime(2015, 1, 1),
'LatestNotificationTime': datetime(2015, 1, 1),
'StartLoggingTime': datetime(2015, 1, 1),
'StopLoggingTime': datetime(2015, 1, 1),
'LatestCloudWatchLogsDeliveryError': 'string',
'LatestCloudWatchLogsDeliveryTime': datetime(2015, 1, 1)
}
Response Structure
• (dict) –
Returns the objects or data listed below if successful. Otherwise, returns an error.
– IsLogging (boolean) –
Whether the CloudTrail is currently logging AWS API calls.
– LatestDeliveryError (string) –
420 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Displays any Amazon S3 error that CloudTrail encountered when attempt-
ing to deliver log files to the designated bucket. For more information see
the topic Error Responses in the Amazon S3 API Reference.
– LatestNotificationError (string) –
Displays any Amazon SNS error that CloudTrail encountered when at-
tempting to send a notification. For more information about Amazon SNS
errors, see the Amazon SNS Developer Guide .
– LatestDeliveryTime (datetime) –
Specifies the date and time that CloudTrail last delivered log files to an
account’s Amazon S3 bucket.
– LatestNotificationTime (datetime) –
Specifies the date and time of the most recent Amazon SNS notification
that CloudTrail has written a new log file to an account’s Amazon S3
bucket.
– StartLoggingTime (datetime) –
Specifies the most recent date and time when CloudTrail started recording
API calls for an AWS account.
– StopLoggingTime (datetime) –
Specifies the most recent date and time when CloudTrail stopped recording
API calls for an AWS account.
– LatestCloudWatchLogsDeliveryError (string) –
Displays any CloudWatch Logs error that CloudTrail encountered when
attempting to deliver logs to CloudWatch Logs.
– LatestCloudWatchLogsDeliveryTime (datetime) –
Displays the most recent date and time when CloudTrail delivered logs to
CloudWatch Logs.
get_waiter(waiter_name)
lookup_events(**kwargs)
Looks up API activity events captured by CloudTrail that create, update, or delete resources in your
account. Events for a region can be looked up for the times in which you had CloudTrail turned on in that
region during the last seven days. Lookup supports five different attributes: time range (defined by a start
time and end time), user name, event name, resource type, and resource name. All attributes are optional.
The maximum number of attributes that can be specified in any one lookup request are time range and
one other attribute. The default number of results returned is 10, with a maximum of 50 possible. The
response includes a token that you can use to get the next page of results. The rate of lookup requests is
limited to one per second per account.
Warning: Events that occurred during the selected time range will not be available for lookup if
CloudTrail logging was not enabled when the events occurred.
Request Syntax
response = client.lookup_events(
LookupAttributes=[
{
'AttributeKey': 'EventId'|'EventName'|'Username'|'ResourceType'|'ResourceName',
'AttributeValue': 'string'
},
],
3.1. Services 421
Boto3 Documentation, Release 1.1.4
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
MaxResults=123,
NextToken='string'
)
Parameters
• LookupAttributes (list) – Contains a list of lookup attributes. Currently the list
can contain only one item.
– (dict) –
Specifies an attribute and value that filter the events returned.
* AttributeKey (string) – [REQUIRED]
Specifies an attribute on which to filter the events returned.
* AttributeValue (string) – [REQUIRED]
Specifies a value for the specified AttributeKey.
• StartTime (datetime) – Specifies that only events that occur after or at the spec-
ified time are returned. If the specified start time is after the specified end time,
an error is returned.
• EndTime (datetime) – Specifies that only events that occur before or at the spec-
ified time are returned. If the specified end time is before the specified start time,
an error is returned.
• MaxResults (integer) – The number of events to return. Possible values are 1
through 50. The default is 10.
• NextToken (string) – The token to use to get the next page of results after a
previous API call. This token must be passed in with the same parameters that
were specified in the the original call. For example, if the original call specified
an AttributeKey of ‘Username’ with a value of ‘root’, the call with NextToken
should include those same parameters.
Return type dict
Returns
Response Syntax
{
'Events': [
{
'EventId': 'string',
'EventName': 'string',
'EventTime': datetime(2015, 1, 1),
'Username': 'string',
'Resources': [
{
'ResourceType': 'string',
'ResourceName': 'string'
},
],
'CloudTrailEvent': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
422 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Contains a response to a LookupEvents action.
– Events (list) –
A list of events returned based on the lookup attributes specified and the
CloudTrail event. The events list is sorted by time. The most recent event
is listed first.
* (dict) –
Contains information about an event that was returned by a lookup
request. The result includes a representation of a CloudTrail event.
· EventId (string) –
The CloudTrail ID of the event returned.
· EventName (string) –
The name of the event returned.
· EventTime (datetime) –
The date and time of the event returned.
· Username (string) –
A user name or role name of the requester that called the API
in the event returned.
· Resources (list) –
A list of resources referenced by the event returned.
· (dict) –
Specifies the type and name of a resource referenced by an
event.
· ResourceType (string) –
The type of a resource referenced by the event returned.
When the resource type cannot be determined, null is re-
turned. Some examples of resource types are: Instance
for EC2, Trail for CloudTrail, DBInstance for RDS, and
AccessKey for IAM. For a list of resource types supported
for event lookup, see Resource Types Supported for Event
Lookup .
· ResourceName (string) –
The name of the resource referenced by the event returned.
These are user-created names whose values will depend on
the environment. For example, the resource name might be
“auto-scaling-test-group” for an Auto Scaling Group or “i-
1234567” for an EC2 Instance.
· CloudTrailEvent (string) –
A JSON string that contains a representation of the event re-
turned.
– NextToken (string) –
The token to use to get the next page of results after a previous API call.
If the token does not appear, there are no more results to return. The
token must be passed in with the same parameters as the previous call.
For example, if the original call specified an AttributeKey of ‘Username’
with a value of ‘root’, the call with NextToken should include those same
parameters.
3.1. Services 423
Boto3 Documentation, Release 1.1.4
start_logging(**kwargs)
Starts the recording of AWS API calls and log file delivery for a trail.
Request Syntax
response = client.start_logging(
Name='string'
)
Parameters Name (string) – [REQUIRED]
The name of the trail for which CloudTrail logs AWS API calls.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Returns the objects or data listed below if successful. Otherwise, returns an error.
stop_logging(**kwargs)
Suspends the recording of AWS API calls and log file delivery for the specified trail. Under most circum-
stances, there is no need to use this action. You can update a trail without stopping it first. This action is
the only way to stop recording.
Request Syntax
response = client.stop_logging(
Name='string'
)
Parameters Name (string) – [REQUIRED]
Communicates to CloudTrail the name of the trail for which to stop logging AWS API
calls.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Returns the objects or data listed below if successful. Otherwise, returns an error.
update_trail(**kwargs)
From the command line, use update-subscription .
Updates the settings that specify delivery of log files. Changes to a trail do not require stopping the
CloudTrail service. Use this action to designate an existing bucket for log delivery. If the existing bucket
has previously been a target for CloudTrail log files, an IAM policy exists for the bucket.
Request Syntax
424 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.update_trail(
Name='string',
S3BucketName='string',
S3KeyPrefix='string',
SnsTopicName='string',
IncludeGlobalServiceEvents=True|False,
CloudWatchLogsLogGroupArn='string',
CloudWatchLogsRoleArn='string'
)
Parameters
• Name (string) – [REQUIRED]
Specifies the name of the trail.
• S3BucketName (string) – Specifies the name of the Amazon S3 bucket desig-
nated for publishing log files.
• S3KeyPrefix (string) – Specifies the Amazon S3 key prefix that precedes the
name of the bucket you have designated for log file delivery.
• SnsTopicName (string) – Specifies the name of the Amazon SNS topic defined
for notification of log file delivery.
• IncludeGlobalServiceEvents (boolean) – Specifies whether the trail is publish-
ing events from global services such as IAM to the log files.
• CloudWatchLogsLogGroupArn (string) – Specifies a log group name using an
Amazon Resource Name (ARN), a unique identifier that represents the log group
to which CloudTrail logs will be delivered. Not required unless you specify
CloudWatchLogsRoleArn.
• CloudWatchLogsRoleArn (string) – Specifies the role for the CloudWatch
Logs endpoint to assume to write to a user’s log group.
Return type dict
Returns
Response Syntax
{
'Name': 'string',
'S3BucketName': 'string',
'S3KeyPrefix': 'string',
'SnsTopicName': 'string',
'IncludeGlobalServiceEvents': True|False,
'CloudWatchLogsLogGroupArn': 'string',
'CloudWatchLogsRoleArn': 'string'
}
Response Structure
• (dict) – Returns the objects or data listed below if successful. Otherwise, returns
an error.
– Name (string) –
Specifies the name of the trail.
– S3BucketName (string) –
Specifies the name of the Amazon S3 bucket designated for publishing log
files.
– S3KeyPrefix (string) –
Specifies the Amazon S3 key prefix that precedes the name of the bucket
you have designated for log file delivery.
3.1. Services 425
Boto3 Documentation, Release 1.1.4
– SnsTopicName (string) –
Specifies the name of the Amazon SNS topic defined for notification of
log file delivery.
– IncludeGlobalServiceEvents (boolean) –
Specifies whether the trail is publishing events from global services such
as IAM to the log files.
– CloudWatchLogsLogGroupArn (string) –
Specifies the Amazon Resource Name (ARN) of the log group to which
CloudTrail logs will be delivered.
– CloudWatchLogsRoleArn (string) –
Specifies the role for the CloudWatch Logs endpoint to assume to write to
a user’s log group.
CloudWatch
Table of Contents
• CloudWatch
– Client
– Paginators
Client
class CloudWatch.Client
A low-level client representing Amazon CloudWatch:
import boto3
client = boto3.client('cloudwatch')
These are the available methods:
•can_paginate()
•delete_alarms()
•describe_alarm_history()
•describe_alarms()
•describe_alarms_for_metric()
•disable_alarm_actions()
•enable_alarm_actions()
•generate_presigned_url()
•get_metric_statistics()
•get_paginator()
•get_waiter()
•list_metrics()
•put_metric_alarm()
•put_metric_data()
•set_alarm_state()
can_paginate(operation_name)
Check if an operation can be paginated.
426 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
delete_alarms(**kwargs)
Deletes all specified alarms. In the event of an error, no alarms are deleted.
Request Syntax
response = client.delete_alarms(
AlarmNames=[
'string',
]
)
Parameters AlarmNames (list) – [REQUIRED]
A list of alarms to be deleted.
• (string) –
Returns None
describe_alarm_history(**kwargs)
Retrieves history for the specified alarm. Filter alarms by date range or item type. If an alarm name is not
specified, Amazon CloudWatch returns histories for all of the owner’s alarms.
Request Syntax
response = client.describe_alarm_history(
AlarmName='string',
HistoryItemType='ConfigurationUpdate'|'StateUpdate'|'Action',
StartDate=datetime(2015, 1, 1),
EndDate=datetime(2015, 1, 1),
MaxRecords=123,
NextToken='string'
)
Parameters
• AlarmName (string) – The name of the alarm.
• HistoryItemType (string) – The type of alarm histories to retrieve.
• StartDate (datetime) – The starting date to retrieve alarm history.
• EndDate (datetime) – The ending date to retrieve alarm history.
• MaxRecords (integer) – The maximum number of alarm history records to re-
trieve.
• NextToken (string) – The token returned by a previous call to indicate that there
is more data available.
Return type dict
Returns
Response Syntax
{
'AlarmHistoryItems': [
{
'AlarmName': 'string',
'Timestamp': datetime(2015, 1, 1),
3.1. Services 427
Boto3 Documentation, Release 1.1.4
'HistoryItemType': 'ConfigurationUpdate'|'StateUpdate'|'Action',
'HistorySummary': 'string',
'HistoryData': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
The output for the DescribeAlarmHistory action.
– AlarmHistoryItems (list) –
A list of alarm histories in JSON format.
* (dict) –
The AlarmHistoryItem data type contains descriptive infor-
mation about the history of a specific alarm. If you call De-
scribeAlarmHistory , Amazon CloudWatch returns this data type as
part of the DescribeAlarmHistoryResult data type.
· AlarmName (string) –
The descriptive name for the alarm.
· Timestamp (datetime) –
The time stamp for the alarm history item. Amazon Cloud-
Watch uses Coordinated Universal Time (UTC) when return-
ing time stamps, which do not accommodate seasonal adjust-
ments such as daylight savings time. For more information,
see Time stamps in the Amazon CloudWatch Developer Guide
.
· HistoryItemType (string) –
The type of alarm history item.
· HistorySummary (string) –
A human-readable summary of the alarm history.
· HistoryData (string) –
Machine-readable data about the alarm in JSON format.
– NextToken (string) –
A string that marks the start of the next batch of returned results.
describe_alarms(**kwargs)
Retrieves alarms with the specified names. If no name is specified, all alarms for the user are returned.
Alarms can be retrieved by using only a prefix for the alarm name, the alarm state, or a prefix for any
action.
Request Syntax
response = client.describe_alarms(
AlarmNames=[
'string',
],
AlarmNamePrefix='string',
StateValue='OK'|'ALARM'|'INSUFFICIENT_DATA',
ActionPrefix='string',
MaxRecords=123,
428 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
NextToken='string'
)
Parameters
• AlarmNames (list) – A list of alarm names to retrieve information for.
– (string) –
• AlarmNamePrefix (string) – The alarm name prefix. AlarmNames cannot be
specified if this parameter is specified.
• StateValue (string) – The state value to be used in matching alarms.
• ActionPrefix (string) – The action name prefix.
• MaxRecords (integer) – The maximum number of alarm descriptions to retrieve.
• NextToken (string) – The token returned by a previous call to indicate that there
is more data available.
Return type dict
Returns
Response Syntax
{
'MetricAlarms': [
{
'AlarmName': 'string',
'AlarmArn': 'string',
'AlarmDescription': 'string',
'AlarmConfigurationUpdatedTimestamp': datetime(2015, 1, 1),
'ActionsEnabled': True|False,
'OKActions': [
'string',
],
'AlarmActions': [
'string',
],
'InsufficientDataActions': [
'string',
],
'StateValue': 'OK'|'ALARM'|'INSUFFICIENT_DATA',
'StateReason': 'string',
'StateReasonData': 'string',
'StateUpdatedTimestamp': datetime(2015, 1, 1),
'MetricName': 'string',
'Namespace': 'string',
'Statistic': 'SampleCount'|'Average'|'Sum'|'Minimum'|'Maximum',
'Dimensions': [
{
'Name': 'string',
'Value': 'string'
},
],
'Period': 123,
'Unit': 'Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'M
'EvaluationPeriods': 123,
'Threshold': 123.0,
'ComparisonOperator': 'GreaterThanOrEqualToThreshold'|'GreaterThanThre
},
],
'NextToken': 'string'
}
3.1. Services 429
Boto3 Documentation, Release 1.1.4
Response Structure
• (dict) –
The output for the DescribeAlarms action.
– MetricAlarms (list) –
A list of information for the specified alarms.
* (dict) –
The MetricAlarm data type represents an alarm. You can use Put-
MetricAlarm to create or update an alarm.
· AlarmName (string) –
The name of the alarm.
· AlarmArn (string) –
The Amazon Resource Name (ARN) of the alarm.
· AlarmDescription (string) –
The description for the alarm.
· AlarmConfigurationUpdatedTimestamp (datetime) –
The time stamp of the last update to the alarm configura-
tion. Amazon CloudWatch uses Coordinated Universal Time
(UTC) when returning time stamps, which do not accommo-
date seasonal adjustments such as daylight savings time. For
more information, see Time stamps in the Amazon Cloud-
Watch Developer Guide .
· ActionsEnabled (boolean) –
Indicates whether actions should be executed during any
changes to the alarm’s state.
· OKActions (list) –
The list of actions to execute when this alarm transitions into
an OK state from any other state. Each action is specified
as an Amazon Resource Number (ARN). Currently the only
actions supported are publishing to an Amazon SNS topic and
triggering an Auto Scaling policy.
· (string) –
· AlarmActions (list) –
The list of actions to execute when this alarm transitions into
an ALARM state from any other state. Each action is specified
as an Amazon Resource Number (ARN). Currently the only
actions supported are publishing to an Amazon SNS topic and
triggering an Auto Scaling policy.
· (string) –
· InsufficientDataActions (list) –
The list of actions to execute when this alarm transitions into
an INSUFFICIENT_DATA state from any other state. Each
action is specified as an Amazon Resource Number (ARN).
Currently the only actions supported are publishing to an
Amazon SNS topic or triggering an Auto Scaling policy.
Warning: The current WSDL lists this attribute as
UnknownActions .
· (string) –
430 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· StateValue (string) –
The state value for the alarm.
· StateReason (string) –
A human-readable explanation for the alarm’s state.
· StateReasonData (string) –
An explanation for the alarm’s state in machine-readable
JSON format
· StateUpdatedTimestamp (datetime) –
The time stamp of the last update to the alarm’s state. Amazon
CloudWatch uses Coordinated Universal Time (UTC) when
returning time stamps, which do not accommodate seasonal
adjustments such as daylight savings time. For more informa-
tion, see Time stamps in the Amazon CloudWatch Developer
Guide .
· MetricName (string) –
The name of the alarm’s metric.
· Namespace (string) –
The namespace of alarm’s associated metric.
· Statistic (string) –
The statistic to apply to the alarm’s associated metric.
· Dimensions (list) –
The list of dimensions associated with the alarm’s associated
metric.
· (dict) –
The Dimension data type further expands on the identity of
a metric using a Name, Value pair.
For examples that use one or more dimensions, see PutMet-
ricData .
· Name (string) –
The name of the dimension.
· Value (string) –
The value representing the dimension measurement
· Period (integer) –
The period in seconds over which the statistic is applied.
· Unit (string) –
The unit of the alarm’s associated metric.
· EvaluationPeriods (integer) –
The number of periods over which data is compared to the
specified threshold.
· Threshold (float) –
The value against which the specified statistic is compared.
· ComparisonOperator (string) –
The arithmetic operation to use when comparing the specified
Statistic and Threshold . The specified Statistic
value is used as the first operand.
3.1. Services 431
Boto3 Documentation, Release 1.1.4
– NextToken (string) –
A string that marks the start of the next batch of returned results.
describe_alarms_for_metric(**kwargs)
Retrieves all alarms for a single metric. Specify a statistic, period, or unit to filter the set of alarms further.
Request Syntax
response = client.describe_alarms_for_metric(
MetricName='string',
Namespace='string',
Statistic='SampleCount'|'Average'|'Sum'|'Minimum'|'Maximum',
Dimensions=[
{
'Name': 'string',
'Value': 'string'
},
],
Period=123,
Unit='Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'Megabytes'|'Gigabytes'
)
Parameters
• MetricName (string) – [REQUIRED]
The name of the metric.
• Namespace (string) – [REQUIRED]
The namespace of the metric.
• Statistic (string) – The statistic for the metric.
• Dimensions (list) – The list of dimensions associated with the metric.
– (dict) –
The Dimension data type further expands on the identity of a metric
using a Name, Value pair.
For examples that use one or more dimensions, see PutMetricData .
* Name (string) – [REQUIRED]
The name of the dimension.
* Value (string) – [REQUIRED]
The value representing the dimension measurement
• Period (integer) – The period in seconds over which the statistic is applied.
• Unit (string) – The unit for the metric.
Return type dict
Returns
Response Syntax
{
'MetricAlarms': [
{
'AlarmName': 'string',
'AlarmArn': 'string',
'AlarmDescription': 'string',
'AlarmConfigurationUpdatedTimestamp': datetime(2015, 1, 1),
'ActionsEnabled': True|False,
'OKActions': [
432 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string',
],
'AlarmActions': [
'string',
],
'InsufficientDataActions': [
'string',
],
'StateValue': 'OK'|'ALARM'|'INSUFFICIENT_DATA',
'StateReason': 'string',
'StateReasonData': 'string',
'StateUpdatedTimestamp': datetime(2015, 1, 1),
'MetricName': 'string',
'Namespace': 'string',
'Statistic': 'SampleCount'|'Average'|'Sum'|'Minimum'|'Maximum',
'Dimensions': [
{
'Name': 'string',
'Value': 'string'
},
],
'Period': 123,
'Unit': 'Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'M
'EvaluationPeriods': 123,
'Threshold': 123.0,
'ComparisonOperator': 'GreaterThanOrEqualToThreshold'|'GreaterThanThre
},
]
}
Response Structure
• (dict) –
The output for the DescribeAlarmsForMetric action.
– MetricAlarms (list) –
A list of information for each alarm with the specified metric.
* (dict) –
The MetricAlarm data type represents an alarm. You can use Put-
MetricAlarm to create or update an alarm.
· AlarmName (string) –
The name of the alarm.
· AlarmArn (string) –
The Amazon Resource Name (ARN) of the alarm.
· AlarmDescription (string) –
The description for the alarm.
· AlarmConfigurationUpdatedTimestamp (datetime) –
The time stamp of the last update to the alarm configura-
tion. Amazon CloudWatch uses Coordinated Universal Time
(UTC) when returning time stamps, which do not accommo-
date seasonal adjustments such as daylight savings time. For
more information, see Time stamps in the Amazon Cloud-
Watch Developer Guide .
· ActionsEnabled (boolean) –
3.1. Services 433
Boto3 Documentation, Release 1.1.4
Indicates whether actions should be executed during any
changes to the alarm’s state.
· OKActions (list) –
The list of actions to execute when this alarm transitions into
an OK state from any other state. Each action is specified
as an Amazon Resource Number (ARN). Currently the only
actions supported are publishing to an Amazon SNS topic and
triggering an Auto Scaling policy.
· (string) –
· AlarmActions (list) –
The list of actions to execute when this alarm transitions into
an ALARM state from any other state. Each action is specified
as an Amazon Resource Number (ARN). Currently the only
actions supported are publishing to an Amazon SNS topic and
triggering an Auto Scaling policy.
· (string) –
· InsufficientDataActions (list) –
The list of actions to execute when this alarm transitions into
an INSUFFICIENT_DATA state from any other state. Each
action is specified as an Amazon Resource Number (ARN).
Currently the only actions supported are publishing to an
Amazon SNS topic or triggering an Auto Scaling policy.
Warning: The current WSDL lists this attribute as
UnknownActions .
· (string) –
· StateValue (string) –
The state value for the alarm.
· StateReason (string) –
A human-readable explanation for the alarm’s state.
· StateReasonData (string) –
An explanation for the alarm’s state in machine-readable
JSON format
· StateUpdatedTimestamp (datetime) –
The time stamp of the last update to the alarm’s state. Amazon
CloudWatch uses Coordinated Universal Time (UTC) when
returning time stamps, which do not accommodate seasonal
adjustments such as daylight savings time. For more informa-
tion, see Time stamps in the Amazon CloudWatch Developer
Guide .
· MetricName (string) –
The name of the alarm’s metric.
· Namespace (string) –
The namespace of alarm’s associated metric.
· Statistic (string) –
The statistic to apply to the alarm’s associated metric.
· Dimensions (list) –
434 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The list of dimensions associated with the alarm’s associated
metric.
· (dict) –
The Dimension data type further expands on the identity of
a metric using a Name, Value pair.
For examples that use one or more dimensions, see PutMet-
ricData .
· Name (string) –
The name of the dimension.
· Value (string) –
The value representing the dimension measurement
· Period (integer) –
The period in seconds over which the statistic is applied.
· Unit (string) –
The unit of the alarm’s associated metric.
· EvaluationPeriods (integer) –
The number of periods over which data is compared to the
specified threshold.
· Threshold (float) –
The value against which the specified statistic is compared.
· ComparisonOperator (string) –
The arithmetic operation to use when comparing the specified
Statistic and Threshold . The specified Statistic
value is used as the first operand.
disable_alarm_actions(**kwargs)
Disables actions for the specified alarms. When an alarm’s actions are disabled the alarm’s state may
change, but none of the alarm’s actions will execute.
Request Syntax
response = client.disable_alarm_actions(
AlarmNames=[
'string',
]
)
Parameters AlarmNames (list) – [REQUIRED]
The names of the alarms to disable actions for.
• (string) –
Returns None
enable_alarm_actions(**kwargs)
Enables actions for the specified alarms.
Request Syntax
response = client.enable_alarm_actions(
AlarmNames=[
'string',
3.1. Services 435
Boto3 Documentation, Release 1.1.4
]
)
Parameters AlarmNames (list) – [REQUIRED]
The names of the alarms to enable actions for.
• (string) –
Returns None
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_metric_statistics(**kwargs)
Gets statistics for the specified metric.
The maximum number of data points returned from a single GetMetricStatistics request is 1,440,
wereas the maximum number of data points that can be queried is 50,850. If you make a request that
generates more than 1,440 data points, Amazon CloudWatch returns an error. In such a case, you can alter
the request by narrowing the specified time range or increasing the specified period. Alternatively, you
can make multiple requests across adjacent time ranges.
Amazon CloudWatch aggregates data points based on the length of the period that you specify. For
example, if you request statistics with a one-minute granularity, Amazon CloudWatch aggregates data
points with time stamps that fall within the same one-minute period. In such a case, the data points
queried can greatly outnumber the data points returned.
The following examples show various statistics allowed by the data point query maximum of 50,850 when
you call GetMetricStatistics on Amazon EC2 instances with detailed (one-minute) monitoring
enabled:
•Statistics for up to 400 instances for a span of one hour
•Statistics for up to 35 instances over a span of 24 hours
•Statistics for up to 2 instances over a span of 2 weeks
For information about the namespace, metric names, and dimensions that other Amazon Web Services
products use to send metrics to Cloudwatch, go to Amazon CloudWatch Metrics, Namespaces, and Di-
mensions Reference in the Amazon CloudWatch Developer Guide .
Request Syntax
response = client.get_metric_statistics(
Namespace='string',
MetricName='string',
Dimensions=[
{
'Name': 'string',
'Value': 'string'
},
],
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
Period=123,
436 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Statistics=[
'SampleCount'|'Average'|'Sum'|'Minimum'|'Maximum',
],
Unit='Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'Megabytes'|'Gigabytes'
)
Parameters
• Namespace (string) – [REQUIRED]
The namespace of the metric, with or without spaces.
• MetricName (string) – [REQUIRED]
The name of the metric, with or without spaces.
• Dimensions (list) – A list of dimensions describing qualities of the metric.
– (dict) –
The Dimension data type further expands on the identity of a metric
using a Name, Value pair.
For examples that use one or more dimensions, see PutMetricData .
* Name (string) – [REQUIRED]
The name of the dimension.
* Value (string) – [REQUIRED]
The value representing the dimension measurement
• StartTime (datetime) – [REQUIRED]
The time stamp to use for determining the first datapoint to return. The value
specified is inclusive; results include datapoints with the time stamp specified.
• EndTime (datetime) – [REQUIRED]
The time stamp to use for determining the last datapoint to return. The value
specified is exclusive; results will include datapoints up to the time stamp speci-
fied.
• Period (integer) – [REQUIRED]
The granularity, in seconds, of the returned datapoints. Period must be at least
60 seconds and must be a multiple of 60. The default value is 60.
• Statistics (list) – [REQUIRED]
The metric statistics to return. For information about specific statistics returned
by GetMetricStatistics, go to Statistics in the Amazon CloudWatch Developer
Guide .
Valid Values: Average | Sum | SampleCount | Maximum |
Minimum
– (string) –
• Unit (string) – The unit for the metric.
Return type dict
Returns
Response Syntax
{
'Label': 'string',
'Datapoints': [
{
'Timestamp': datetime(2015, 1, 1),
'SampleCount': 123.0,
3.1. Services 437
Boto3 Documentation, Release 1.1.4
'Average': 123.0,
'Sum': 123.0,
'Minimum': 123.0,
'Maximum': 123.0,
'Unit': 'Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'M
},
]
}
Response Structure
• (dict) –
The output for the GetMetricStatistics action.
– Label (string) –
A label describing the specified metric.
– Datapoints (list) –
The datapoints for the specified metric.
* (dict) –
The Datapoint data type encapsulates the statistical data that
Amazon CloudWatch computes from metric data.
· Timestamp (datetime) –
The time stamp used for the datapoint. Amazon Cloud-
Watch uses Coordinated Universal Time (UTC) when return-
ing time stamps, which do not accommodate seasonal adjust-
ments such as daylight savings time. For more information,
see Time stamps in the Amazon CloudWatch Developer Guide
.
· SampleCount (float) –
The number of metric values that contributed to the aggregate
value of this datapoint.
· Average (float) –
The average of metric values that correspond to the datapoint.
· Sum (float) –
The sum of metric values used for the datapoint.
· Minimum (float) –
The minimum metric value used for the datapoint.
· Maximum (float) –
The maximum of the metric value used for the datapoint.
· Unit (string) –
The standard unit used for the datapoint.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
438 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
list_metrics(**kwargs)
Returns a list of valid metrics stored for the AWS account owner. Returned metrics can be used with
GetMetricStatistics to obtain statistical data for a given metric.
Request Syntax
response = client.list_metrics(
Namespace='string',
MetricName='string',
Dimensions=[
{
'Name': 'string',
'Value': 'string'
},
],
NextToken='string'
)
Parameters
• Namespace (string) – The namespace to filter against.
• MetricName (string) – The name of the metric to filter against.
• Dimensions (list) – A list of dimensions to filter against.
– (dict) –
The DimensionFilter data type is used to filter ListMetrics results.
* Name (string) – [REQUIRED]
The dimension name to be matched.
* Value (string) –
The value of the dimension to be matched.
• NextToken (string) – The token returned by a previous call to indicate that there
is more data available.
Return type dict
Returns
Response Syntax
{
'Metrics': [
{
'Namespace': 'string',
'MetricName': 'string',
'Dimensions': [
{
'Name': 'string',
'Value': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
3.1. Services 439
Boto3 Documentation, Release 1.1.4
• (dict) –
The output for the ListMetrics action.
– Metrics (list) –
A list of metrics used to generate statistics for an AWS account.
* (dict) –
The Metric data type contains information about a specific metric.
If you call ListMetrics , Amazon CloudWatch returns information
contained by this data type.
The example in the Examples section publishes two metrics named
buffers and latency. Both metrics are in the examples namespace.
Both metrics have two dimensions, InstanceID and InstanceType.
· Namespace (string) –
The namespace of the metric.
· MetricName (string) –
The name of the metric.
· Dimensions (list) –
A list of dimensions associated with the metric.
· (dict) –
The Dimension data type further expands on the identity of
a metric using a Name, Value pair.
For examples that use one or more dimensions, see PutMet-
ricData .
· Name (string) –
The name of the dimension.
· Value (string) –
The value representing the dimension measurement
– NextToken (string) –
A string that marks the start of the next batch of returned results.
put_metric_alarm(**kwargs)
Creates or updates an alarm and associates it with the specified Amazon CloudWatch metric. Optionally,
this operation can associate one or more Amazon Simple Notification Service resources with the alarm.
When this operation creates an alarm, the alarm state is immediately set to INSUFFICIENT_DATA
. The alarm is evaluated and its StateValue is set appropriately. Any actions associated with the
StateValue is then executed.
Request Syntax
response = client.put_metric_alarm(
AlarmName='string',
AlarmDescription='string',
ActionsEnabled=True|False,
OKActions=[
'string',
],
AlarmActions=[
'string',
],
InsufficientDataActions=[
440 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string',
],
MetricName='string',
Namespace='string',
Statistic='SampleCount'|'Average'|'Sum'|'Minimum'|'Maximum',
Dimensions=[
{
'Name': 'string',
'Value': 'string'
},
],
Period=123,
Unit='Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'Megabytes'|'Gigabytes'
EvaluationPeriods=123,
Threshold=123.0,
ComparisonOperator='GreaterThanOrEqualToThreshold'|'GreaterThanThreshold'|'LessThanThres
)
Parameters
• AlarmName (string) – [REQUIRED]
The descriptive name for the alarm. This name must be unique within the user’s
AWS account
• AlarmDescription (string) – The description for the alarm.
• ActionsEnabled (boolean) – Indicates whether or not actions should be exe-
cuted during any changes to the alarm’s state.
• OKActions (list) – The list of actions to execute when this alarm transitions into
an OK state from any other state. Each action is specified as an Amazon Resource
Number (ARN). Currently the only action supported is publishing to an Amazon
SNS topic or an Amazon Auto Scaling policy.
– (string) –
• AlarmActions (list) – The list of actions to execute when this alarm transitions
into an ALARM state from any other state. Each action is specified as an Amazon
Resource Number (ARN). Currently the only action supported is publishing to
an Amazon SNS topic or an Amazon Auto Scaling policy.
– (string) –
• InsufficientDataActions (list) – The list of actions to execute when this alarm
transitions into an INSUFFICIENT_DATA state from any other state. Each
action is specified as an Amazon Resource Number (ARN). Currently the only
action supported is publishing to an Amazon SNS topic or an Amazon Auto
Scaling policy.
– (string) –
• MetricName (string) – [REQUIRED]
The name for the alarm’s associated metric.
• Namespace (string) – [REQUIRED]
The namespace for the alarm’s associated metric.
• Statistic (string) – [REQUIRED]
The statistic to apply to the alarm’s associated metric.
• Dimensions (list) – The dimensions for the alarm’s associated metric.
– (dict) –
The Dimension data type further expands on the identity of a metric
using a Name, Value pair.
For examples that use one or more dimensions, see PutMetricData .
3.1. Services 441
Boto3 Documentation, Release 1.1.4
* Name (string) – [REQUIRED]
The name of the dimension.
* Value (string) – [REQUIRED]
The value representing the dimension measurement
• Period (integer) – [REQUIRED]
The period in seconds over which the specified statistic is applied.
• Unit (string) – The unit for the alarm’s associated metric.
• EvaluationPeriods (integer) – [REQUIRED]
The number of periods over which data is compared to the specified threshold.
• Threshold (float) – [REQUIRED]
The value against which the specified statistic is compared.
• ComparisonOperator (string) – [REQUIRED]
The arithmetic operation to use when comparing the specified Statistic and
Threshold . The specified Statistic value is used as the first operand.
Returns None
put_metric_data(**kwargs)
Publishes metric data points to Amazon CloudWatch. Amazon Cloudwatch associates the data points
with the specified metric. If the specified metric does not exist, Amazon CloudWatch creates the metric.
It can take up to fifteen minutes for a new metric to appear in calls to the ListMetrics action.
The size of a PutMetricDatarequest is limited to 8 KB for HTTP GET requests and 40 KB for HTTP
POST requests.
Warning: Although the Value parameter accepts numbers of type Double , Amazon CloudWatch
truncates values with very large exponents. Values with base-10 exponents greater than 126 (1 x
10^126) are truncated. Likewise, values with base-10 exponents less than -130 (1 x 10^-130) are also
truncated.
Data that is timestamped 24 hours or more in the past may take in excess of 48 hours to become available
from submission time using GetMetricStatistics .
Request Syntax
response = client.put_metric_data(
Namespace='string',
MetricData=[
{
'MetricName': 'string',
'Dimensions': [
{
'Name': 'string',
'Value': 'string'
},
],
'Timestamp': datetime(2015, 1, 1),
'Value': 123.0,
'StatisticValues': {
'SampleCount': 123.0,
'Sum': 123.0,
'Minimum': 123.0,
'Maximum': 123.0
},
'Unit': 'Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'Megabytes'|
442 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
]
)
Parameters
• Namespace (string) – [REQUIRED]
The namespace for the metric data.
• MetricData (list) – [REQUIRED]
A list of data describing the metric.
– (dict) –
The MetricDatum data type encapsulates the information sent with Put-
MetricData to either create a new metric or add new values to be aggre-
gated into an existing metric.
* MetricName (string) – [REQUIRED]
The name of the metric.
* Dimensions (list) –
A list of dimensions associated with the metric. Note, when using
the Dimensions value in a query, you need to append .member.N to
it (e.g., Dimensions.member.N).
· (dict) –
The Dimension data type further expands on the identity of
a metric using a Name, Value pair.
For examples that use one or more dimensions, see PutMet-
ricData .
· Name (string) – [REQUIRED]
The name of the dimension.
· Value (string) – [REQUIRED]
The value representing the dimension measurement
* Timestamp (datetime) –
The time stamp used for the metric. If not specified, the default
value is set to the time the metric data was received. Amazon Cloud-
Watch uses Coordinated Universal Time (UTC) when returning time
stamps, which do not accommodate seasonal adjustments such as
daylight savings time. For more information, see Time stamps in
the Amazon CloudWatch Developer Guide .
* Value (float) –
The value for the metric.
Warning: Although the Value parameter accepts numbers of
type Double , Amazon CloudWatch truncates values with very
large exponents. Values with base-10 exponents greater than 126
(1 x 10^126) are truncated. Likewise, values with base-10 expo-
nents less than -130 (1 x 10^-130) are also truncated.
* StatisticValues (dict) –
A set of statistical values describing the metric.
· SampleCount (float) – [REQUIRED]
The number of samples used for the statistic set.
3.1. Services 443
Boto3 Documentation, Release 1.1.4
· Sum (float) – [REQUIRED]
The sum of values for the sample set.
· Minimum (float) – [REQUIRED]
The minimum value of the sample set.
· Maximum (float) – [REQUIRED]
The maximum value of the sample set.
* Unit (string) –
The unit of the metric.
Returns None
set_alarm_state(**kwargs)
Temporarily sets the state of an alarm. When the updated StateValue differs from the previous value,
the action configured for the appropriate state is invoked. This is not a permanent change. The next
periodic alarm check (in about a minute) will set the alarm to its actual state.
Request Syntax
response = client.set_alarm_state(
AlarmName='string',
StateValue='OK'|'ALARM'|'INSUFFICIENT_DATA',
StateReason='string',
StateReasonData='string'
)
Parameters
• AlarmName (string) – [REQUIRED]
The descriptive name for the alarm. This name must be unique within the user’s
AWS account. The maximum length is 255 characters.
• StateValue (string) – [REQUIRED]
The value of the state.
• StateReason (string) – [REQUIRED]
The reason that this alarm is set to this specific state (in human-readable text
format)
• StateReasonData (string) – The reason that this alarm is set to this specific state
(in machine-readable JSON format)
Returns None
Paginators
The available paginators are:
• CloudWatch.Paginator.DescribeAlarmHistory
• CloudWatch.Paginator.DescribeAlarms
• CloudWatch.Paginator.ListMetrics
class CloudWatch.Paginator.DescribeAlarmHistory
paginator = client.get_paginator('describe_alarm_history')
444 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudWatch.Client.describe_alarm_history().
Request Syntax
response_iterator = paginator.paginate(
AlarmName='string',
HistoryItemType='ConfigurationUpdate'|'StateUpdate'|'Action',
StartDate=datetime(2015, 1, 1),
EndDate=datetime(2015, 1, 1),
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• AlarmName (string) – The name of the alarm.
• HistoryItemType (string) – The type of alarm histories to retrieve.
• StartDate (datetime) – The starting date to retrieve alarm history.
• EndDate (datetime) – The ending date to retrieve alarm history.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'AlarmHistoryItems': [
{
'AlarmName': 'string',
'Timestamp': datetime(2015, 1, 1),
'HistoryItemType': 'ConfigurationUpdate'|'StateUpdate'|'Action',
'HistorySummary': 'string',
'HistoryData': 'string'
},
],
Response Structure
• (dict) –
The output for the DescribeAlarmHistory action.
3.1. Services 445
Boto3 Documentation, Release 1.1.4
– AlarmHistoryItems (list) –
A list of alarm histories in JSON format.
* (dict) –
The AlarmHistoryItem data type contains descriptive infor-
mation about the history of a specific alarm. If you call De-
scribeAlarmHistory , Amazon CloudWatch returns this data type as
part of the DescribeAlarmHistoryResult data type.
· AlarmName (string) –
The descriptive name for the alarm.
· Timestamp (datetime) –
The time stamp for the alarm history item. Amazon Cloud-
Watch uses Coordinated Universal Time (UTC) when return-
ing time stamps, which do not accommodate seasonal adjust-
ments such as daylight savings time. For more information,
see Time stamps in the Amazon CloudWatch Developer Guide
.
· HistoryItemType (string) –
The type of alarm history item.
· HistorySummary (string) –
A human-readable summary of the alarm history.
· HistoryData (string) –
Machine-readable data about the alarm in JSON format.
class CloudWatch.Paginator.DescribeAlarms
paginator = client.get_paginator('describe_alarms')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudWatch.Client.describe_alarms().
Request Syntax
response_iterator = paginator.paginate(
AlarmNames=[
'string',
],
AlarmNamePrefix='string',
StateValue='OK'|'ALARM'|'INSUFFICIENT_DATA',
ActionPrefix='string',
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• AlarmNames (list) – A list of alarm names to retrieve information for.
– (string) –
• AlarmNamePrefix (string) – The alarm name prefix. AlarmNames cannot be
specified if this parameter is specified.
446 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• StateValue (string) – The state value to be used in matching alarms.
• ActionPrefix (string) – The action name prefix.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'MetricAlarms': [
{
'AlarmName': 'string',
'AlarmArn': 'string',
'AlarmDescription': 'string',
'AlarmConfigurationUpdatedTimestamp': datetime(2015, 1, 1),
'ActionsEnabled': True|False,
'OKActions': [
'string',
],
'AlarmActions': [
'string',
],
'InsufficientDataActions': [
'string',
],
'StateValue': 'OK'|'ALARM'|'INSUFFICIENT_DATA',
'StateReason': 'string',
'StateReasonData': 'string',
'StateUpdatedTimestamp': datetime(2015, 1, 1),
'MetricName': 'string',
'Namespace': 'string',
'Statistic': 'SampleCount'|'Average'|'Sum'|'Minimum'|'Maximum',
'Dimensions': [
{
'Name': 'string',
'Value': 'string'
},
],
'Period': 123,
'Unit': 'Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'M
'EvaluationPeriods': 123,
'Threshold': 123.0,
'ComparisonOperator': 'GreaterThanOrEqualToThreshold'|'GreaterThanThre
},
],
3.1. Services 447
Boto3 Documentation, Release 1.1.4
Response Structure
• (dict) –
The output for the DescribeAlarms action.
– MetricAlarms (list) –
A list of information for the specified alarms.
* (dict) –
The MetricAlarm data type represents an alarm. You can use Put-
MetricAlarm to create or update an alarm.
· AlarmName (string) –
The name of the alarm.
· AlarmArn (string) –
The Amazon Resource Name (ARN) of the alarm.
· AlarmDescription (string) –
The description for the alarm.
· AlarmConfigurationUpdatedTimestamp (datetime) –
The time stamp of the last update to the alarm configura-
tion. Amazon CloudWatch uses Coordinated Universal Time
(UTC) when returning time stamps, which do not accommo-
date seasonal adjustments such as daylight savings time. For
more information, see Time stamps in the Amazon Cloud-
Watch Developer Guide .
· ActionsEnabled (boolean) –
Indicates whether actions should be executed during any
changes to the alarm’s state.
· OKActions (list) –
The list of actions to execute when this alarm transitions into
an OK state from any other state. Each action is specified
as an Amazon Resource Number (ARN). Currently the only
actions supported are publishing to an Amazon SNS topic and
triggering an Auto Scaling policy.
· (string) –
· AlarmActions (list) –
The list of actions to execute when this alarm transitions into
an ALARM state from any other state. Each action is specified
as an Amazon Resource Number (ARN). Currently the only
actions supported are publishing to an Amazon SNS topic and
triggering an Auto Scaling policy.
· (string) –
· InsufficientDataActions (list) –
The list of actions to execute when this alarm transitions into
an INSUFFICIENT_DATA state from any other state. Each
action is specified as an Amazon Resource Number (ARN).
Currently the only actions supported are publishing to an
Amazon SNS topic or triggering an Auto Scaling policy.
448 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Warning: The current WSDL lists this attribute as
UnknownActions .
· (string) –
· StateValue (string) –
The state value for the alarm.
· StateReason (string) –
A human-readable explanation for the alarm’s state.
· StateReasonData (string) –
An explanation for the alarm’s state in machine-readable
JSON format
· StateUpdatedTimestamp (datetime) –
The time stamp of the last update to the alarm’s state. Amazon
CloudWatch uses Coordinated Universal Time (UTC) when
returning time stamps, which do not accommodate seasonal
adjustments such as daylight savings time. For more informa-
tion, see Time stamps in the Amazon CloudWatch Developer
Guide .
· MetricName (string) –
The name of the alarm’s metric.
· Namespace (string) –
The namespace of alarm’s associated metric.
· Statistic (string) –
The statistic to apply to the alarm’s associated metric.
· Dimensions (list) –
The list of dimensions associated with the alarm’s associated
metric.
· (dict) –
The Dimension data type further expands on the identity of
a metric using a Name, Value pair.
For examples that use one or more dimensions, see PutMet-
ricData .
· Name (string) –
The name of the dimension.
· Value (string) –
The value representing the dimension measurement
· Period (integer) –
The period in seconds over which the statistic is applied.
· Unit (string) –
The unit of the alarm’s associated metric.
· EvaluationPeriods (integer) –
The number of periods over which data is compared to the
specified threshold.
· Threshold (float) –
The value against which the specified statistic is compared.
3.1. Services 449
Boto3 Documentation, Release 1.1.4
· ComparisonOperator (string) –
The arithmetic operation to use when comparing the specified
Statistic and Threshold . The specified Statistic
value is used as the first operand.
class CloudWatch.Paginator.ListMetrics
paginator = client.get_paginator('list_metrics')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
CloudWatch.Client.list_metrics().
Request Syntax
response_iterator = paginator.paginate(
Namespace='string',
MetricName='string',
Dimensions=[
{
'Name': 'string',
'Value': 'string'
},
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• Namespace (string) – The namespace to filter against.
• MetricName (string) – The name of the metric to filter against.
• Dimensions (list) – A list of dimensions to filter against.
– (dict) –
The DimensionFilter data type is used to filter ListMetrics results.
* Name (string) – [REQUIRED]
The dimension name to be matched.
* Value (string) –
The value of the dimension to be matched.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
450 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'Metrics': [
{
'Namespace': 'string',
'MetricName': 'string',
'Dimensions': [
{
'Name': 'string',
'Value': 'string'
},
]
},
],
Response Structure
• (dict) –
The output for the ListMetrics action.
– Metrics (list) –
A list of metrics used to generate statistics for an AWS account.
* (dict) –
The Metric data type contains information about a specific metric.
If you call ListMetrics , Amazon CloudWatch returns information
contained by this data type.
The example in the Examples section publishes two metrics named
buffers and latency. Both metrics are in the examples namespace.
Both metrics have two dimensions, InstanceID and InstanceType.
· Namespace (string) –
The namespace of the metric.
· MetricName (string) –
The name of the metric.
· Dimensions (list) –
A list of dimensions associated with the metric.
· (dict) –
The Dimension data type further expands on the identity of
a metric using a Name, Value pair.
For examples that use one or more dimensions, see PutMet-
ricData .
· Name (string) –
The name of the dimension.
· Value (string) –
The value representing the dimension measurement
3.1. Services 451
Boto3 Documentation, Release 1.1.4
CodeCommit
Table of Contents
• CodeCommit
– Client
Client
class CodeCommit.Client
A low-level client representing AWS CodeCommit:
import boto3
client = boto3.client('codecommit')
These are the available methods:
•batch_get_repositories()
•can_paginate()
•create_branch()
•create_repository()
•delete_repository()
•generate_presigned_url()
•get_branch()
•get_paginator()
•get_repository()
•get_waiter()
•list_branches()
•list_repositories()
•update_default_branch()
•update_repository_description()
•update_repository_name()
batch_get_repositories(**kwargs)
Gets information about one or more repositories.
Note: The description field for a repository accepts all HTML characters and all valid Unicode characters.
Applications that do not HTML-encode the description and display it in a web page could expose users
to potentially malicious code. Make sure that you HTML-encode the description field in any application
that uses this API to display the repository description on a web page.
Request Syntax
response = client.batch_get_repositories(
repositoryNames=[
'string',
]
)
Parameters repositoryNames (list) – [REQUIRED]
The names of the repositories to get information about.
452 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• (string) – Repository name is restricted to alphanumeric characters (a-z, A-Z,
0-9), ”.”, “_”, and “-”. Additionally, the suffix ”.git” is prohibited in a repository
name.
Return type dict
Returns
Response Syntax
{
'repositories': [
{
'accountId': 'string',
'repositoryId': 'string',
'repositoryName': 'string',
'repositoryDescription': 'string',
'defaultBranch': 'string',
'lastModifiedDate': datetime(2015, 1, 1),
'creationDate': datetime(2015, 1, 1),
'cloneUrlHttp': 'string',
'cloneUrlSsh': 'string',
'Arn': 'string'
},
],
'repositoriesNotFound': [
'string',
]
}
Response Structure
• (dict) –
Represents the output of a batch get repositories operation.
– repositories (list) –
A list of repositories returned by the batch get repositories operation.
* (dict) –
Information about a repository.
· accountId (string) –
The ID of the AWS account associated with the repository.
· repositoryId (string) –
The ID of the repository.
· repositoryName (string) –
The repository’s name.
· repositoryDescription (string) –
A comment or description about the repository.
· defaultBranch (string) –
The repository’s default branch name.
· lastModifiedDate (datetime) –
The date and time the repository was last modified, in times-
tamp format.
· creationDate (datetime) –
The date and time the repository was created, in timestamp
format.
3.1. Services 453
Boto3 Documentation, Release 1.1.4
· cloneUrlHttp (string) –
The URL to use for cloning the repository over HTTPS.
· cloneUrlSsh (string) –
The URL to use for cloning the repository over SSH.
· Arn (string) –
The Amazon Resource Name (ARN) of the repository.
– repositoriesNotFound (list) –
Returns a list of repository names for which information could not be
found.
* (string) – Repository name is restricted to alphanumeric characters
(a-z, A-Z, 0-9), ”.”, “_”, and “-”. Additionally, the suffix ”.git” is
prohibited in a repository name.
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
create_branch(**kwargs)
Creates a new branch in a repository and points the branch to a commit.
Note: Calling the create branch operation does not set a repository’s default branch. To do this, call the
update default branch operation.
Request Syntax
response = client.create_branch(
repositoryName='string',
branchName='string',
commitId='string'
)
Parameters
• repositoryName (string) – [REQUIRED]
The name of the repository in which you want to create the new branch.
• branchName (string) – [REQUIRED]
The name of the new branch to create.
• commitId (string) – [REQUIRED]
The ID of the commit to point the new branch to.
Note: If this commit ID is not specified, the new branch will point to the commit
that is pointed to by the repository’s default branch.
Returns None
create_repository(**kwargs)
Creates a new, empty repository.
Request Syntax
454 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.create_repository(
repositoryName='string',
repositoryDescription='string'
)
Parameters
• repositoryName (string) – [REQUIRED]
The name of the new repository to be created.
Note: The repository name must be unique across the calling AWS account. In
addition, repository names are restricted to alphanumeric characters. The suffix
”.git” is prohibited.
• repositoryDescription (string) – A comment or description about the new
repository.
Return type dict
Returns
Response Syntax
{
'repositoryMetadata': {
'accountId': 'string',
'repositoryId': 'string',
'repositoryName': 'string',
'repositoryDescription': 'string',
'defaultBranch': 'string',
'lastModifiedDate': datetime(2015, 1, 1),
'creationDate': datetime(2015, 1, 1),
'cloneUrlHttp': 'string',
'cloneUrlSsh': 'string',
'Arn': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a create repository operation.
– repositoryMetadata (dict) –
Information about the newly created repository.
* accountId (string) –
The ID of the AWS account associated with the repository.
* repositoryId (string) –
The ID of the repository.
* repositoryName (string) –
The repository’s name.
* repositoryDescription (string) –
A comment or description about the repository.
* defaultBranch (string) –
The repository’s default branch name.
* lastModifiedDate (datetime) –
3.1. Services 455
Boto3 Documentation, Release 1.1.4
The date and time the repository was last modified, in timestamp
format.
* creationDate (datetime) –
The date and time the repository was created, in timestamp format.
* cloneUrlHttp (string) –
The URL to use for cloning the repository over HTTPS.
* cloneUrlSsh (string) –
The URL to use for cloning the repository over SSH.
* Arn (string) –
The Amazon Resource Name (ARN) of the repository.
delete_repository(**kwargs)
Deletes a repository. If a specified repository was already deleted, a null repository ID will be returned.
Warning: Deleting a repository also deletes all associated objects and metadata. After a repository
is deleted, all future push calls to the deleted repository will fail.
Request Syntax
response = client.delete_repository(
repositoryName='string'
)
Parameters repositoryName (string) – [REQUIRED]
The name of the repository to delete.
Return type dict
Returns
Response Syntax
{
'repositoryId': 'string'
}
Response Structure
• (dict) –
Represents the output of a delete repository operation.
– repositoryId (string) –
The ID of the repository that was deleted.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
456 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
get_branch(**kwargs)
Retrieves information about a repository branch, including its name and the last commit ID.
Request Syntax
response = client.get_branch(
repositoryName='string',
branchName='string'
)
Parameters
• repositoryName (string) – Repository name is restricted to alphanumeric char-
acters (a-z, A-Z, 0-9), ”.”, “_”, and “-”. Additionally, the suffix ”.git” is prohib-
ited in a repository name.
• branchName (string) – The name of the branch for which you want to retrieve
information.
Return type dict
Returns
Response Syntax
{
'branch': {
'branchName': 'string',
'commitId': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a get branch operation.
– branch (dict) –
The name of the branch.
* branchName (string) –
The name of the branch.
* commitId (string) –
The ID of the last commit made to the branch.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_repository(**kwargs)
Gets information about a repository.
Note: The description field for a repository accepts all HTML characters and all valid Unicode characters.
Applications that do not HTML-encode the description and display it in a web page could expose users
3.1. Services 457
Boto3 Documentation, Release 1.1.4
to potentially malicious code. Make sure that you HTML-encode the description field in any application
that uses this API to display the repository description on a web page.
Request Syntax
response = client.get_repository(
repositoryName='string'
)
Parameters repositoryName (string) – [REQUIRED]
The name of the repository to get information about.
Return type dict
Returns
Response Syntax
{
'repositoryMetadata': {
'accountId': 'string',
'repositoryId': 'string',
'repositoryName': 'string',
'repositoryDescription': 'string',
'defaultBranch': 'string',
'lastModifiedDate': datetime(2015, 1, 1),
'creationDate': datetime(2015, 1, 1),
'cloneUrlHttp': 'string',
'cloneUrlSsh': 'string',
'Arn': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a get repository operation.
– repositoryMetadata (dict) –
Information about the repository.
* accountId (string) –
The ID of the AWS account associated with the repository.
* repositoryId (string) –
The ID of the repository.
* repositoryName (string) –
The repository’s name.
* repositoryDescription (string) –
A comment or description about the repository.
* defaultBranch (string) –
The repository’s default branch name.
* lastModifiedDate (datetime) –
The date and time the repository was last modified, in timestamp
format.
* creationDate (datetime) –
The date and time the repository was created, in timestamp format.
458 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* cloneUrlHttp (string) –
The URL to use for cloning the repository over HTTPS.
* cloneUrlSsh (string) –
The URL to use for cloning the repository over SSH.
* Arn (string) –
The Amazon Resource Name (ARN) of the repository.
get_waiter(waiter_name)
list_branches(**kwargs)
Gets information about one or more branches in a repository.
Request Syntax
response = client.list_branches(
repositoryName='string',
nextToken='string'
)
Parameters
• repositoryName (string) – [REQUIRED]
The name of the repository that contains the branches.
• nextToken (string) – An enumeration token that allows the operation to batch
the results.
Return type dict
Returns
Response Syntax
{
'branches': [
'string',
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list branches operation.
– branches (list) –
The list of branch names.
* (string) –
– nextToken (string) –
An enumeration token that returns the batch of the results.
list_repositories(**kwargs)
Gets information about one or more repositories.
Request Syntax
response = client.list_repositories(
nextToken='string',
sortBy='repositoryName'|'lastModifiedDate',
3.1. Services 459
Boto3 Documentation, Release 1.1.4
order='ascending'|'descending'
)
Parameters
• nextToken (string) – An enumeration token that allows the operation to batch
the results of the operation. Batch sizes are 1,000 for list repository operations.
When the client sends the token back to AWS CodeCommit, another page of
1,000 records is retrieved.
• sortBy (string) – The criteria used to sort the results of a list repositories opera-
tion.
• order (string) – The order in which to sort the results of a list repositories oper-
ation.
Return type dict
Returns
Response Syntax
{
'repositories': [
{
'repositoryName': 'string',
'repositoryId': 'string'
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list repositories operation.
– repositories (list) –
Lists the repositories called by the list repositories operation.
* (dict) –
Information about a repository name and ID.
· repositoryName (string) – Repository name is restricted to
alphanumeric characters (a-z, A-Z, 0-9), ”.”, “_”, and “-”. Ad-
ditionally, the suffix ”.git” is prohibited in a repository name.
· repositoryId (string) –
The ID associated with the repository name.
– nextToken (string) –
An enumeration token that allows the operation to batch the results of the
operation. Batch sizes are 1,000 for list repository operations. When the
client sends the token back to AWS CodeCommit, another page of 1,000
records is retrieved.
update_default_branch(**kwargs)
Sets or changes the default branch name for the specified repository.
Note: If you use this operation to change the default branch name to the current default branch name, a
success message is returned even though the default branch did not change.
Request Syntax
460 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.update_default_branch(
repositoryName='string',
defaultBranchName='string'
)
Parameters
• repositoryName (string) – [REQUIRED]
The name of the repository to set or change the default branch for.
• defaultBranchName (string) – [REQUIRED]
The name of the branch to set as the default.
Returns None
update_repository_description(**kwargs)
Sets or changes the comment or description for a repository.
Note: The description field for a repository accepts all HTML characters and all valid Unicode characters.
Applications that do not HTML-encode the description and display it in a web page could expose users
to potentially malicious code. Make sure that you HTML-encode the description field in any application
that uses this API to display the repository description on a web page.
Request Syntax
response = client.update_repository_description(
repositoryName='string',
repositoryDescription='string'
)
Parameters
• repositoryName (string) – [REQUIRED]
The name of the repository to set or change the comment or description for.
• repositoryDescription (string) – The new comment or description for the spec-
ified repository.
Returns None
update_repository_name(**kwargs)
Renames a repository.
Request Syntax
response = client.update_repository_name(
oldName='string',
newName='string'
)
Parameters
• oldName (string) – [REQUIRED] Repository name is restricted to alphanu-
meric characters (a-z, A-Z, 0-9), ”.”, “_”, and “-”. Additionally, the suffix ”.git”
is prohibited in a repository name.
• newName (string) – [REQUIRED] Repository name is restricted to alphanu-
meric characters (a-z, A-Z, 0-9), ”.”, “_”, and “-”. Additionally, the suffix ”.git”
is prohibited in a repository name.
Returns None
3.1. Services 461
Boto3 Documentation, Release 1.1.4
CodeDeploy
Table of Contents
• CodeDeploy
– Client
Client
class CodeDeploy.Client
A low-level client representing AWS CodeDeploy:
import boto3
client = boto3.client('codedeploy')
These are the available methods:
•add_tags_to_on_premises_instances()
•batch_get_applications()
•batch_get_deployments()
•batch_get_on_premises_instances()
•can_paginate()
•create_application()
•create_deployment()
•create_deployment_config()
•create_deployment_group()
•delete_application()
•delete_deployment_config()
•delete_deployment_group()
•deregister_on_premises_instance()
•generate_presigned_url()
•get_application()
•get_application_revision()
•get_deployment()
•get_deployment_config()
•get_deployment_group()
•get_deployment_instance()
•get_on_premises_instance()
•get_paginator()
•get_waiter()
•list_application_revisions()
•list_applications()
•list_deployment_configs()
•list_deployment_groups()
•list_deployment_instances()
•list_deployments()
•list_on_premises_instances()
•register_application_revision()
•register_on_premises_instance()
•remove_tags_from_on_premises_instances()
•stop_deployment()
•update_application()
462 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
•update_deployment_group()
add_tags_to_on_premises_instances(**kwargs)
Adds tags to on-premises instances.
Request Syntax
response = client.add_tags_to_on_premises_instances(
tags=[
{
'Key': 'string',
'Value': 'string'
},
],
instanceNames=[
'string',
]
)
Parameters
• tags (list) – [REQUIRED]
The tag key-value pairs to add to the on-premises instances.
Keys and values are both required. Keys cannot be nulls or empty strings. Value-
only tags are not allowed.
– (dict) –
Information about a tag.
* Key (string) –
The tag’s key.
* Value (string) –
The tag’s value.
• instanceNames (list) – [REQUIRED]
The names of the on-premises instances to add tags to.
– (string) –
Returns None
batch_get_applications(**kwargs)
Gets information about one or more applications.
Request Syntax
response = client.batch_get_applications(
applicationNames=[
'string',
]
)
Parameters applicationNames (list) – A list of application names, with multiple applica-
tion names separated by spaces.
• (string) –
Return type dict
Returns
Response Syntax
3.1. Services 463
Boto3 Documentation, Release 1.1.4
{
'applicationsInfo': [
{
'applicationId': 'string',
'applicationName': 'string',
'createTime': datetime(2015, 1, 1),
'linkedToGitHub': True|False
},
]
}
Response Structure
• (dict) –
Represents the output of a batch get applications operation.
– applicationsInfo (list) –
Information about the applications.
* (dict) –
Information about an application.
· applicationId (string) –
The application ID.
· applicationName (string) –
The application name.
· createTime (datetime) –
The time that the application was created.
· linkedToGitHub (boolean) –
True if the user has authenticated with GitHub for the speci-
fied application; otherwise, false.
batch_get_deployments(**kwargs)
Gets information about one or more deployments.
Request Syntax
response = client.batch_get_deployments(
deploymentIds=[
'string',
]
)
Parameters deploymentIds (list) – A list of deployment IDs, with multiple deployment IDs
separated by spaces.
• (string) –
Return type dict
Returns
Response Syntax
{
'deploymentsInfo': [
{
'applicationName': 'string',
'deploymentGroupName': 'string',
'deploymentConfigName': 'string',
464 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'deploymentId': 'string',
'revision': {
'revisionType': 'S3'|'GitHub',
's3Location': {
'bucket': 'string',
'key': 'string',
'bundleType': 'tar'|'tgz'|'zip',
'version': 'string',
'eTag': 'string'
},
'gitHubLocation': {
'repository': 'string',
'commitId': 'string'
}
},
'status': 'Created'|'Queued'|'InProgress'|'Succeeded'|'Failed'|'Stoppe
'errorInformation': {
'code': 'DEPLOYMENT_GROUP_MISSING'|'APPLICATION_MISSING'|'REVISION
'message': 'string'
},
'createTime': datetime(2015, 1, 1),
'startTime': datetime(2015, 1, 1),
'completeTime': datetime(2015, 1, 1),
'deploymentOverview': {
'Pending': 123,
'InProgress': 123,
'Succeeded': 123,
'Failed': 123,
'Skipped': 123
},
'description': 'string',
'creator': 'user'|'autoscaling',
'ignoreApplicationStopFailures': True|False
},
]
}
Response Structure
• (dict) –
Represents the output of a batch get deployments operation.
– deploymentsInfo (list) –
Information about the deployments.
* (dict) –
Information about a deployment.
· applicationName (string) –
The application name.
· deploymentGroupName (string) –
The deployment group name.
· deploymentConfigName (string) –
The deployment configuration name.
· deploymentId (string) –
The deployment ID.
· revision (dict) –
3.1. Services 465
Boto3 Documentation, Release 1.1.4
Information about the location of application artifacts that are
stored and the service to retrieve them from.
· revisionType (string) –
The application revision’s type:
· S3: An application revision stored in Amazon S3.
· GitHub: An application revision stored in GitHub.
· s3Location (dict) –
Information about the location of application artifacts that are
stored in Amazon S3.
· bucket (string) –
The name of the Amazon S3 bucket where the application
revision is stored.
· key (string) –
The name of the Amazon S3 object that represents the bun-
dled artifacts for the application revision.
· bundleType (string) –
The file type of the application revision. Must be one of the
following:
· tar: A tar archive file.
· tgz: A compressed tar archive file.
· zip: A zip archive file.
· version (string) –
A specific version of the Amazon S3 object that represents the
bundled artifacts for the application revision.
If the version is not specified, the system will use the most
recent version by default.
· eTag (string) –
The ETag of the Amazon S3 object that represents the bundled
artifacts for the application revision.
If the ETag is not specified as an input parameter, ETag vali-
dation of the object will be skipped.
· gitHubLocation (dict) –
Information about the location of application artifacts that are
stored in GitHub.
· repository (string) –
The GitHub account and repository pair that stores a refer-
ence to the commit that represents the bundled artifacts for
the application revision.
Specified as account/repository.
· commitId (string) –
The SHA1 commit ID of the GitHub commit that references
the that represents the bundled artifacts for the application re-
vision.
· status (string) –
The current state of the deployment as a whole.
· errorInformation (dict) –
466 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Information about any error associated with this deployment.
· code (string) –
The error code:
· APPLICATION_MISSING: The application was missing.
Note that this error code will most likely be raised if the ap-
plication is deleted after the deployment is created but before
it starts.
· DEPLOYMENT_GROUP_MISSING: The deployment
group was missing. Note that this error code will most
likely be raised if the deployment group is deleted after the
deployment is created but before it starts.
· HEALTH_CONSTRAINTS: The deployment failed on too
many instances to be able to successfully deploy within the
specified instance health constraints.
· HEALTH_CONSTRAINTS_INVALID: The revision can
never successfully deploy within the instance health con-
straints as specified.
· IAM_ROLE_MISSING: The service role cannot be accessed.
· IAM_ROLE_PERMISSIONS: The service role does not have
the correct permissions.
· INTERNAL_ERROR: There was an internal error.
· NO_EC2_SUBSCRIPTION: The calling account is not sub-
scribed to the Amazon EC2 service.
· NO_INSTANCES: No instances were specified, or no in-
stances can be found.
· OVER_MAX_INSTANCES: The maximum number of in-
stances was exceeded.
· THROTTLED: The operation was throttled because the call-
ing account exceeded the throttling limits of one or more
AWS services.
· TIMEOUT: The deployment has timed out.
· REVISION_MISSING: The revision ID was missing. Note
that this error code will most likely be raised if the revision is
deleted after the deployment is created but before it starts.
· message (string) –
An accompanying error message.
· createTime (datetime) –
A timestamp indicating when the deployment was created.
· startTime (datetime) –
A timestamp indicating when the deployment began deploy-
ing to the deployment group.
Note that in some cases, the reported value of the start time
may be later than the complete time. This is due to differ-
ences in the clock settings of various back-end servers that
participate in the overall deployment process.
· completeTime (datetime) –
A timestamp indicating when the deployment was completed.
· deploymentOverview (dict) –
A summary of the deployment status of the instances in the
deployment.
3.1. Services 467
Boto3 Documentation, Release 1.1.4
· Pending (integer) –
The number of instances that are pending in the deployment.
· InProgress (integer) –
The number of instances that are in progress in the deploy-
ment.
· Succeeded (integer) –
The number of instances that have succeeded in the deploy-
ment.
· Failed (integer) –
The number of instances that have failed in the deployment.
· Skipped (integer) –
The number of instances that have been skipped in the de-
ployment.
· description (string) –
A comment about the deployment.
· creator (string) –
How the deployment was created:
· user: A user created the deployment.
· autoscaling: Auto Scaling created the deployment.
· ignoreApplicationStopFailures (boolean) –
If true, then if the deployment causes the ApplicationStop de-
ployment lifecycle event to fail to a specific instance, the de-
ployment will not be considered to have failed to that instance
at that point and will continue on to the BeforeInstall deploy-
ment lifecycle event.
If false or not specified, then if the deployment causes the Ap-
plicationStop deployment lifecycle event to fail to a specific
instance, the deployment will stop to that instance, and the
deployment to that instance will be considered to have failed.
batch_get_on_premises_instances(**kwargs)
Gets information about one or more on-premises instances.
Request Syntax
response = client.batch_get_on_premises_instances(
instanceNames=[
'string',
]
)
Parameters instanceNames (list) – The names of the on-premises instances to get informa-
tion about.
• (string) –
Return type dict
Returns
Response Syntax
{
'instanceInfos': [
468 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'instanceName': 'string',
'iamUserArn': 'string',
'instanceArn': 'string',
'registerTime': datetime(2015, 1, 1),
'deregisterTime': datetime(2015, 1, 1),
'tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
Represents the output of a batch get on-premises instances operation.
– instanceInfos (list) –
Information about the on-premises instances.
* (dict) –
Information about an on-premises instance.
· instanceName (string) –
The name of the on-premises instance.
· iamUserArn (string) –
The IAM user ARN associated with the on-premises instance.
· instanceArn (string) –
The ARN of the on-premises instance.
· registerTime (datetime) –
The time that the on-premises instance was registered.
· deregisterTime (datetime) –
If the on-premises instance was deregistered, the time that the
on-premises instance was deregistered.
· tags (list) –
The tags that are currently associated with the on-premises
instance.
· (dict) –
Information about a tag.
· Key (string) –
The tag’s key.
· Value (string) –
The tag’s value.
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
3.1. Services 469
Boto3 Documentation, Release 1.1.4
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
create_application(**kwargs)
Creates a new application.
Request Syntax
response = client.create_application(
applicationName='string'
)
Parameters applicationName (string) – [REQUIRED]
The name of the application. This name must be unique with the applicable IAM user
or AWS account.
Return type dict
Returns
Response Syntax
{
'applicationId': 'string'
}
Response Structure
• (dict) –
Represents the output of a create application operation.
– applicationId (string) –
A unique application ID.
create_deployment(**kwargs)
Deploys an application revision through the specified deployment group.
Request Syntax
response = client.create_deployment(
applicationName='string',
deploymentGroupName='string',
revision={
'revisionType': 'S3'|'GitHub',
's3Location': {
'bucket': 'string',
'key': 'string',
'bundleType': 'tar'|'tgz'|'zip',
'version': 'string',
'eTag': 'string'
},
'gitHubLocation': {
'repository': 'string',
'commitId': 'string'
}
},
deploymentConfigName='string',
description='string',
ignoreApplicationStopFailures=True|False
)
470 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the ap-
plicable IAM user or AWS account.
• deploymentGroupName (string) – The deployment group’s name.
• revision (dict) – The type of revision to deploy, along with information about
the revision’s location.
– revisionType (string) –
The application revision’s type:
* S3: An application revision stored in Amazon S3.
* GitHub: An application revision stored in GitHub.
– s3Location (dict) –
Information about the location of application artifacts that are stored in
Amazon S3.
* bucket (string) –
The name of the Amazon S3 bucket where the application revision
is stored.
* key (string) –
The name of the Amazon S3 object that represents the bundled arti-
facts for the application revision.
* bundleType (string) –
The file type of the application revision. Must be one of the follow-
ing:
· tar: A tar archive file.
· tgz: A compressed tar archive file.
· zip: A zip archive file.
* version (string) –
A specific version of the Amazon S3 object that represents the bun-
dled artifacts for the application revision.
If the version is not specified, the system will use the most recent
version by default.
* eTag (string) –
The ETag of the Amazon S3 object that represents the bundled arti-
facts for the application revision.
If the ETag is not specified as an input parameter, ETag validation
of the object will be skipped.
– gitHubLocation (dict) –
Information about the location of application artifacts that are stored in
GitHub.
* repository (string) –
The GitHub account and repository pair that stores a reference to
the commit that represents the bundled artifacts for the application
revision.
Specified as account/repository.
* commitId (string) –
The SHA1 commit ID of the GitHub commit that references the that
represents the bundled artifacts for the application revision.
3.1. Services 471
Boto3 Documentation, Release 1.1.4
• deploymentConfigName (string) – The name of an existing deployment config-
uration associated with the applicable IAM user or AWS account.
If not specified, the value configured in the deployment group will be used as the
default. If the deployment group does not have a deployment configuration as-
sociated with it, then CodeDeployDefault.OneAtATime will be used by default.
• description (string) – A comment about the deployment.
• ignoreApplicationStopFailures (boolean) – If set to true, then if the deploy-
ment causes the ApplicationStop deployment lifecycle event to fail to a specific
instance, the deployment will not be considered to have failed to that instance at
that point and will continue on to the BeforeInstall deployment lifecycle event.
If set to false or not specified, then if the deployment causes the ApplicationStop
deployment lifecycle event to fail to a specific instance, the deployment will stop
to that instance, and the deployment to that instance will be considered to have
failed.
Return type dict
Returns
Response Syntax
{
'deploymentId': 'string'
}
Response Structure
• (dict) –
Represents the output of a create deployment operation.
– deploymentId (string) –
A unique deployment ID.
create_deployment_config(**kwargs)
Creates a new deployment configuration.
Request Syntax
response = client.create_deployment_config(
deploymentConfigName='string',
minimumHealthyHosts={
'value': 123,
'type': 'HOST_COUNT'|'FLEET_PERCENT'
}
)
Parameters
• deploymentConfigName (string) – [REQUIRED]
The name of the deployment configuration to create.
• minimumHealthyHosts (dict) – The minimum number of healthy instances that
should be available at any time during the deployment. There are two parameters
expected in the input: type and value.
The type parameter takes either of the following values:
– HOST_COUNT: The value parameter represents the minimum number of
healthy instances, as an absolute value.
– FLEET_PERCENT: The value parameter represents the minimum number
of healthy instances, as a percentage of the total number of instances in
472 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
the deployment. If you specify FLEET_PERCENT, then at the start of the
deployment AWS CodeDeploy converts the percentage to the equivalent
number of instances and rounds fractional instances up.
The value parameter takes an integer.
For example, to set a minimum of 95% healthy instances, specify a type of
FLEET_PERCENT and a value of 95.
– value (integer) –
The minimum healthy instances value.
– type (string) –
The minimum healthy instances type:
* HOST_COUNT: The minimum number of healthy instances, as an
absolute value.
* FLEET_PERCENT: The minimum number of healthy instances, as
a percentage of the total number of instances in the deployment.
For example, for 9 instances, if a HOST_COUNT of 6 is specified, deploy
to up to 3 instances at a time. The deployment succeeds if 6 or more
instances are successfully deployed to; otherwise, the deployment fails.
If a FLEET_PERCENT of 40 is specified, deploy to up to 5 instances at
a time. The deployment succeeds if 4 or more instances are successfully
deployed to; otherwise, the deployment fails.
Note: In a call to the get deployment configuration operation,
CodeDeployDefault.OneAtATime will return a minimum healthy in-
stances type of MOST_CONCURRENCY and a value of 1. This
means a deployment to only one instances at a time. (You cannot
set the type to MOST_CONCURRENCY, only to HOST_COUNT or
FLEET_PERCENT.)
Return type dict
Returns
Response Syntax
{
'deploymentConfigId': 'string'
}
Response Structure
• (dict) –
Represents the output of a create deployment configuration operation.
– deploymentConfigId (string) –
A unique deployment configuration ID.
create_deployment_group(**kwargs)
Creates a new deployment group for application revisions to be deployed to.
Request Syntax
response = client.create_deployment_group(
applicationName='string',
deploymentGroupName='string',
deploymentConfigName='string',
ec2TagFilters=[
{
3.1. Services 473
Boto3 Documentation, Release 1.1.4
'Key': 'string',
'Value': 'string',
'Type': 'KEY_ONLY'|'VALUE_ONLY'|'KEY_AND_VALUE'
},
],
onPremisesInstanceTagFilters=[
{
'Key': 'string',
'Value': 'string',
'Type': 'KEY_ONLY'|'VALUE_ONLY'|'KEY_AND_VALUE'
},
],
autoScalingGroups=[
'string',
],
serviceRoleArn='string'
)
Parameters
• applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the ap-
plicable IAM user or AWS account.
• deploymentGroupName (string) – [REQUIRED]
The name of an existing deployment group for the specified application.
• deploymentConfigName (string) – If specified, the deployment configuration
name must be one of the predefined values, or it can be a custom deployment
configuration:
– CodeDeployDefault.AllAtOnce deploys an application revision to up to
all of the instances at once. The overall deployment succeeds if the ap-
plication revision deploys to at least one of the instances. The overall
deployment fails after the application revision fails to deploy to all of the
instances. For example, for 9 instances, deploy to up to all 9 instances at
once. The overall deployment succeeds if any of the 9 instances is suc-
cessfully deployed to, and it fails if all 9 instances fail to be deployed to.
– CodeDeployDefault.HalfAtATime deploys to up to half of the instances at
a time (with fractions rounded down). The overall deployment succeeds
if the application revision deploys to at least half of the instances (with
fractions rounded up); otherwise, the deployment fails. For example, for
9 instances, deploy to up to 4 instances at a time. The overall deployment
succeeds if 5 or more instances are successfully deployed to; otherwise,
the deployment fails. Note that the deployment may successfully deploy
to some instances, even if the overall deployment fails.
– CodeDeployDefault.OneAtATime deploys the application revision to only
one of the instances at a time. The overall deployment succeeds if the ap-
plication revision deploys to all of the instances. The overall deployment
fails after the application revision first fails to deploy to any one instances.
For example, for 9 instances, deploy to one instance at a time. The overall
deployment succeeds if all 9 instances are successfully deployed to, and
it fails if any of one of the 9 instances fail to be deployed to. Note that
the deployment may successfully deploy to some instances, even if the
overall deployment fails. This is the default deployment configuration if a
configuration isn’t specified for either the deployment or the deployment
group.
To create a custom deployment configuration, call the create deployment config-
474 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
uration operation.
• ec2TagFilters (list) – The Amazon EC2 tags to filter on.
– (dict) –
Information about a tag filter.
* Key (string) –
The tag filter key.
* Value (string) –
The tag filter value.
* Type (string) –
The tag filter type:
· KEY_ONLY: Key only.
· VALUE_ONLY: Value only.
· KEY_AND_VALUE: Key and value.
• onPremisesInstanceTagFilters (list) – The on-premises instance tags to filter
on.
– (dict) –
Information about an on-premises instance tag filter.
* Key (string) –
The on-premises instance tag filter key.
* Value (string) –
The on-premises instance tag filter value.
* Type (string) –
The on-premises instance tag filter type:
· KEY_ONLY: Key only.
· VALUE_ONLY: Value only.
· KEY_AND_VALUE: Key and value.
• autoScalingGroups (list) – A list of associated Auto Scaling groups.
– (string) –
• serviceRoleArn (string) – [REQUIRED]
A service role ARN that allows AWS CodeDeploy to act on the user’s behalf
when interacting with AWS services.
Return type dict
Returns
Response Syntax
{
'deploymentGroupId': 'string'
}
Response Structure
• (dict) –
Represents the output of a create deployment group operation.
– deploymentGroupId (string) –
A unique deployment group ID.
delete_application(**kwargs)
Deletes an application.
Request Syntax
3.1. Services 475
Boto3 Documentation, Release 1.1.4
response = client.delete_application(
applicationName='string'
)
Parameters applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the applicable
IAM user or AWS account.
Returns None
delete_deployment_config(**kwargs)
Deletes a deployment configuration.
Note: A deployment configuration cannot be deleted if it is currently in use. Also, predefined configura-
tions cannot be deleted.
Request Syntax
response = client.delete_deployment_config(
deploymentConfigName='string'
)
Parameters deploymentConfigName (string) – [REQUIRED]
The name of an existing deployment configuration associated with the applicable IAM
user or AWS account.
Returns None
delete_deployment_group(**kwargs)
Deletes a deployment group.
Request Syntax
response = client.delete_deployment_group(
applicationName='string',
deploymentGroupName='string'
)
Parameters
• applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the ap-
plicable IAM user or AWS account.
• deploymentGroupName (string) – [REQUIRED]
The name of an existing deployment group for the specified application.
Return type dict
Returns
Response Syntax
{
'hooksNotCleanedUp': [
{
'name': 'string',
'hook': 'string'
},
476 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
]
}
Response Structure
• (dict) –
Represents the output of a delete deployment group operation.
– hooksNotCleanedUp (list) –
If the output contains no data, and the corresponding deployment group
contained at least one Auto Scaling group, AWS CodeDeploy successfully
removed all corresponding Auto Scaling lifecycle event hooks from the
Amazon EC2 instances in the Auto Scaling. If the output does contain
data, AWS CodeDeploy could not remove some Auto Scaling lifecycle
event hooks from the Amazon EC2 instances in the Auto Scaling group.
* (dict) –
Information about an Auto Scaling group.
· name (string) –
The Auto Scaling group name.
· hook (string) –
An Auto Scaling lifecycle event hook name.
deregister_on_premises_instance(**kwargs)
Deregisters an on-premises instance.
Request Syntax
response = client.deregister_on_premises_instance(
instanceName='string'
)
Parameters instanceName (string) – [REQUIRED]
The name of the on-premises instance to deregister.
Returns None
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_application(**kwargs)
Gets information about an application.
Request Syntax
response = client.get_application(
applicationName='string'
)
3.1. Services 477
Boto3 Documentation, Release 1.1.4
Parameters applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the applicable
IAM user or AWS account.
Return type dict
Returns
Response Syntax
{
'application': {
'applicationId': 'string',
'applicationName': 'string',
'createTime': datetime(2015, 1, 1),
'linkedToGitHub': True|False
}
}
Response Structure
• (dict) –
Represents the output of a get application operation.
– application (dict) –
Information about the application.
* applicationId (string) –
The application ID.
* applicationName (string) –
The application name.
* createTime (datetime) –
The time that the application was created.
* linkedToGitHub (boolean) –
True if the user has authenticated with GitHub for the specified ap-
plication; otherwise, false.
get_application_revision(**kwargs)
Gets information about an application revision.
Request Syntax
response = client.get_application_revision(
applicationName='string',
revision={
'revisionType': 'S3'|'GitHub',
's3Location': {
'bucket': 'string',
'key': 'string',
'bundleType': 'tar'|'tgz'|'zip',
'version': 'string',
'eTag': 'string'
},
'gitHubLocation': {
'repository': 'string',
'commitId': 'string'
}
}
)
478 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• applicationName (string) – [REQUIRED]
The name of the application that corresponds to the revision.
• revision (dict) – [REQUIRED]
Information about the application revision to get, including the revision’s type
and its location.
– revisionType (string) –
The application revision’s type:
* S3: An application revision stored in Amazon S3.
* GitHub: An application revision stored in GitHub.
– s3Location (dict) –
Information about the location of application artifacts that are stored in
Amazon S3.
* bucket (string) –
The name of the Amazon S3 bucket where the application revision
is stored.
* key (string) –
The name of the Amazon S3 object that represents the bundled arti-
facts for the application revision.
* bundleType (string) –
The file type of the application revision. Must be one of the follow-
ing:
· tar: A tar archive file.
· tgz: A compressed tar archive file.
· zip: A zip archive file.
* version (string) –
A specific version of the Amazon S3 object that represents the bun-
dled artifacts for the application revision.
If the version is not specified, the system will use the most recent
version by default.
* eTag (string) –
The ETag of the Amazon S3 object that represents the bundled arti-
facts for the application revision.
If the ETag is not specified as an input parameter, ETag validation
of the object will be skipped.
– gitHubLocation (dict) –
Information about the location of application artifacts that are stored in
GitHub.
* repository (string) –
The GitHub account and repository pair that stores a reference to
the commit that represents the bundled artifacts for the application
revision.
Specified as account/repository.
* commitId (string) –
The SHA1 commit ID of the GitHub commit that references the that
represents the bundled artifacts for the application revision.
3.1. Services 479
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'applicationName': 'string',
'revision': {
'revisionType': 'S3'|'GitHub',
's3Location': {
'bucket': 'string',
'key': 'string',
'bundleType': 'tar'|'tgz'|'zip',
'version': 'string',
'eTag': 'string'
},
'gitHubLocation': {
'repository': 'string',
'commitId': 'string'
}
},
'revisionInfo': {
'description': 'string',
'deploymentGroups': [
'string',
],
'firstUsedTime': datetime(2015, 1, 1),
'lastUsedTime': datetime(2015, 1, 1),
'registerTime': datetime(2015, 1, 1)
}
}
Response Structure
• (dict) –
Represents the output of a get application revision operation.
– applicationName (string) –
The name of the application that corresponds to the revision.
– revision (dict) –
Additional information about the revision, including the revision’s type
and its location.
* revisionType (string) –
The application revision’s type:
· S3: An application revision stored in Amazon S3.
· GitHub: An application revision stored in GitHub.
* s3Location (dict) –
Information about the location of application artifacts that are stored
in Amazon S3.
· bucket (string) –
The name of the Amazon S3 bucket where the application
revision is stored.
· key (string) –
The name of the Amazon S3 object that represents the bun-
dled artifacts for the application revision.
480 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· bundleType (string) –
The file type of the application revision. Must be one of the
following:
· tar: A tar archive file.
· tgz: A compressed tar archive file.
· zip: A zip archive file.
· version (string) –
A specific version of the Amazon S3 object that represents the
bundled artifacts for the application revision.
If the version is not specified, the system will use the most
recent version by default.
· eTag (string) –
The ETag of the Amazon S3 object that represents the bundled
artifacts for the application revision.
If the ETag is not specified as an input parameter, ETag vali-
dation of the object will be skipped.
* gitHubLocation (dict) –
Information about the location of application artifacts that are stored
in GitHub.
· repository (string) –
The GitHub account and repository pair that stores a refer-
ence to the commit that represents the bundled artifacts for
the application revision.
Specified as account/repository.
· commitId (string) –
The SHA1 commit ID of the GitHub commit that references
the that represents the bundled artifacts for the application re-
vision.
– revisionInfo (dict) –
General information about the revision.
* description (string) –
A comment about the revision.
* deploymentGroups (list) –
A list of deployment groups that use this revision.
· (string) –
* firstUsedTime (datetime) –
When the revision was first used by AWS CodeDeploy.
* lastUsedTime (datetime) –
When the revision was last used by AWS CodeDeploy.
* registerTime (datetime) –
When the revision was registered with AWS CodeDeploy.
get_deployment(**kwargs)
Gets information about a deployment.
Request Syntax
3.1. Services 481
Boto3 Documentation, Release 1.1.4
response = client.get_deployment(
deploymentId='string'
)
Parameters deploymentId (string) – [REQUIRED]
An existing deployment ID associated with the applicable IAM user or AWS account.
Return type dict
Returns
Response Syntax
{
'deploymentInfo': {
'applicationName': 'string',
'deploymentGroupName': 'string',
'deploymentConfigName': 'string',
'deploymentId': 'string',
'revision': {
'revisionType': 'S3'|'GitHub',
's3Location': {
'bucket': 'string',
'key': 'string',
'bundleType': 'tar'|'tgz'|'zip',
'version': 'string',
'eTag': 'string'
},
'gitHubLocation': {
'repository': 'string',
'commitId': 'string'
}
},
'status': 'Created'|'Queued'|'InProgress'|'Succeeded'|'Failed'|'Stopped',
'errorInformation': {
'code': 'DEPLOYMENT_GROUP_MISSING'|'APPLICATION_MISSING'|'REVISION_MIS
'message': 'string'
},
'createTime': datetime(2015, 1, 1),
'startTime': datetime(2015, 1, 1),
'completeTime': datetime(2015, 1, 1),
'deploymentOverview': {
'Pending': 123,
'InProgress': 123,
'Succeeded': 123,
'Failed': 123,
'Skipped': 123
},
'description': 'string',
'creator': 'user'|'autoscaling',
'ignoreApplicationStopFailures': True|False
}
}
Response Structure
• (dict) –
Represents the output of a get deployment operation.
– deploymentInfo (dict) –
482 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Information about the deployment.
* applicationName (string) –
The application name.
* deploymentGroupName (string) –
The deployment group name.
* deploymentConfigName (string) –
The deployment configuration name.
* deploymentId (string) –
The deployment ID.
* revision (dict) –
Information about the location of application artifacts that are stored
and the service to retrieve them from.
· revisionType (string) –
The application revision’s type:
· S3: An application revision stored in Amazon S3.
· GitHub: An application revision stored in GitHub.
· s3Location (dict) –
Information about the location of application artifacts that are
stored in Amazon S3.
· bucket (string) –
The name of the Amazon S3 bucket where the application
revision is stored.
· key (string) –
The name of the Amazon S3 object that represents the bun-
dled artifacts for the application revision.
· bundleType (string) –
The file type of the application revision. Must be one of the
following:
· tar: A tar archive file.
· tgz: A compressed tar archive file.
· zip: A zip archive file.
· version (string) –
A specific version of the Amazon S3 object that represents the
bundled artifacts for the application revision.
If the version is not specified, the system will use the most
recent version by default.
· eTag (string) –
The ETag of the Amazon S3 object that represents the bundled
artifacts for the application revision.
If the ETag is not specified as an input parameter, ETag vali-
dation of the object will be skipped.
· gitHubLocation (dict) –
Information about the location of application artifacts that are
stored in GitHub.
· repository (string) –
3.1. Services 483
Boto3 Documentation, Release 1.1.4
The GitHub account and repository pair that stores a refer-
ence to the commit that represents the bundled artifacts for
the application revision.
Specified as account/repository.
· commitId (string) –
The SHA1 commit ID of the GitHub commit that references
the that represents the bundled artifacts for the application re-
vision.
* status (string) –
The current state of the deployment as a whole.
* errorInformation (dict) –
Information about any error associated with this deployment.
· code (string) –
The error code:
· APPLICATION_MISSING: The application was missing.
Note that this error code will most likely be raised if the ap-
plication is deleted after the deployment is created but before
it starts.
· DEPLOYMENT_GROUP_MISSING: The deployment
group was missing. Note that this error code will most
likely be raised if the deployment group is deleted after the
deployment is created but before it starts.
· HEALTH_CONSTRAINTS: The deployment failed on too
many instances to be able to successfully deploy within the
specified instance health constraints.
· HEALTH_CONSTRAINTS_INVALID: The revision can
never successfully deploy within the instance health con-
straints as specified.
· IAM_ROLE_MISSING: The service role cannot be accessed.
· IAM_ROLE_PERMISSIONS: The service role does not have
the correct permissions.
· INTERNAL_ERROR: There was an internal error.
· NO_EC2_SUBSCRIPTION: The calling account is not sub-
scribed to the Amazon EC2 service.
· NO_INSTANCES: No instances were specified, or no in-
stances can be found.
· OVER_MAX_INSTANCES: The maximum number of in-
stances was exceeded.
· THROTTLED: The operation was throttled because the call-
ing account exceeded the throttling limits of one or more
AWS services.
· TIMEOUT: The deployment has timed out.
· REVISION_MISSING: The revision ID was missing. Note
that this error code will most likely be raised if the revision is
deleted after the deployment is created but before it starts.
· message (string) –
An accompanying error message.
* createTime (datetime) –
A timestamp indicating when the deployment was created.
* startTime (datetime) –
484 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A timestamp indicating when the deployment began deploying to
the deployment group.
Note that in some cases, the reported value of the start time may be
later than the complete time. This is due to differences in the clock
settings of various back-end servers that participate in the overall
deployment process.
* completeTime (datetime) –
A timestamp indicating when the deployment was completed.
* deploymentOverview (dict) –
A summary of the deployment status of the instances in the deploy-
ment.
· Pending (integer) –
The number of instances that are pending in the deployment.
· InProgress (integer) –
The number of instances that are in progress in the deploy-
ment.
· Succeeded (integer) –
The number of instances that have succeeded in the deploy-
ment.
· Failed (integer) –
The number of instances that have failed in the deployment.
· Skipped (integer) –
The number of instances that have been skipped in the de-
ployment.
* description (string) –
A comment about the deployment.
* creator (string) –
How the deployment was created:
· user: A user created the deployment.
· autoscaling: Auto Scaling created the deployment.
* ignoreApplicationStopFailures (boolean) –
If true, then if the deployment causes the ApplicationStop deploy-
ment lifecycle event to fail to a specific instance, the deployment
will not be considered to have failed to that instance at that point and
will continue on to the BeforeInstall deployment lifecycle event.
If false or not specified, then if the deployment causes the Appli-
cationStop deployment lifecycle event to fail to a specific instance,
the deployment will stop to that instance, and the deployment to that
instance will be considered to have failed.
get_deployment_config(**kwargs)
Gets information about a deployment configuration.
Request Syntax
response = client.get_deployment_config(
deploymentConfigName='string'
)
3.1. Services 485
Boto3 Documentation, Release 1.1.4
Parameters deploymentConfigName (string) – [REQUIRED]
The name of an existing deployment configuration associated with the applicable IAM
user or AWS account.
Return type dict
Returns
Response Syntax
{
'deploymentConfigInfo': {
'deploymentConfigId': 'string',
'deploymentConfigName': 'string',
'minimumHealthyHosts': {
'value': 123,
'type': 'HOST_COUNT'|'FLEET_PERCENT'
},
'createTime': datetime(2015, 1, 1)
}
}
Response Structure
• (dict) –
Represents the output of a get deployment configuration operation.
– deploymentConfigInfo (dict) –
Information about the deployment configuration.
* deploymentConfigId (string) –
The deployment configuration ID.
* deploymentConfigName (string) –
The deployment configuration name.
* minimumHealthyHosts (dict) –
Information about the number or percentage of minimum healthy
instances.
· value (integer) –
The minimum healthy instances value.
· type (string) –
The minimum healthy instances type:
· HOST_COUNT: The minimum number of healthy instances,
as an absolute value.
· FLEET_PERCENT: The minimum number of healthy in-
stances, as a percentage of the total number of instances in
the deployment.
For example, for 9 instances, if a HOST_COUNT of 6 is spec-
ified, deploy to up to 3 instances at a time. The deployment
succeeds if 6 or more instances are successfully deployed to;
otherwise, the deployment fails. If a FLEET_PERCENT of
40 is specified, deploy to up to 5 instances at a time. The
deployment succeeds if 4 or more instances are successfully
deployed to; otherwise, the deployment fails.
Note: In a call to the get deployment configuration operation,
CodeDeployDefault.OneAtATime will return a minimum
healthy instances type of MOST_CONCURRENCY and a
486 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
value of 1. This means a deployment to only one instances at a
time. (You cannot set the type to MOST_CONCURRENCY,
only to HOST_COUNT or FLEET_PERCENT.)
* createTime (datetime) –
The time that the deployment configuration was created.
get_deployment_group(**kwargs)
Gets information about a deployment group.
Request Syntax
response = client.get_deployment_group(
applicationName='string',
deploymentGroupName='string'
)
Parameters
• applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the ap-
plicable IAM user or AWS account.
• deploymentGroupName (string) – [REQUIRED]
The name of an existing deployment group for the specified application.
Return type dict
Returns
Response Syntax
{
'deploymentGroupInfo': {
'applicationName': 'string',
'deploymentGroupId': 'string',
'deploymentGroupName': 'string',
'deploymentConfigName': 'string',
'ec2TagFilters': [
{
'Key': 'string',
'Value': 'string',
'Type': 'KEY_ONLY'|'VALUE_ONLY'|'KEY_AND_VALUE'
},
],
'onPremisesInstanceTagFilters': [
{
'Key': 'string',
'Value': 'string',
'Type': 'KEY_ONLY'|'VALUE_ONLY'|'KEY_AND_VALUE'
},
],
'autoScalingGroups': [
{
'name': 'string',
'hook': 'string'
},
],
'serviceRoleArn': 'string',
'targetRevision': {
'revisionType': 'S3'|'GitHub',
3.1. Services 487
Boto3 Documentation, Release 1.1.4
's3Location': {
'bucket': 'string',
'key': 'string',
'bundleType': 'tar'|'tgz'|'zip',
'version': 'string',
'eTag': 'string'
},
'gitHubLocation': {
'repository': 'string',
'commitId': 'string'
}
}
}
}
Response Structure
• (dict) –
Represents the output of a get deployment group operation.
– deploymentGroupInfo (dict) –
Information about the deployment group.
* applicationName (string) –
The application name.
* deploymentGroupId (string) –
The deployment group ID.
* deploymentGroupName (string) –
The deployment group name.
* deploymentConfigName (string) –
The deployment configuration name.
* ec2TagFilters (list) –
The Amazon EC2 tags to filter on.
· (dict) –
Information about a tag filter.
· Key (string) –
The tag filter key.
· Value (string) –
The tag filter value.
· Type (string) –
The tag filter type:
· KEY_ONLY: Key only.
· VALUE_ONLY: Value only.
· KEY_AND_VALUE: Key and value.
* onPremisesInstanceTagFilters (list) –
The on-premises instance tags to filter on.
· (dict) –
Information about an on-premises instance tag filter.
· Key (string) –
The on-premises instance tag filter key.
488 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Value (string) –
The on-premises instance tag filter value.
· Type (string) –
The on-premises instance tag filter type:
· KEY_ONLY: Key only.
· VALUE_ONLY: Value only.
· KEY_AND_VALUE: Key and value.
* autoScalingGroups (list) –
A list of associated Auto Scaling groups.
· (dict) –
Information about an Auto Scaling group.
· name (string) –
The Auto Scaling group name.
· hook (string) –
An Auto Scaling lifecycle event hook name.
* serviceRoleArn (string) –
A service role ARN.
* targetRevision (dict) –
Information about the deployment group’s target revision, including
the revision’s type and its location.
· revisionType (string) –
The application revision’s type:
· S3: An application revision stored in Amazon S3.
· GitHub: An application revision stored in GitHub.
· s3Location (dict) –
Information about the location of application artifacts that are
stored in Amazon S3.
· bucket (string) –
The name of the Amazon S3 bucket where the application
revision is stored.
· key (string) –
The name of the Amazon S3 object that represents the bun-
dled artifacts for the application revision.
· bundleType (string) –
The file type of the application revision. Must be one of the
following:
· tar: A tar archive file.
· tgz: A compressed tar archive file.
· zip: A zip archive file.
· version (string) –
A specific version of the Amazon S3 object that represents the
bundled artifacts for the application revision.
If the version is not specified, the system will use the most
recent version by default.
· eTag (string) –
3.1. Services 489
Boto3 Documentation, Release 1.1.4
The ETag of the Amazon S3 object that represents the bundled
artifacts for the application revision.
If the ETag is not specified as an input parameter, ETag vali-
dation of the object will be skipped.
· gitHubLocation (dict) –
Information about the location of application artifacts that are
stored in GitHub.
· repository (string) –
The GitHub account and repository pair that stores a refer-
ence to the commit that represents the bundled artifacts for
the application revision.
Specified as account/repository.
· commitId (string) –
The SHA1 commit ID of the GitHub commit that references
the that represents the bundled artifacts for the application re-
vision.
get_deployment_instance(**kwargs)
Gets information about an instance as part of a deployment.
Request Syntax
response = client.get_deployment_instance(
deploymentId='string',
instanceId='string'
)
Parameters
• deploymentId (string) – [REQUIRED]
The unique ID of a deployment.
• instanceId (string) – [REQUIRED]
The unique ID of an instance in the deployment’s deployment group.
Return type dict
Returns
Response Syntax
{
'instanceSummary': {
'deploymentId': 'string',
'instanceId': 'string',
'status': 'Pending'|'InProgress'|'Succeeded'|'Failed'|'Skipped'|'Unknown',
'lastUpdatedAt': datetime(2015, 1, 1),
'lifecycleEvents': [
{
'lifecycleEventName': 'string',
'diagnostics': {
'errorCode': 'Success'|'ScriptMissing'|'ScriptNotExecutable'|'
'scriptName': 'string',
'message': 'string',
'logTail': 'string'
},
'startTime': datetime(2015, 1, 1),
490 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'endTime': datetime(2015, 1, 1),
'status': 'Pending'|'InProgress'|'Succeeded'|'Failed'|'Skipped'|'U
},
]
}
}
Response Structure
• (dict) –
Represents the output of a get deployment instance operation.
– instanceSummary (dict) –
Information about the instance.
* deploymentId (string) –
The deployment ID.
* instanceId (string) –
The instance ID.
* status (string) –
The deployment status for this instance:
· Pending: The deployment is pending for this instance.
· In Progress: The deployment is in progress for this instance.
· Succeeded: The deployment has succeeded for this instance.
· Failed: The deployment has failed for this instance.
· Skipped: The deployment has been skipped for this instance.
· Unknown: The deployment status is unknown for this in-
stance.
* lastUpdatedAt (datetime) –
A timestamp indicating when the instance information was last up-
dated.
* lifecycleEvents (list) –
A list of lifecycle events for this instance.
· (dict) –
Information about a deployment lifecycle event.
· lifecycleEventName (string) –
The deployment lifecycle event name, such as Application-
Stop, BeforeInstall, AfterInstall, ApplicationStart, or Vali-
dateService.
· diagnostics (dict) –
Diagnostic information about the deployment lifecycle event.
· errorCode (string) –
The associated error code:
· Success: The specified script ran.
· ScriptMissing: The specified script was not found in the spec-
ified location.
· ScriptNotExecutable: The specified script is not a recognized
executable file type.
· ScriptTimedOut: The specified script did not finish running
in the specified time period.
· ScriptFailed: The specified script failed to run as expected.
3.1. Services 491
Boto3 Documentation, Release 1.1.4
· UnknownError: The specified script did not run for an un-
known reason.
· scriptName (string) –
The name of the script.
· message (string) –
The message associated with the error.
· logTail (string) –
The last portion of the associated diagnostic log.
· startTime (datetime) –
A timestamp indicating when the deployment lifecycle event
started.
· endTime (datetime) –
A timestamp indicating when the deployment lifecycle event
ended.
· status (string) –
The deployment lifecycle event status:
· Pending: The deployment lifecycle event is pending.
· InProgress: The deployment lifecycle event is in progress.
· Succeeded: The deployment lifecycle event has succeeded.
· Failed: The deployment lifecycle event has failed.
· Skipped: The deployment lifecycle event has been skipped.
· Unknown: The deployment lifecycle event is unknown.
get_on_premises_instance(**kwargs)
Gets information about an on-premises instance.
Request Syntax
response = client.get_on_premises_instance(
instanceName='string'
)
Parameters instanceName (string) – [REQUIRED]
The name of the on-premises instance to get information about
Return type dict
Returns
Response Syntax
{
'instanceInfo': {
'instanceName': 'string',
'iamUserArn': 'string',
'instanceArn': 'string',
'registerTime': datetime(2015, 1, 1),
'deregisterTime': datetime(2015, 1, 1),
'tags': [
{
'Key': 'string',
'Value': 'string'
},
]
492 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
}
}
Response Structure
• (dict) –
Represents the output of a get on-premises instance operation.
– instanceInfo (dict) –
Information about the on-premises instance.
* instanceName (string) –
The name of the on-premises instance.
* iamUserArn (string) –
The IAM user ARN associated with the on-premises instance.
* instanceArn (string) –
The ARN of the on-premises instance.
* registerTime (datetime) –
The time that the on-premises instance was registered.
* deregisterTime (datetime) –
If the on-premises instance was deregistered, the time that the on-
premises instance was deregistered.
* tags (list) –
The tags that are currently associated with the on-premises instance.
· (dict) –
Information about a tag.
· Key (string) –
The tag’s key.
· Value (string) –
The tag’s value.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
list_application_revisions(**kwargs)
Lists information about revisions for an application.
Request Syntax
response = client.list_application_revisions(
applicationName='string',
sortBy='registerTime'|'firstUsedTime'|'lastUsedTime',
3.1. Services 493
Boto3 Documentation, Release 1.1.4
sortOrder='ascending'|'descending',
s3Bucket='string',
s3KeyPrefix='string',
deployed='include'|'exclude'|'ignore',
nextToken='string'
)
Parameters
• applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the ap-
plicable IAM user or AWS account.
• sortBy (string) – The column name to sort the list results by:
– registerTime: Sort the list results by when the revisions were registered
with AWS CodeDeploy.
– firstUsedTime: Sort the list results by when the revisions were first used
by in a deployment.
– lastUsedTime: Sort the list results by when the revisions were last used in
a deployment.
If not specified or set to null, the results will be returned in an arbitrary order.
• sortOrder (string) – The order to sort the list results by:
– ascending: Sort the list of results in ascending order.
– descending: Sort the list of results in descending order.
If not specified, the results will be sorted in ascending order.
If set to null, the results will be sorted in an arbitrary order.
• s3Bucket (string) – A specific Amazon S3 bucket name to limit the search for
revisions.
If set to null, then all of the user’s buckets will be searched.
• s3KeyPrefix (string) – A specific key prefix for the set of Amazon S3 objects to
limit the search for revisions.
• deployed (string) – Whether to list revisions based on whether the revision is the
target revision of an deployment group:
– include: List revisions that are target revisions of a deployment group.
– exclude: Do not list revisions that are target revisions of a deployment
group.
– ignore: List all revisions, regardless of whether they are target revisions of
a deployment group.
• nextToken (string) – An identifier that was returned from the previous list ap-
plication revisions call, which can be used to return the next set of applications
in the list.
Return type dict
Returns
Response Syntax
{
'revisions': [
{
'revisionType': 'S3'|'GitHub',
's3Location': {
'bucket': 'string',
'key': 'string',
'bundleType': 'tar'|'tgz'|'zip',
'version': 'string',
'eTag': 'string'
494 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
'gitHubLocation': {
'repository': 'string',
'commitId': 'string'
}
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list application revisions operation.
– revisions (list) –
A list of revision locations that contain the matching revisions.
* (dict) –
Information about an application revision’s location.
· revisionType (string) –
The application revision’s type:
· S3: An application revision stored in Amazon S3.
· GitHub: An application revision stored in GitHub.
· s3Location (dict) –
Information about the location of application artifacts that are
stored in Amazon S3.
· bucket (string) –
The name of the Amazon S3 bucket where the application
revision is stored.
· key (string) –
The name of the Amazon S3 object that represents the bun-
dled artifacts for the application revision.
· bundleType (string) –
The file type of the application revision. Must be one of the
following:
· tar: A tar archive file.
· tgz: A compressed tar archive file.
· zip: A zip archive file.
· version (string) –
A specific version of the Amazon S3 object that represents the
bundled artifacts for the application revision.
If the version is not specified, the system will use the most
recent version by default.
· eTag (string) –
The ETag of the Amazon S3 object that represents the bundled
artifacts for the application revision.
If the ETag is not specified as an input parameter, ETag vali-
dation of the object will be skipped.
· gitHubLocation (dict) –
3.1. Services 495
Boto3 Documentation, Release 1.1.4
Information about the location of application artifacts that are
stored in GitHub.
· repository (string) –
The GitHub account and repository pair that stores a refer-
ence to the commit that represents the bundled artifacts for
the application revision.
Specified as account/repository.
· commitId (string) –
The SHA1 commit ID of the GitHub commit that references
the that represents the bundled artifacts for the application re-
vision.
– nextToken (string) –
If the amount of information that is returned is significantly large, an iden-
tifier will also be returned, which can be used in a subsequent list appli-
cation revisions call to return the next set of application revisions in the
list.
list_applications(**kwargs)
Lists the applications registered with the applicable IAM user or AWS account.
Request Syntax
response = client.list_applications(
nextToken='string'
)
Parameters nextToken (string) – An identifier that was returned from the previous list ap-
plications call, which can be used to return the next set of applications in the list.
Return type dict
Returns
Response Syntax
{
'applications': [
'string',
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list applications operation.
– applications (list) –
A list of application names.
* (string) –
– nextToken (string) –
If the amount of information that is returned is significantly large, an iden-
tifier will also be returned, which can be used in a subsequent list applica-
tions call to return the next set of applications in the list.
list_deployment_configs(**kwargs)
Lists the deployment configurations with the applicable IAM user or AWS account.
496 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.list_deployment_configs(
nextToken='string'
)
Parameters nextToken (string) – An identifier that was returned from the previous list de-
ployment configurations call, which can be used to return the next set of deployment
configurations in the list.
Return type dict
Returns
Response Syntax
{
'deploymentConfigsList': [
'string',
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list deployment configurations operation.
– deploymentConfigsList (list) –
A list of deployment configurations, including the built-in configurations
such as CodeDeployDefault.OneAtATime.
* (string) –
– nextToken (string) –
If the amount of information that is returned is significantly large, an iden-
tifier will also be returned, which can be used in a subsequent list deploy-
ment configurations call to return the next set of deployment configura-
tions in the list.
list_deployment_groups(**kwargs)
Lists the deployment groups for an application registered with the applicable IAM user or AWS account.
Request Syntax
response = client.list_deployment_groups(
applicationName='string',
nextToken='string'
)
Parameters
• applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the ap-
plicable IAM user or AWS account.
• nextToken (string) – An identifier that was returned from the previous list de-
ployment groups call, which can be used to return the next set of deployment
groups in the list.
Return type dict
Returns
Response Syntax
3.1. Services 497
Boto3 Documentation, Release 1.1.4
{
'applicationName': 'string',
'deploymentGroups': [
'string',
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list deployment groups operation.
– applicationName (string) –
The application name.
– deploymentGroups (list) –
A list of corresponding deployment group names.
* (string) –
– nextToken (string) –
If the amount of information that is returned is significantly large, an iden-
tifier will also be returned, which can be used in a subsequent list deploy-
ment groups call to return the next set of deployment groups in the list.
list_deployment_instances(**kwargs)
Lists the instances for a deployment associated with the applicable IAM user or AWS account.
Request Syntax
response = client.list_deployment_instances(
deploymentId='string',
nextToken='string',
instanceStatusFilter=[
'Pending'|'InProgress'|'Succeeded'|'Failed'|'Skipped'|'Unknown',
]
)
Parameters
• deploymentId (string) – [REQUIRED]
The unique ID of a deployment.
• nextToken (string) – An identifier that was returned from the previous list de-
ployment instances call, which can be used to return the next set of deployment
instances in the list.
• instanceStatusFilter (list) – A subset of instances to list, by status:
– Pending: Include in the resulting list those instances with pending deploy-
ments.
– InProgress: Include in the resulting list those instances with in-progress
deployments.
– Succeeded: Include in the resulting list those instances with succeeded
deployments.
– Failed: Include in the resulting list those instances with failed deploy-
ments.
– Skipped: Include in the resulting list those instances with skipped deploy-
ments.
– Unknown: Include in the resulting list those instances with deployments
in an unknown state.
498 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– (string) –
Return type dict
Returns
Response Syntax
{
'instancesList': [
'string',
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list deployment instances operation.
– instancesList (list) –
A list of instances IDs.
* (string) –
– nextToken (string) –
If the amount of information that is returned is significantly large, an iden-
tifier will also be returned, which can be used in a subsequent list deploy-
ment instances call to return the next set of deployment instances in the
list.
list_deployments(**kwargs)
Lists the deployments within a deployment group for an application registered with the applicable IAM
user or AWS account.
Request Syntax
response = client.list_deployments(
applicationName='string',
deploymentGroupName='string',
includeOnlyStatuses=[
'Created'|'Queued'|'InProgress'|'Succeeded'|'Failed'|'Stopped',
],
createTimeRange={
'start': datetime(2015, 1, 1),
'end': datetime(2015, 1, 1)
},
nextToken='string'
)
Parameters
• applicationName (string) – The name of an existing AWS CodeDeploy appli-
cation associated with the applicable IAM user or AWS account.
• deploymentGroupName (string) – The name of an existing deployment group
for the specified application.
• includeOnlyStatuses (list) – A subset of deployments to list, by status:
– Created: Include in the resulting list created deployments.
– Queued: Include in the resulting list queued deployments.
– In Progress: Include in the resulting list in-progress deployments.
– Succeeded: Include in the resulting list succeeded deployments.
– Failed: Include in the resulting list failed deployments.
– Aborted: Include in the resulting list aborted deployments.
3.1. Services 499
Boto3 Documentation, Release 1.1.4
– (string) –
• createTimeRange (dict) – A deployment creation start- and end-time range for
returning a subset of the list of deployments.
– start (datetime) –
The time range’s start time.
Note: Specify null to leave the time range’s start time open-ended.
– end (datetime) –
The time range’s end time.
Note: Specify null to leave the time range’s end time open-ended.
• nextToken (string) – An identifier that was returned from the previous list de-
ployments call, which can be used to return the next set of deployments in the
list.
Return type dict
Returns
Response Syntax
{
'deployments': [
'string',
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list deployments operation.
– deployments (list) –
A list of deployment IDs.
* (string) –
– nextToken (string) –
If the amount of information that is returned is significantly large, an iden-
tifier will also be returned, which can be used in a subsequent list deploy-
ments call to return the next set of deployments in the list.
list_on_premises_instances(**kwargs)
Gets a list of one or more on-premises instance names.
Unless otherwise specified, both registered and deregistered on-premises instance names will be listed.
To list only registered or deregistered on-premises instance names, use the registration status parameter.
Request Syntax
response = client.list_on_premises_instances(
registrationStatus='Registered'|'Deregistered',
tagFilters=[
{
'Key': 'string',
'Value': 'string',
'Type': 'KEY_ONLY'|'VALUE_ONLY'|'KEY_AND_VALUE'
},
500 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
nextToken='string'
)
Parameters
• registrationStatus (string) – The on-premises instances registration status:
– Deregistered: Include in the resulting list deregistered on-premises in-
stances.
– Registered: Include in the resulting list registered on-premises instances.
• tagFilters (list) – The on-premises instance tags that will be used to restrict the
corresponding on-premises instance names that are returned.
– (dict) –
Information about an on-premises instance tag filter.
* Key (string) –
The on-premises instance tag filter key.
* Value (string) –
The on-premises instance tag filter value.
* Type (string) –
The on-premises instance tag filter type:
· KEY_ONLY: Key only.
· VALUE_ONLY: Value only.
· KEY_AND_VALUE: Key and value.
• nextToken (string) – An identifier that was returned from the previous list on-
premises instances call, which can be used to return the next set of on-premises
instances in the list.
Return type dict
Returns
Response Syntax
{
'instanceNames': [
'string',
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of list on-premises instances operation.
– instanceNames (list) –
The list of matching on-premises instance names.
* (string) –
– nextToken (string) –
If the amount of information that is returned is significantly large, an iden-
tifier will also be returned, which can be used in a subsequent list on-
premises instances call to return the next set of on-premises instances in
the list.
register_application_revision(**kwargs)
Registers with AWS CodeDeploy a revision for the specified application.
3.1. Services 501
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.register_application_revision(
applicationName='string',
description='string',
revision={
'revisionType': 'S3'|'GitHub',
's3Location': {
'bucket': 'string',
'key': 'string',
'bundleType': 'tar'|'tgz'|'zip',
'version': 'string',
'eTag': 'string'
},
'gitHubLocation': {
'repository': 'string',
'commitId': 'string'
}
}
)
Parameters
• applicationName (string) – [REQUIRED]
The name of an existing AWS CodeDeploy application associated with the ap-
plicable IAM user or AWS account.
• description (string) – A comment about the revision.
• revision (dict) – [REQUIRED]
Information about the application revision to register, including the revision’s
type and its location.
– revisionType (string) –
The application revision’s type:
* S3: An application revision stored in Amazon S3.
* GitHub: An application revision stored in GitHub.
– s3Location (dict) –
Information about the location of application artifacts that are stored in
Amazon S3.
* bucket (string) –
The name of the Amazon S3 bucket where the application revision
is stored.
* key (string) –
The name of the Amazon S3 object that represents the bundled arti-
facts for the application revision.
* bundleType (string) –
The file type of the application revision. Must be one of the follow-
ing:
· tar: A tar archive file.
· tgz: A compressed tar archive file.
· zip: A zip archive file.
* version (string) –
A specific version of the Amazon S3 object that represents the bun-
dled artifacts for the application revision.
502 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
If the version is not specified, the system will use the most recent
version by default.
* eTag (string) –
The ETag of the Amazon S3 object that represents the bundled arti-
facts for the application revision.
If the ETag is not specified as an input parameter, ETag validation
of the object will be skipped.
– gitHubLocation (dict) –
Information about the location of application artifacts that are stored in
GitHub.
* repository (string) –
The GitHub account and repository pair that stores a reference to
the commit that represents the bundled artifacts for the application
revision.
Specified as account/repository.
* commitId (string) –
The SHA1 commit ID of the GitHub commit that references the that
represents the bundled artifacts for the application revision.
Returns None
register_on_premises_instance(**kwargs)
Registers an on-premises instance.
Request Syntax
response = client.register_on_premises_instance(
instanceName='string',
iamUserArn='string'
)
Parameters
• instanceName (string) – [REQUIRED]
The name of the on-premises instance to register.
• iamUserArn (string) – [REQUIRED]
The ARN of the IAM user to associate with the on-premises instance.
Returns None
remove_tags_from_on_premises_instances(**kwargs)
Removes one or more tags from one or more on-premises instances.
Request Syntax
response = client.remove_tags_from_on_premises_instances(
tags=[
{
'Key': 'string',
'Value': 'string'
},
],
instanceNames=[
'string',
]
)
3.1. Services 503
Boto3 Documentation, Release 1.1.4
Parameters
• tags (list) – [REQUIRED]
The tag key-value pairs to remove from the on-premises instances.
– (dict) –
Information about a tag.
* Key (string) –
The tag’s key.
* Value (string) –
The tag’s value.
• instanceNames (list) – [REQUIRED]
The names of the on-premises instances to remove tags from.
– (string) –
Returns None
stop_deployment(**kwargs)
Attempts to stop an ongoing deployment.
Request Syntax
response = client.stop_deployment(
deploymentId='string'
)
Parameters deploymentId (string) – [REQUIRED]
The unique ID of a deployment.
Return type dict
Returns
Response Syntax
{
'status': 'Pending'|'Succeeded',
'statusMessage': 'string'
}
Response Structure
• (dict) –
Represents the output of a stop deployment operation.
– status (string) –
The status of the stop deployment operation:
* Pending: The stop operation is pending.
* Succeeded: The stop operation succeeded.
– statusMessage (string) –
An accompanying status message.
update_application(**kwargs)
Changes an existing application’s name.
Request Syntax
504 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.update_application(
applicationName='string',
newApplicationName='string'
)
Parameters
• applicationName (string) – The current name of the application that you want
to change.
• newApplicationName (string) – The new name that you want to change the
application to.
Returns None
update_deployment_group(**kwargs)
Changes information about an existing deployment group.
Request Syntax
response = client.update_deployment_group(
applicationName='string',
currentDeploymentGroupName='string',
newDeploymentGroupName='string',
deploymentConfigName='string',
ec2TagFilters=[
{
'Key': 'string',
'Value': 'string',
'Type': 'KEY_ONLY'|'VALUE_ONLY'|'KEY_AND_VALUE'
},
],
onPremisesInstanceTagFilters=[
{
'Key': 'string',
'Value': 'string',
'Type': 'KEY_ONLY'|'VALUE_ONLY'|'KEY_AND_VALUE'
},
],
autoScalingGroups=[
'string',
],
serviceRoleArn='string'
)
Parameters
• applicationName (string) – [REQUIRED]
The application name corresponding to the deployment group to update.
• currentDeploymentGroupName (string) – [REQUIRED]
The current name of the existing deployment group.
• newDeploymentGroupName (string) – The new name of the deployment
group, if you want to change it.
• deploymentConfigName (string) – The replacement deployment configuration
name to use, if you want to change it.
• ec2TagFilters (list) – The replacement set of Amazon EC2 tags to filter on, if
you want to change them.
– (dict) –
Information about a tag filter.
3.1. Services 505
Boto3 Documentation, Release 1.1.4
* Key (string) –
The tag filter key.
* Value (string) –
The tag filter value.
* Type (string) –
The tag filter type:
· KEY_ONLY: Key only.
· VALUE_ONLY: Value only.
· KEY_AND_VALUE: Key and value.
• onPremisesInstanceTagFilters (list) – The replacement set of on-premises in-
stance tags for filter on, if you want to change them.
– (dict) –
Information about an on-premises instance tag filter.
* Key (string) –
The on-premises instance tag filter key.
* Value (string) –
The on-premises instance tag filter value.
* Type (string) –
The on-premises instance tag filter type:
· KEY_ONLY: Key only.
· VALUE_ONLY: Value only.
· KEY_AND_VALUE: Key and value.
• autoScalingGroups (list) – The replacement list of Auto Scaling groups to be
included in the deployment group, if you want to change them.
– (string) –
• serviceRoleArn (string) – A replacement service role’s ARN, if you want to
change it.
Return type dict
Returns
Response Syntax
{
'hooksNotCleanedUp': [
{
'name': 'string',
'hook': 'string'
},
]
}
Response Structure
• (dict) –
Represents the output of an update deployment group operation.
– hooksNotCleanedUp (list) –
If the output contains no data, and the corresponding deployment group
contained at least one Auto Scaling group, AWS CodeDeploy successfully
removed all corresponding Auto Scaling lifecycle event hooks from the
AWS account. If the output does contain data, AWS CodeDeploy could
not remove some Auto Scaling lifecycle event hooks from the AWS ac-
count.
506 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* (dict) –
Information about an Auto Scaling group.
· name (string) –
The Auto Scaling group name.
· hook (string) –
An Auto Scaling lifecycle event hook name.
CodePipeline
Table of Contents
• CodePipeline
– Client
Client
class CodePipeline.Client
A low-level client representing AWS CodePipeline:
import boto3
client = boto3.client('codepipeline')
These are the available methods:
•acknowledge_job()
•acknowledge_third_party_job()
•can_paginate()
•create_custom_action_type()
•create_pipeline()
•delete_custom_action_type()
•delete_pipeline()
•disable_stage_transition()
•enable_stage_transition()
•generate_presigned_url()
•get_job_details()
•get_paginator()
•get_pipeline()
•get_pipeline_state()
•get_third_party_job_details()
•get_waiter()
•list_action_types()
•list_pipelines()
•poll_for_jobs()
•poll_for_third_party_jobs()
•put_action_revision()
•put_job_failure_result()
•put_job_success_result()
•put_third_party_job_failure_result()
•put_third_party_job_success_result()
•start_pipeline_execution()
3.1. Services 507
Boto3 Documentation, Release 1.1.4
•update_pipeline()
acknowledge_job(**kwargs)
Returns information about a specified job and whether that job has been received by the job worker. Only
used for custom actions.
Request Syntax
response = client.acknowledge_job(
jobId='string',
nonce='string'
)
Parameters
• jobId (string) – [REQUIRED]
The unique system-generated ID of the job for which you want to confirm re-
ceipt.
• nonce (string) – [REQUIRED]
A system-generated random number that AWS CodePipeline uses to ensure that
the job is being worked on by only one job worker. This number must be returned
in the response.
Return type dict
Returns
Response Syntax
{
'status': 'Created'|'Queued'|'Dispatched'|'InProgress'|'TimedOut'|'Succeeded'|
}
Response Structure
• (dict) –
Represents the output of an acknowledge job action.
– status (string) –
Whether the job worker has received the specified job.
acknowledge_third_party_job(**kwargs)
Confirms a job worker has received the specified job. Only used for partner actions.
Request Syntax
response = client.acknowledge_third_party_job(
jobId='string',
nonce='string',
clientToken='string'
)
Parameters
• jobId (string) – [REQUIRED]
The unique system-generated ID of the job.
• nonce (string) – [REQUIRED]
A system-generated random number that AWS CodePipeline uses to ensure that
the job is being worked on by only one job worker. This number must be returned
in the response.
508 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• clientToken (string) – [REQUIRED]
The clientToken portion of the clientId and clientToken pair used to verify that
the calling entity is allowed access to the job and its details.
Return type dict
Returns
Response Syntax
{
'status': 'Created'|'Queued'|'Dispatched'|'InProgress'|'TimedOut'|'Succeeded'|
}
Response Structure
• (dict) –
Represents the output of an acknowledge third party job action.
– status (string) –
The status information for the third party job, if any.
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
create_custom_action_type(**kwargs)
Creates a new custom action that can be used in all pipelines associated with the AWS account. Only used
for custom actions.
Request Syntax
response = client.create_custom_action_type(
category='Source'|'Build'|'Deploy'|'Test'|'Invoke',
provider='string',
version='string',
settings={
'thirdPartyConfigurationUrl': 'string',
'entityUrlTemplate': 'string',
'executionUrlTemplate': 'string',
'revisionUrlTemplate': 'string'
},
configurationProperties=[
{
'name': 'string',
'required': True|False,
'key': True|False,
'secret': True|False,
'queryable': True|False,
'description': 'string',
'type': 'String'|'Number'|'Boolean'
},
],
inputArtifactDetails={
'minimumCount': 123,
3.1. Services 509
Boto3 Documentation, Release 1.1.4
'maximumCount': 123
},
outputArtifactDetails={
'minimumCount': 123,
'maximumCount': 123
}
)
Parameters
• category (string) – [REQUIRED]
The category of the custom action, such as a source action or a build action.
• provider (string) – [REQUIRED]
The provider of the service used in the custom action, such as AWS CodeDeploy.
• version (string) – [REQUIRED]
The version number of the custom action.
Note: A newly-created custom action is always assigned a version number of 1
. This is required.
• settings (dict) – Returns information about the settings for an action type.
– thirdPartyConfigurationUrl (string) –
The URL of a sign-up page where users can sign up for an external service
and perform initial configuration of the action provided by that service.
– entityUrlTemplate (string) –
The URL returned to the AWS CodePipeline console that provides a deep
link to the resources of the external system, such as the configuration page
for an AWS CodeDeploy deployment group. This link is provided as part
of the action display within the pipeline.
– executionUrlTemplate (string) –
The URL returned to the AWS CodePipeline console that contains a link
to the top-level landing page for the external system, such as console page
for AWS CodeDeploy. This link is shown on the pipeline view page in the
AWS CodePipeline console and provides a link to the execution entity of
the external action.
– revisionUrlTemplate (string) –
The URL returned to the AWS CodePipeline console that contains a link
to the page where customers can update or change the configuration of the
external action.
• configurationProperties (list) – The configuration properties for the custom ac-
tion.
– (dict) –
Represents information about an action configuration property.
* name (string) – [REQUIRED]
The name of the action configuration property.
* required (boolean) – [REQUIRED]
Whether the configuration property is a required value.
* key (boolean) – [REQUIRED]
Whether the configuration property is a key.
510 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* secret (boolean) – [REQUIRED]
Whether the configuration property is secret. Secrets are hidden
from all calls except for GetJobDetails, GetThirdPartyJobDetails,
PollForJobs, and PollForThirdPartyJobs.
When updating a pipeline, passing * * * * * without changing any
other values of the action will preserve the prior value of the secret.
* queryable (boolean) –
Indicates that the proprety will be used in conjunction with PollFor-
Jobs. When creating a custom action, an action can have up to one
queryable property. If it has one, that property must be both required
and not secret.
If you create a pipeline with a custom action type, and that custom
action contains a queryable property, the value for that configuration
property is subject to additional restrictions. The value must be less
than or equal to twenty (20) characters. The value can contain only
alphanumeric characters, underscores, and hyphens.
* description (string) –
The description of the action configuration property that will be dis-
played to users.
* type (string) –
The type of the configuration property.
• inputArtifactDetails (dict) – [REQUIRED]
Returns information about the details of an artifact.
– minimumCount (integer) – [REQUIRED]
The minimum number of artifacts allowed for the action type.
– maximumCount (integer) – [REQUIRED]
The maximum number of artifacts allowed for the action type.
• outputArtifactDetails (dict) – [REQUIRED]
Returns information about the details of an artifact.
– minimumCount (integer) – [REQUIRED]
The minimum number of artifacts allowed for the action type.
– maximumCount (integer) – [REQUIRED]
The maximum number of artifacts allowed for the action type.
Return type dict
Returns
Response Syntax
{
'actionType': {
'id': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'settings': {
'thirdPartyConfigurationUrl': 'string',
'entityUrlTemplate': 'string',
3.1. Services 511
Boto3 Documentation, Release 1.1.4
'executionUrlTemplate': 'string',
'revisionUrlTemplate': 'string'
},
'actionConfigurationProperties': [
{
'name': 'string',
'required': True|False,
'key': True|False,
'secret': True|False,
'queryable': True|False,
'description': 'string',
'type': 'String'|'Number'|'Boolean'
},
],
'inputArtifactDetails': {
'minimumCount': 123,
'maximumCount': 123
},
'outputArtifactDetails': {
'minimumCount': 123,
'maximumCount': 123
}
}
}
Response Structure
• (dict) –
Represents the output of a create custom action operation.
– actionType (dict) –
Returns information about the details of an action type.
* id (dict) –
Represents information about an action type.
· category (string) –
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) –
The creator of the action being called.
· provider (string) –
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) –
A string that identifies the action type.
* settings (dict) –
The settings for the action type.
· thirdPartyConfigurationUrl (string) –
The URL of a sign-up page where users can sign up for an
external service and perform initial configuration of the action
provided by that service.
512 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· entityUrlTemplate (string) –
The URL returned to the AWS CodePipeline console that pro-
vides a deep link to the resources of the external system, such
as the configuration page for an AWS CodeDeploy deploy-
ment group. This link is provided as part of the action display
within the pipeline.
· executionUrlTemplate (string) –
The URL returned to the AWS CodePipeline console that con-
tains a link to the top-level landing page for the external sys-
tem, such as console page for AWS CodeDeploy. This link
is shown on the pipeline view page in the AWS CodePipeline
console and provides a link to the execution entity of the ex-
ternal action.
· revisionUrlTemplate (string) –
The URL returned to the AWS CodePipeline console that con-
tains a link to the page where customers can update or change
the configuration of the external action.
* actionConfigurationProperties (list) –
The configuration properties for the action type.
· (dict) –
Represents information about an action configuration prop-
erty.
· name (string) –
The name of the action configuration property.
· required (boolean) –
Whether the configuration property is a required value.
· key (boolean) –
Whether the configuration property is a key.
· secret (boolean) –
Whether the configuration property is secret. Secrets are
hidden from all calls except for GetJobDetails, GetThirdPar-
tyJobDetails, PollForJobs, and PollForThirdPartyJobs.
When updating a pipeline, passing * * * * * without changing
any other values of the action will preserve the prior value of
the secret.
· queryable (boolean) –
Indicates that the proprety will be used in conjunction with
PollForJobs. When creating a custom action, an action can
have up to one queryable property. If it has one, that property
must be both required and not secret.
If you create a pipeline with a custom action type, and that
custom action contains a queryable property, the value for
that configuration property is subject to additional restric-
tions. The value must be less than or equal to twenty (20)
characters. The value can contain only alphanumeric charac-
ters, underscores, and hyphens.
· description (string) –
3.1. Services 513
Boto3 Documentation, Release 1.1.4
The description of the action configuration property that will
be displayed to users.
· type (string) –
The type of the configuration property.
* inputArtifactDetails (dict) –
The details of the input artifact for the action, such as its commit ID.
· minimumCount (integer) –
The minimum number of artifacts allowed for the action type.
· maximumCount (integer) –
The maximum number of artifacts allowed for the action type.
* outputArtifactDetails (dict) –
The details of the output artifact of the action, such as its commit
ID.
· minimumCount (integer) –
The minimum number of artifacts allowed for the action type.
· maximumCount (integer) –
The maximum number of artifacts allowed for the action type.
create_pipeline(**kwargs)
Creates a pipeline.
Request Syntax
response = client.create_pipeline(
pipeline={
'name': 'string',
'roleArn': 'string',
'artifactStore': {
'type': 'S3',
'location': 'string',
'encryptionKey': {
'id': 'string',
'type': 'KMS'
}
},
'stages': [
{
'name': 'string',
'blockers': [
{
'name': 'string',
'type': 'Schedule'
},
],
'actions': [
{
'name': 'string',
'actionTypeId': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'runOrder': 123,
514 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'configuration': {
'string': 'string'
},
'outputArtifacts': [
{
'name': 'string'
},
],
'inputArtifacts': [
{
'name': 'string'
},
],
'roleArn': 'string'
},
]
},
],
'version': 123
}
)
Parameters pipeline (dict) – [REQUIRED]
Represents the structure of actions and stages to be performed in the pipeline.
• name (string) – [REQUIRED]
The name of the action to be performed.
• roleArn (string) – [REQUIRED]
The Amazon Resource Name (ARN) for AWS CodePipeline to use to either
perform actions with no actionRoleArn, or to use to assume roles for actions
with an actionRoleArn.
• artifactStore (dict) – [REQUIRED]
The Amazon S3 location where artifacts are stored for the pipeline. If this Ama-
zon S3 bucket is created manually, it must meet the requirements for AWS Code-
Pipeline. For more information, see the Concepts.
– type (string) – [REQUIRED]
The type of the artifact store, such as S3.
– location (string) – [REQUIRED]
The location for storing the artifacts for a pipeline, such as an S3 bucket
or folder.
– encryptionKey (dict) –
The AWS Key Management Service (AWS KMS) key used to encrypt the
data in the artifact store. If this is undefined, the default key for Amazon
S3 is used.
* id (string) – [REQUIRED]
The ID of the AWS KMS key.
* type (string) – [REQUIRED]
The type of AWS KMS key, such as a customer master key.
• stages (list) – [REQUIRED]
The stage in which to perform the action.
– (dict) –
3.1. Services 515
Boto3 Documentation, Release 1.1.4
Represents information about a stage and its definition.
* name (string) – [REQUIRED]
The name of the stage.
* blockers (list) –
The gates included in a stage.
· (dict) –
Represents information about a gate declaration.
· name (string) – [REQUIRED]
The name of the gate declaration.
· type (string) – [REQUIRED]
The type of the gate declaration.
* actions (list) – [REQUIRED]
The actions included in a stage.
· (dict) –
Represents information about an action declaration.
· name (string) – [REQUIRED]
The action declaration’s name.
· actionTypeId (dict) – [REQUIRED]
The configuration information for the action type.
· category (string) – [REQUIRED]
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) – [REQUIRED]
The creator of the action being called.
· provider (string) – [REQUIRED]
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) – [REQUIRED]
A string that identifies the action type.
· runOrder (integer) –
The order in which actions are run.
· configuration (dict) –
The action declaration’s configuration.
· (string) –
· (string) –
· outputArtifacts (list) –
The name or ID of the result of the action declaration, such as
a test or build artifact.
· (dict) –
Represents information about the output of an action.
· name (string) – [REQUIRED]
The name of the output of an artifact, such as “My App”.
516 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
Output artifact names must be unique within a pipeline.
· inputArtifacts (list) –
The name or ID of the artifact consumed by the action, such
as a test or build artifact.
· (dict) –
Represents information about an artifact to be worked on,
such as a test or build artifact.
· name (string) – [REQUIRED]
The name of the artifact to be worked on, for example, “My
App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
· roleArn (string) –
The ARN of the IAM service role that will perform the de-
clared action. This is assumed through the roleArn for the
pipeline.
• version (integer) –
The version number of the pipeline. A new pipeline always has a version number
of 1. This number is automatically incremented when a pipeline is updated.
Return type dict
Returns
Response Syntax
{
'pipeline': {
'name': 'string',
'roleArn': 'string',
'artifactStore': {
'type': 'S3',
'location': 'string',
'encryptionKey': {
'id': 'string',
'type': 'KMS'
}
},
'stages': [
{
'name': 'string',
'blockers': [
{
'name': 'string',
3.1. Services 517
Boto3 Documentation, Release 1.1.4
'type': 'Schedule'
},
],
'actions': [
{
'name': 'string',
'actionTypeId': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'runOrder': 123,
'configuration': {
'string': 'string'
},
'outputArtifacts': [
{
'name': 'string'
},
],
'inputArtifacts': [
{
'name': 'string'
},
],
'roleArn': 'string'
},
]
},
],
'version': 123
}
}
Response Structure
• (dict) –
Represents the output of a create pipeline action.
– pipeline (dict) –
Represents the structure of actions and stages to be performed in the
pipeline.
* name (string) –
The name of the action to be performed.
* roleArn (string) –
The Amazon Resource Name (ARN) for AWS CodePipeline to use
to either perform actions with no actionRoleArn, or to use to assume
roles for actions with an actionRoleArn.
* artifactStore (dict) –
The Amazon S3 location where artifacts are stored for the pipeline.
If this Amazon S3 bucket is created manually, it must meet the re-
quirements for AWS CodePipeline. For more information, see the
Concepts.
· type (string) –
518 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The type of the artifact store, such as S3.
· location (string) –
The location for storing the artifacts for a pipeline, such as an
S3 bucket or folder.
· encryptionKey (dict) –
The AWS Key Management Service (AWS KMS) key used to
encrypt the data in the artifact store. If this is undefined, the
default key for Amazon S3 is used.
· id (string) –
The ID of the AWS KMS key.
· type (string) –
The type of AWS KMS key, such as a customer master key.
* stages (list) –
The stage in which to perform the action.
· (dict) –
Represents information about a stage and its definition.
· name (string) –
The name of the stage.
· blockers (list) –
The gates included in a stage.
· (dict) –
Represents information about a gate declaration.
· name (string) –
The name of the gate declaration.
· type (string) –
The type of the gate declaration.
· actions (list) –
The actions included in a stage.
· (dict) –
Represents information about an action declaration.
· name (string) –
The action declaration’s name.
· actionTypeId (dict) –
The configuration information for the action type.
· category (string) –
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) –
The creator of the action being called.
· provider (string) –
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
3.1. Services 519
Boto3 Documentation, Release 1.1.4
· version (string) –
A string that identifies the action type.
· runOrder (integer) –
The order in which actions are run.
· configuration (dict) –
The action declaration’s configuration.
· (string) –
· (string) –
· outputArtifacts (list) –
The name or ID of the result of the action declaration, such as
a test or build artifact.
· (dict) –
Represents information about the output of an action.
· name (string) –
The name of the output of an artifact, such as “My App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
Output artifact names must be unique within a pipeline.
· inputArtifacts (list) –
The name or ID of the artifact consumed by the action, such
as a test or build artifact.
· (dict) –
Represents information about an artifact to be worked on,
such as a test or build artifact.
· name (string) –
The name of the artifact to be worked on, for example, “My
App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
· roleArn (string) –
The ARN of the IAM service role that will perform the de-
clared action. This is assumed through the roleArn for the
pipeline.
* version (integer) –
The version number of the pipeline. A new pipeline always has
a version number of 1. This number is automatically incremented
when a pipeline is updated.
520 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
delete_custom_action_type(**kwargs)
Marks a custom action as deleted. PollForJobs for the custom action will fail after the action is marked
for deletion. Only used for custom actions.
Warning: You cannot recreate a custom action after it has been deleted unless you increase the
version number of the action.
Request Syntax
response = client.delete_custom_action_type(
category='Source'|'Build'|'Deploy'|'Test'|'Invoke',
provider='string',
version='string'
)
Parameters
• category (string) – [REQUIRED]
The category of the custom action that you want to delete, such as source or
deploy.
• provider (string) – [REQUIRED]
The provider of the service used in the custom action, such as AWS CodeDeploy.
• version (string) – [REQUIRED]
The version of the custom action to delete.
Returns None
delete_pipeline(**kwargs)
Deletes the specified pipeline.
Request Syntax
response = client.delete_pipeline(
name='string'
)
Parameters name (string) – [REQUIRED]
The name of the pipeline to be deleted.
Returns None
disable_stage_transition(**kwargs)
Prevents artifacts in a pipeline from transitioning to the next stage in the pipeline.
Request Syntax
response = client.disable_stage_transition(
pipelineName='string',
stageName='string',
transitionType='Inbound'|'Outbound',
reason='string'
)
Parameters
• pipelineName (string) – [REQUIRED]
The name of the pipeline in which you want to disable the flow of artifacts from
one stage to another.
3.1. Services 521
Boto3 Documentation, Release 1.1.4
• stageName (string) – [REQUIRED]
The name of the stage where you want to disable the inbound or outbound tran-
sition of artifacts.
• transitionType (string) – [REQUIRED]
Specifies whether artifacts will be prevented from transitioning into the stage
and being processed by the actions in that stage (inbound), or prevented from
transitioning from the stage after they have been processed by the actions in that
stage (outbound).
• reason (string) – [REQUIRED]
The reason given to the user why a stage is disabled, such as waiting for manual
approval or manual tests. This message is displayed in the pipeline console UI.
Returns None
enable_stage_transition(**kwargs)
Enables artifacts in a pipeline to transition to a stage in a pipeline.
Request Syntax
response = client.enable_stage_transition(
pipelineName='string',
stageName='string',
transitionType='Inbound'|'Outbound'
)
Parameters
• pipelineName (string) – [REQUIRED]
The name of the pipeline in which you want to enable the flow of artifacts from
one stage to another.
• stageName (string) – [REQUIRED]
The name of the stage where you want to enable the transition of artifacts, either
into the stage (inbound) or from that stage to the next stage (outbound).
• transitionType (string) – [REQUIRED]
Specifies whether artifacts will be allowed to enter the stage and be processed by
the actions in that stage (inbound) or whether already-processed artifacts will be
allowed to transition to the next stage (outbound).
Returns None
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_job_details(**kwargs)
Returns information about a job. Only used for custom actions.
522 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Warning: When this API is called, AWS CodePipeline returns temporary credentials for the Amazon
S3 bucket used to store artifacts for the pipeline, if the action requires access to that Amazon S3 bucket
for input or output artifacts. Additionally, this API returns any secret values defined for the action.
Request Syntax
response = client.get_job_details(
jobId='string'
)
Parameters jobId (string) – [REQUIRED]
The unique system-generated ID for the job.
Return type dict
Returns
Response Syntax
{
'jobDetails': {
'id': 'string',
'data': {
'actionTypeId': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'actionConfiguration': {
'configuration': {
'string': 'string'
}
},
'pipelineContext': {
'pipelineName': 'string',
'stage': {
'name': 'string'
},
'action': {
'name': 'string'
}
},
'inputArtifacts': [
{
'name': 'string',
'revision': 'string',
'location': {
'type': 'S3',
's3Location': {
'bucketName': 'string',
'objectKey': 'string'
}
}
},
],
'outputArtifacts': [
{
3.1. Services 523
Boto3 Documentation, Release 1.1.4
'name': 'string',
'revision': 'string',
'location': {
'type': 'S3',
's3Location': {
'bucketName': 'string',
'objectKey': 'string'
}
}
},
],
'artifactCredentials': {
'accessKeyId': 'string',
'secretAccessKey': 'string',
'sessionToken': 'string'
},
'continuationToken': 'string',
'encryptionKey': {
'id': 'string',
'type': 'KMS'
}
},
'accountId': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a get job details action.
– jobDetails (dict) –
The details of the job.
Note: If AWSSessionCredentials is used, a long-running job can call
GetJobDetails again to obtain new credentials.
* id (string) –
The unique system-generated ID of the job.
* data (dict) –
Represents additional information about a job required for a job
worker to complete the job.
· actionTypeId (dict) –
Represents information about an action type.
· category (string) –
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) –
The creator of the action being called.
· provider (string) –
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
524 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) –
A string that identifies the action type.
· actionConfiguration (dict) –
Represents information about an action configuration.
· configuration (dict) –
The configuration data for the action.
· (string) –
· (string) –
· pipelineContext (dict) –
Represents information about a pipeline to a job worker.
· pipelineName (string) –
The name of the pipeline. This is a user-specified value.
Pipeline names must be unique across all pipeline names un-
der an Amazon Web Services account.
· stage (dict) –
The stage of the pipeline.
· name (string) –
The name of the stage.
· action (dict) –
Represents the context of an action within the stage of a
pipeline to a job worker.
· name (string) –
The name of the action within the context of a job.
· inputArtifacts (list) –
The artifact supplied to the job.
· (dict) –
Represents information about an artifact that will be worked
upon by actions in the pipeline.
· name (string) –
The artifact’s name.
· revision (string) –
The artifact’s revision ID. Depending on the type of object,
this could be a commit ID (GitHub) or a revision ID (Amazon
S3).
· location (dict) –
The location of an artifact.
· type (string) –
The type of artifact in the location.
· s3Location (dict) –
The Amazon S3 bucket that contains the artifact.
· bucketName (string) –
The name of the Amazon S3 bucket.
3.1. Services 525
Boto3 Documentation, Release 1.1.4
· objectKey (string) –
The key of the object in the Amazon S3 bucket, which
uniquely identifies the object in the bucket.
· outputArtifacts (list) –
The output of the job.
· (dict) –
Represents information about an artifact that will be worked
upon by actions in the pipeline.
· name (string) –
The artifact’s name.
· revision (string) –
The artifact’s revision ID. Depending on the type of object,
this could be a commit ID (GitHub) or a revision ID (Amazon
S3).
· location (dict) –
The location of an artifact.
· type (string) –
The type of artifact in the location.
· s3Location (dict) –
The Amazon S3 bucket that contains the artifact.
· bucketName (string) –
The name of the Amazon S3 bucket.
· objectKey (string) –
The key of the object in the Amazon S3 bucket, which
uniquely identifies the object in the bucket.
· artifactCredentials (dict) –
Represents an AWS session credentials object. These creden-
tials are temporary credentials that are issued by AWS Secure
Token Service (STS). They can be used to access input and
output artifacts in the Amazon S3 bucket used to store artifact
for the pipeline in AWS CodePipeline.
· accessKeyId (string) –
The access key for the session.
· secretAccessKey (string) –
The secret access key for the session.
· sessionToken (string) –
The token for the session.
· continuationToken (string) –
A system-generated token, such as a AWS CodeDeploy de-
ployment ID, that a job requires in order to continue the job
asynchronously.
· encryptionKey (dict) –
Represents information about the AWS Key Management
Service (AWS KMS) key used to encrypt data in the artifact
store.
526 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· id (string) –
The ID of the AWS KMS key.
· type (string) –
The type of AWS KMS key, such as a customer master key.
* accountId (string) –
The AWS account ID associated with the job.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_pipeline(**kwargs)
Returns the metadata, structure, stages, and actions of a pipeline. Can be used to return the entire structure
of a pipeline in JSON format, which can then be modified and used to update the pipeline structure with
UpdatePipeline .
Request Syntax
response = client.get_pipeline(
name='string',
version=123
)
Parameters
• name (string) – [REQUIRED]
The name of the pipeline for which you want to get information. Pipeline names
must be unique under an Amazon Web Services (AWS) user account.
• version (integer) – The version number of the pipeline. If you do not specify a
version, defaults to the most current version.
Return type dict
Returns
Response Syntax
{
'pipeline': {
'name': 'string',
'roleArn': 'string',
'artifactStore': {
'type': 'S3',
'location': 'string',
'encryptionKey': {
'id': 'string',
'type': 'KMS'
}
},
'stages': [
3.1. Services 527
Boto3 Documentation, Release 1.1.4
{
'name': 'string',
'blockers': [
{
'name': 'string',
'type': 'Schedule'
},
],
'actions': [
{
'name': 'string',
'actionTypeId': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'runOrder': 123,
'configuration': {
'string': 'string'
},
'outputArtifacts': [
{
'name': 'string'
},
],
'inputArtifacts': [
{
'name': 'string'
},
],
'roleArn': 'string'
},
]
},
],
'version': 123
}
}
Response Structure
• (dict) –
Represents the output of a get pipeline action.
– pipeline (dict) –
Represents the structure of actions and stages to be performed in the
pipeline.
* name (string) –
The name of the action to be performed.
* roleArn (string) –
The Amazon Resource Name (ARN) for AWS CodePipeline to use
to either perform actions with no actionRoleArn, or to use to assume
roles for actions with an actionRoleArn.
* artifactStore (dict) –
The Amazon S3 location where artifacts are stored for the pipeline.
528 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
If this Amazon S3 bucket is created manually, it must meet the re-
quirements for AWS CodePipeline. For more information, see the
Concepts.
· type (string) –
The type of the artifact store, such as S3.
· location (string) –
The location for storing the artifacts for a pipeline, such as an
S3 bucket or folder.
· encryptionKey (dict) –
The AWS Key Management Service (AWS KMS) key used to
encrypt the data in the artifact store. If this is undefined, the
default key for Amazon S3 is used.
· id (string) –
The ID of the AWS KMS key.
· type (string) –
The type of AWS KMS key, such as a customer master key.
* stages (list) –
The stage in which to perform the action.
· (dict) –
Represents information about a stage and its definition.
· name (string) –
The name of the stage.
· blockers (list) –
The gates included in a stage.
· (dict) –
Represents information about a gate declaration.
· name (string) –
The name of the gate declaration.
· type (string) –
The type of the gate declaration.
· actions (list) –
The actions included in a stage.
· (dict) –
Represents information about an action declaration.
· name (string) –
The action declaration’s name.
· actionTypeId (dict) –
The configuration information for the action type.
· category (string) –
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) –
The creator of the action being called.
3.1. Services 529
Boto3 Documentation, Release 1.1.4
· provider (string) –
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) –
A string that identifies the action type.
· runOrder (integer) –
The order in which actions are run.
· configuration (dict) –
The action declaration’s configuration.
· (string) –
· (string) –
· outputArtifacts (list) –
The name or ID of the result of the action declaration, such as
a test or build artifact.
· (dict) –
Represents information about the output of an action.
· name (string) –
The name of the output of an artifact, such as “My App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
Output artifact names must be unique within a pipeline.
· inputArtifacts (list) –
The name or ID of the artifact consumed by the action, such
as a test or build artifact.
· (dict) –
Represents information about an artifact to be worked on,
such as a test or build artifact.
· name (string) –
The name of the artifact to be worked on, for example, “My
App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
· roleArn (string) –
The ARN of the IAM service role that will perform the de-
clared action. This is assumed through the roleArn for the
pipeline.
530 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* version (integer) –
The version number of the pipeline. A new pipeline always has
a version number of 1. This number is automatically incremented
when a pipeline is updated.
get_pipeline_state(**kwargs)
Returns information about the state of a pipeline, including the stages, actions, and details about the last
run of the pipeline.
Request Syntax
response = client.get_pipeline_state(
name='string'
)
Parameters name (string) – [REQUIRED]
The name of the pipeline about which you want to get information.
Return type dict
Returns
Response Syntax
{
'pipelineName': 'string',
'pipelineVersion': 123,
'stageStates': [
{
'stageName': 'string',
'inboundTransitionState': {
'enabled': True|False,
'lastChangedBy': 'string',
'lastChangedAt': datetime(2015, 1, 1),
'disabledReason': 'string'
},
'actionStates': [
{
'actionName': 'string',
'currentRevision': {
'revisionId': 'string',
'revisionChangeId': 'string',
'created': datetime(2015, 1, 1)
},
'latestExecution': {
'status': 'InProgress'|'Succeeded'|'Failed',
'summary': 'string',
'lastStatusChange': datetime(2015, 1, 1),
'externalExecutionId': 'string',
'externalExecutionUrl': 'string',
'percentComplete': 123,
'errorDetails': {
'code': 'string',
'message': 'string'
}
},
'entityUrl': 'string',
'revisionUrl': 'string'
},
3.1. Services 531
Boto3 Documentation, Release 1.1.4
]
},
],
'created': datetime(2015, 1, 1),
'updated': datetime(2015, 1, 1)
}
Response Structure
• (dict) –
Represents the output of a get pipeline state action.
– pipelineName (string) –
The name of the pipeline for which you want to get the state.
– pipelineVersion (integer) –
The version number of the pipeline.
Note: A newly-created pipeline is always assigned a version number of
1.
– stageStates (list) –
A list of the pipeline stage output information, including stage name, state,
most recent run details, whether the stage is disabled, and other data.
* (dict) –
Represents information about the state of the stage.
· stageName (string) –
The name of the stage.
· inboundTransitionState (dict) –
The state of the inbound transition, which is either enabled or
disabled.
· enabled (boolean) –
Whether the transition between stages is enabled (true) or dis-
abled (false).
· lastChangedBy (string) –
The ID of the user who last changed the transition state.
· lastChangedAt (datetime) –
The timestamp when the transition state was last changed.
· disabledReason (string) –
The user-specified reason why the transition between two
stages of a pipeline was disabled.
· actionStates (list) –
The state of the stage.
· (dict) –
Represents information about the state of an action.
· actionName (string) –
The name of the action.
· currentRevision (dict) –
Represents information about the version (or revision) of an
action.
532 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· revisionId (string) –
The system-generated unique ID that identifies the revision
number of the action.
· revisionChangeId (string) –
The unique identifier of the change that set the state to this
revision, for example a deployment ID or timestamp.
· created (datetime) –
The date and time when the most recent version of the action
was created, in timestamp format.
· latestExecution (dict) –
Represents information about how an action runs.
· status (string) –
The status of the action, or for a completed action, the last
status of the action.
· summary (string) –
A summary of the run of the action.
· lastStatusChange (datetime) –
The last status change of the action.
· externalExecutionId (string) –
The external ID of the run of the action.
· externalExecutionUrl (string) –
The URL of a resource external to AWS that will be used
when running the action, for example an external repository
URL.
· percentComplete (integer) –
A percentage of completeness of the action as it runs.
· errorDetails (dict) –
The details of an error returned by a URL external to AWS.
· code (string) –
The system ID or error number code of the error.
· message (string) –
The text of the error message.
· entityUrl (string) –
A URL link for more information about the state of the action,
such as a deployment group details page.
· revisionUrl (string) –
A URL link for more information about the revision, such as
a commit details page.
– created (datetime) –
The date and time the pipeline was created, in timestamp format.
– updated (datetime) –
The date and time the pipeline was last updated, in timestamp format.
get_third_party_job_details(**kwargs)
Requests the details of a job for a third party action. Only used for partner actions.
3.1. Services 533
Boto3 Documentation, Release 1.1.4
Warning: When this API is called, AWS CodePipeline returns temporary credentials for the Amazon
S3 bucket used to store artifacts for the pipeline, if the action requires access to that Amazon S3 bucket
for input or output artifacts. Additionally, this API returns any secret values defined for the action.
Request Syntax
response = client.get_third_party_job_details(
jobId='string',
clientToken='string'
)
Parameters
• jobId (string) – [REQUIRED]
The unique system-generated ID used for identifying the job.
• clientToken (string) – [REQUIRED]
The clientToken portion of the clientId and clientToken pair used to verify that
the calling entity is allowed access to the job and its details.
Return type dict
Returns
Response Syntax
{
'jobDetails': {
'id': 'string',
'data': {
'actionTypeId': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'actionConfiguration': {
'configuration': {
'string': 'string'
}
},
'pipelineContext': {
'pipelineName': 'string',
'stage': {
'name': 'string'
},
'action': {
'name': 'string'
}
},
'inputArtifacts': [
{
'name': 'string',
'revision': 'string',
'location': {
'type': 'S3',
's3Location': {
'bucketName': 'string',
'objectKey': 'string'
}
534 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
}
},
],
'outputArtifacts': [
{
'name': 'string',
'revision': 'string',
'location': {
'type': 'S3',
's3Location': {
'bucketName': 'string',
'objectKey': 'string'
}
}
},
],
'artifactCredentials': {
'accessKeyId': 'string',
'secretAccessKey': 'string',
'sessionToken': 'string'
},
'continuationToken': 'string',
'encryptionKey': {
'id': 'string',
'type': 'KMS'
}
},
'nonce': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a get third party job details action.
– jobDetails (dict) –
The details of the job, including any protected values defined for the job.
* id (string) –
The identifier used to identify the job details in AWS CodePipeline.
* data (dict) –
The data to be returned by the third party job worker.
· actionTypeId (dict) –
Represents information about an action type.
· category (string) –
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) –
The creator of the action being called.
· provider (string) –
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
3.1. Services 535
Boto3 Documentation, Release 1.1.4
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) –
A string that identifies the action type.
· actionConfiguration (dict) –
Represents information about an action configuration.
· configuration (dict) –
The configuration data for the action.
· (string) –
· (string) –
· pipelineContext (dict) –
Represents information about a pipeline to a job worker.
· pipelineName (string) –
The name of the pipeline. This is a user-specified value.
Pipeline names must be unique across all pipeline names un-
der an Amazon Web Services account.
· stage (dict) –
The stage of the pipeline.
· name (string) –
The name of the stage.
· action (dict) –
Represents the context of an action within the stage of a
pipeline to a job worker.
· name (string) –
The name of the action within the context of a job.
· inputArtifacts (list) –
The name of the artifact that will be worked upon by the ac-
tion, if any. This name might be system-generated, such as
“MyApp”, or might be defined by the user when the action is
created. The input artifact name must match the name of an
output artifact generated by an action in an earlier action or
stage of the pipeline.
· (dict) –
Represents information about an artifact that will be worked
upon by actions in the pipeline.
· name (string) –
The artifact’s name.
· revision (string) –
The artifact’s revision ID. Depending on the type of object,
this could be a commit ID (GitHub) or a revision ID (Amazon
S3).
· location (dict) –
The location of an artifact.
· type (string) –
The type of artifact in the location.
536 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· s3Location (dict) –
The Amazon S3 bucket that contains the artifact.
· bucketName (string) –
The name of the Amazon S3 bucket.
· objectKey (string) –
The key of the object in the Amazon S3 bucket, which
uniquely identifies the object in the bucket.
· outputArtifacts (list) –
The name of the artifact that will be the result of the action,
if any. This name might be system-generated, such as “My-
BuiltApp”, or might be defined by the user when the action is
created.
· (dict) –
Represents information about an artifact that will be worked
upon by actions in the pipeline.
· name (string) –
The artifact’s name.
· revision (string) –
The artifact’s revision ID. Depending on the type of object,
this could be a commit ID (GitHub) or a revision ID (Amazon
S3).
· location (dict) –
The location of an artifact.
· type (string) –
The type of artifact in the location.
· s3Location (dict) –
The Amazon S3 bucket that contains the artifact.
· bucketName (string) –
The name of the Amazon S3 bucket.
· objectKey (string) –
The key of the object in the Amazon S3 bucket, which
uniquely identifies the object in the bucket.
· artifactCredentials (dict) –
Represents an AWS session credentials object. These creden-
tials are temporary credentials that are issued by AWS Secure
Token Service (STS). They can be used to access input and
output artifacts in the Amazon S3 bucket used to store artifact
for the pipeline in AWS CodePipeline.
· accessKeyId (string) –
The access key for the session.
· secretAccessKey (string) –
The secret access key for the session.
· sessionToken (string) –
The token for the session.
· continuationToken (string) –
3.1. Services 537
Boto3 Documentation, Release 1.1.4
A system-generated token, such as a AWS CodeDeploy de-
ployment ID, that a job requires in order to continue the job
asynchronously.
· encryptionKey (dict) –
The AWS Key Management Service (AWS KMS) key used to
encrypt and decrypt data in the artifact store for the pipeline.
· id (string) –
The ID of the AWS KMS key.
· type (string) –
The type of AWS KMS key, such as a customer master key.
* nonce (string) –
A system-generated random number that AWS CodePipeline uses
to ensure that the job is being worked on by only one job worker.
This number must be returned in the response.
get_waiter(waiter_name)
list_action_types(**kwargs)
Gets a summary of all AWS CodePipeline action types associated with your account.
Request Syntax
response = client.list_action_types(
actionOwnerFilter='AWS'|'ThirdParty'|'Custom',
nextToken='string'
)
Parameters
• actionOwnerFilter (string) – Filters the list of action types to those created by
a specified entity.
• nextToken (string) – An identifier that was returned from the previous list action
types call, which can be used to return the next set of action types in the list.
Return type dict
Returns
Response Syntax
{
'actionTypes': [
{
'id': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'settings': {
'thirdPartyConfigurationUrl': 'string',
'entityUrlTemplate': 'string',
'executionUrlTemplate': 'string',
'revisionUrlTemplate': 'string'
},
'actionConfigurationProperties': [
{
'name': 'string',
538 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'required': True|False,
'key': True|False,
'secret': True|False,
'queryable': True|False,
'description': 'string',
'type': 'String'|'Number'|'Boolean'
},
],
'inputArtifactDetails': {
'minimumCount': 123,
'maximumCount': 123
},
'outputArtifactDetails': {
'minimumCount': 123,
'maximumCount': 123
}
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list action types action.
– actionTypes (list) –
Provides details of the action types.
* (dict) –
Returns information about the details of an action type.
· id (dict) –
Represents information about an action type.
· category (string) –
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) –
The creator of the action being called.
· provider (string) –
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) –
A string that identifies the action type.
· settings (dict) –
The settings for the action type.
· thirdPartyConfigurationUrl (string) –
The URL of a sign-up page where users can sign up for an
external service and perform initial configuration of the action
provided by that service.
· entityUrlTemplate (string) –
3.1. Services 539
Boto3 Documentation, Release 1.1.4
The URL returned to the AWS CodePipeline console that pro-
vides a deep link to the resources of the external system, such
as the configuration page for an AWS CodeDeploy deploy-
ment group. This link is provided as part of the action display
within the pipeline.
· executionUrlTemplate (string) –
The URL returned to the AWS CodePipeline console that con-
tains a link to the top-level landing page for the external sys-
tem, such as console page for AWS CodeDeploy. This link
is shown on the pipeline view page in the AWS CodePipeline
console and provides a link to the execution entity of the ex-
ternal action.
· revisionUrlTemplate (string) –
The URL returned to the AWS CodePipeline console that con-
tains a link to the page where customers can update or change
the configuration of the external action.
· actionConfigurationProperties (list) –
The configuration properties for the action type.
· (dict) –
Represents information about an action configuration prop-
erty.
· name (string) –
The name of the action configuration property.
· required (boolean) –
Whether the configuration property is a required value.
· key (boolean) –
Whether the configuration property is a key.
· secret (boolean) –
Whether the configuration property is secret. Secrets are
hidden from all calls except for GetJobDetails, GetThirdPar-
tyJobDetails, PollForJobs, and PollForThirdPartyJobs.
When updating a pipeline, passing * * * * * without changing
any other values of the action will preserve the prior value of
the secret.
· queryable (boolean) –
Indicates that the proprety will be used in conjunction with
PollForJobs. When creating a custom action, an action can
have up to one queryable property. If it has one, that property
must be both required and not secret.
If you create a pipeline with a custom action type, and that
custom action contains a queryable property, the value for
that configuration property is subject to additional restric-
tions. The value must be less than or equal to twenty (20)
characters. The value can contain only alphanumeric charac-
ters, underscores, and hyphens.
· description (string) –
The description of the action configuration property that will
be displayed to users.
540 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· type (string) –
The type of the configuration property.
· inputArtifactDetails (dict) –
The details of the input artifact for the action, such as its com-
mit ID.
· minimumCount (integer) –
The minimum number of artifacts allowed for the action type.
· maximumCount (integer) –
The maximum number of artifacts allowed for the action type.
· outputArtifactDetails (dict) –
The details of the output artifact of the action, such as its com-
mit ID.
· minimumCount (integer) –
The minimum number of artifacts allowed for the action type.
· maximumCount (integer) –
The maximum number of artifacts allowed for the action type.
– nextToken (string) –
If the amount of returned information is significantly large, an identifier
is also returned which can be used in a subsequent list action types call to
return the next set of action types in the list.
list_pipelines(**kwargs)
Gets a summary of all of the pipelines associated with your account.
Request Syntax
response = client.list_pipelines(
nextToken='string'
)
Parameters nextToken (string) – An identifier that was returned from the previous list
pipelines call, which can be used to return the next set of pipelines in the list.
Return type dict
Returns
Response Syntax
{
'pipelines': [
{
'name': 'string',
'version': 123,
'created': datetime(2015, 1, 1),
'updated': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a list pipelines action.
3.1. Services 541
Boto3 Documentation, Release 1.1.4
– pipelines (list) –
The list of pipelines.
* (dict) –
Returns a summary of a pipeline.
· name (string) –
The name of the pipeline.
· version (integer) –
The version number of the pipeline.
· created (datetime) –
The date and time the pipeline was created, in timestamp for-
mat.
· updated (datetime) –
The date and time of the last update to the pipeline, in times-
tamp format.
– nextToken (string) –
If the amount of returned information is significantly large, an identifier is
also returned which can be used in a subsequent list pipelines call to return
the next set of pipelines in the list.
poll_for_jobs(**kwargs)
Returns information about any jobs for AWS CodePipeline to act upon.
Warning: When this API is called, AWS CodePipeline returns temporary credentials for the Amazon
S3 bucket used to store artifacts for the pipeline, if the action requires access to that Amazon S3 bucket
for input or output artifacts. Additionally, this API returns any secret values defined for the action.
Request Syntax
response = client.poll_for_jobs(
actionTypeId={
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
maxBatchSize=123,
queryParam={
'string': 'string'
}
)
Parameters
• actionTypeId (dict) – [REQUIRED]
Represents information about an action type.
– category (string) – [REQUIRED]
A category defines what kind of action can be taken in the stage, and con-
strains the provider type for the action. Valid categories are limited to one
of the values below.
– owner (string) – [REQUIRED]
The creator of the action being called.
542 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– provider (string) – [REQUIRED]
The provider of the service being called by the action. Valid providers are
determined by the action category. For example, an action in the Deploy
category type might have a provider of AWS CodeDeploy, which would
be specified as CodeDeploy.
– version (string) – [REQUIRED]
A string that identifies the action type.
• maxBatchSize (integer) – The maximum number of jobs to return in a poll for
jobs call.
• queryParam (dict) – A map of property names and values. For an action type
with no queryable properties, this value must be null or an empty map. For an
action type with a queryable property, you must supply that property as a key in
the map. Only jobs whose action configuration matches the mapped value will
be returned.
– (string) –
* (string) –
Return type dict
Returns
Response Syntax
{
'jobs': [
{
'id': 'string',
'data': {
'actionTypeId': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'actionConfiguration': {
'configuration': {
'string': 'string'
}
},
'pipelineContext': {
'pipelineName': 'string',
'stage': {
'name': 'string'
},
'action': {
'name': 'string'
}
},
'inputArtifacts': [
{
'name': 'string',
'revision': 'string',
'location': {
'type': 'S3',
's3Location': {
'bucketName': 'string',
'objectKey': 'string'
}
3.1. Services 543
Boto3 Documentation, Release 1.1.4
}
},
],
'outputArtifacts': [
{
'name': 'string',
'revision': 'string',
'location': {
'type': 'S3',
's3Location': {
'bucketName': 'string',
'objectKey': 'string'
}
}
},
],
'artifactCredentials': {
'accessKeyId': 'string',
'secretAccessKey': 'string',
'sessionToken': 'string'
},
'continuationToken': 'string',
'encryptionKey': {
'id': 'string',
'type': 'KMS'
}
},
'nonce': 'string',
'accountId': 'string'
},
]
}
Response Structure
• (dict) –
Represents the output of a poll for jobs action.
– jobs (list) –
Information about the jobs to take action on.
* (dict) –
Represents information about a job.
· id (string) –
The unique system-generated ID of the job.
· data (dict) –
Additional data about a job.
· actionTypeId (dict) –
Represents information about an action type.
· category (string) –
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) –
The creator of the action being called.
544 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· provider (string) –
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) –
A string that identifies the action type.
· actionConfiguration (dict) –
Represents information about an action configuration.
· configuration (dict) –
The configuration data for the action.
· (string) –
· (string) –
· pipelineContext (dict) –
Represents information about a pipeline to a job worker.
· pipelineName (string) –
The name of the pipeline. This is a user-specified value.
Pipeline names must be unique across all pipeline names un-
der an Amazon Web Services account.
· stage (dict) –
The stage of the pipeline.
· name (string) –
The name of the stage.
· action (dict) –
Represents the context of an action within the stage of a
pipeline to a job worker.
· name (string) –
The name of the action within the context of a job.
· inputArtifacts (list) –
The artifact supplied to the job.
· (dict) –
Represents information about an artifact that will be worked
upon by actions in the pipeline.
· name (string) –
The artifact’s name.
· revision (string) –
The artifact’s revision ID. Depending on the type of object,
this could be a commit ID (GitHub) or a revision ID (Amazon
S3).
· location (dict) –
The location of an artifact.
· type (string) –
The type of artifact in the location.
· s3Location (dict) –
The Amazon S3 bucket that contains the artifact.
3.1. Services 545
Boto3 Documentation, Release 1.1.4
· bucketName (string) –
The name of the Amazon S3 bucket.
· objectKey (string) –
The key of the object in the Amazon S3 bucket, which
uniquely identifies the object in the bucket.
· outputArtifacts (list) –
The output of the job.
· (dict) –
Represents information about an artifact that will be worked
upon by actions in the pipeline.
· name (string) –
The artifact’s name.
· revision (string) –
The artifact’s revision ID. Depending on the type of object,
this could be a commit ID (GitHub) or a revision ID (Amazon
S3).
· location (dict) –
The location of an artifact.
· type (string) –
The type of artifact in the location.
· s3Location (dict) –
The Amazon S3 bucket that contains the artifact.
· bucketName (string) –
The name of the Amazon S3 bucket.
· objectKey (string) –
The key of the object in the Amazon S3 bucket, which
uniquely identifies the object in the bucket.
· artifactCredentials (dict) –
Represents an AWS session credentials object. These creden-
tials are temporary credentials that are issued by AWS Secure
Token Service (STS). They can be used to access input and
output artifacts in the Amazon S3 bucket used to store artifact
for the pipeline in AWS CodePipeline.
· accessKeyId (string) –
The access key for the session.
· secretAccessKey (string) –
The secret access key for the session.
· sessionToken (string) –
The token for the session.
· continuationToken (string) –
A system-generated token, such as a AWS CodeDeploy de-
ployment ID, that a job requires in order to continue the job
asynchronously.
· encryptionKey (dict) –
546 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Represents information about the AWS Key Management
Service (AWS KMS) key used to encrypt data in the artifact
store.
· id (string) –
The ID of the AWS KMS key.
· type (string) –
The type of AWS KMS key, such as a customer master key.
· nonce (string) –
A system-generated random number that AWS CodePipeline
uses to ensure that the job is being worked on by only one job
worker. This number must be returned in the response.
· accountId (string) –
The ID of the AWS account to use when performing the job.
poll_for_third_party_jobs(**kwargs)
Determines whether there are any third party jobs for a job worker to act on. Only used for partner actions.
Warning: When this API is called, AWS CodePipeline returns temporary credentials for the Amazon
S3 bucket used to store artifacts for the pipeline, if the action requires access to that Amazon S3 bucket
for input or output artifacts.
Request Syntax
response = client.poll_for_third_party_jobs(
actionTypeId={
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
maxBatchSize=123
)
Parameters
• actionTypeId (dict) – [REQUIRED]
Represents information about an action type.
– category (string) – [REQUIRED]
A category defines what kind of action can be taken in the stage, and con-
strains the provider type for the action. Valid categories are limited to one
of the values below.
– owner (string) – [REQUIRED]
The creator of the action being called.
– provider (string) – [REQUIRED]
The provider of the service being called by the action. Valid providers are
determined by the action category. For example, an action in the Deploy
category type might have a provider of AWS CodeDeploy, which would
be specified as CodeDeploy.
– version (string) – [REQUIRED]
A string that identifies the action type.
3.1. Services 547
Boto3 Documentation, Release 1.1.4
• maxBatchSize (integer) – The maximum number of jobs to return in a poll for
jobs call.
Return type dict
Returns
Response Syntax
{
'jobs': [
{
'clientId': 'string',
'jobId': 'string'
},
]
}
Response Structure
• (dict) –
Represents the output of a poll for third party jobs action.
– jobs (list) –
Information about the jobs to take action on.
* (dict) –
A response to a PollForThirdPartyJobs request returned by AWS
CodePipeline when there is a job to be worked upon by a partner
action.
· clientId (string) –
The clientToken portion of the clientId and clientToken pair
used to verify that the calling entity is allowed access to the
job and its details.
· jobId (string) –
The identifier used to identify the job in AWS CodePipeline.
put_action_revision(**kwargs)
Provides information to AWS CodePipeline about new revisions to a source.
Request Syntax
response = client.put_action_revision(
pipelineName='string',
stageName='string',
actionName='string',
actionRevision={
'revisionId': 'string',
'revisionChangeId': 'string',
'created': datetime(2015, 1, 1)
}
)
Parameters
• pipelineName (string) – [REQUIRED]
The name of the pipeline that will start processing the revision to the source.
• stageName (string) – [REQUIRED]
The name of the stage that contains the action that will act upon the revision.
548 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• actionName (string) – [REQUIRED]
The name of the action that will process the revision.
• actionRevision (dict) – [REQUIRED]
Represents information about the version (or revision) of an action.
– revisionId (string) – [REQUIRED]
The system-generated unique ID that identifies the revision number of the
action.
– revisionChangeId (string) –
The unique identifier of the change that set the state to this revision, for
example a deployment ID or timestamp.
– created (datetime) – [REQUIRED]
The date and time when the most recent version of the action was created,
in timestamp format.
Return type dict
Returns
Response Syntax
{
'newRevision': True|False,
'pipelineExecutionId': 'string'
}
Response Structure
• (dict) –
Represents the output of a put action revision action.
– newRevision (boolean) –
The new revision number or ID for the revision after the action completes.
– pipelineExecutionId (string) –
The ID of the current workflow state of the pipeline.
put_job_failure_result(**kwargs)
Represents the failure of a job as returned to the pipeline by a job worker. Only used for custom actions.
Request Syntax
response = client.put_job_failure_result(
jobId='string',
failureDetails={
'type': 'JobFailed'|'ConfigurationError'|'PermissionError'|'RevisionOutOfSync'|'Revi
'message': 'string',
'externalExecutionId': 'string'
}
)
Parameters
• jobId (string) – [REQUIRED]
The unique system-generated ID of the job that failed. This is the same ID
returned from PollForJobs.
• failureDetails (dict) – [REQUIRED]
The details about the failure of a job.
3.1. Services 549
Boto3 Documentation, Release 1.1.4
– type (string) – [REQUIRED]
The type of the failure.
– message (string) – [REQUIRED]
The message about the failure.
– externalExecutionId (string) –
The external ID of the run of the action that failed.
Returns None
put_job_success_result(**kwargs)
Represents the success of a job as returned to the pipeline by a job worker. Only used for custom actions.
Request Syntax
response = client.put_job_success_result(
jobId='string',
currentRevision={
'revision': 'string',
'changeIdentifier': 'string'
},
continuationToken='string',
executionDetails={
'summary': 'string',
'externalExecutionId': 'string',
'percentComplete': 123
}
)
Parameters
• jobId (string) – [REQUIRED]
The unique system-generated ID of the job that succeeded. This is the same ID
returned from PollForJobs.
• currentRevision (dict) – The ID of the current revision of the artifact success-
fully worked upon by the job.
– revision (string) – [REQUIRED]
The revision ID of the current version of an artifact.
– changeIdentifier (string) – [REQUIRED]
The change identifier for the current revision.
• continuationToken (string) – A system-generated token, such as a AWS Cod-
eDeploy deployment ID, that the successful job used to complete a job asyn-
chronously.
• executionDetails (dict) – The execution details of the successful job, such as the
actions taken by the job worker.
– summary (string) –
The summary of the current status of the actions.
– externalExecutionId (string) –
The system-generated unique ID of this action used to identify this job
worker in any external systems, such as AWS CodeDeploy.
– percentComplete (integer) –
The percentage of work completed on the action, represented on a scale of
zero to one hundred percent.
Returns None
550 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
put_third_party_job_failure_result(**kwargs)
Represents the failure of a third party job as returned to the pipeline by a job worker. Only used for partner
actions.
Request Syntax
response = client.put_third_party_job_failure_result(
jobId='string',
clientToken='string',
failureDetails={
'type': 'JobFailed'|'ConfigurationError'|'PermissionError'|'RevisionOutOfSync'|'Revi
'message': 'string',
'externalExecutionId': 'string'
}
)
Parameters
• jobId (string) – [REQUIRED]
The ID of the job that failed. This is the same ID returned from PollForThird-
PartyJobs.
• clientToken (string) – [REQUIRED]
The clientToken portion of the clientId and clientToken pair used to verify that
the calling entity is allowed access to the job and its details.
• failureDetails (dict) – [REQUIRED]
Represents information about failure details.
– type (string) – [REQUIRED]
The type of the failure.
– message (string) – [REQUIRED]
The message about the failure.
– externalExecutionId (string) –
The external ID of the run of the action that failed.
Returns None
put_third_party_job_success_result(**kwargs)
Represents the success of a third party job as returned to the pipeline by a job worker. Only used for
partner actions.
Request Syntax
response = client.put_third_party_job_success_result(
jobId='string',
clientToken='string',
currentRevision={
'revision': 'string',
'changeIdentifier': 'string'
},
continuationToken='string',
executionDetails={
'summary': 'string',
'externalExecutionId': 'string',
'percentComplete': 123
}
)
3.1. Services 551
Boto3 Documentation, Release 1.1.4
Parameters
• jobId (string) – [REQUIRED]
The ID of the job that successfully completed. This is the same ID returned from
PollForThirdPartyJobs.
• clientToken (string) – [REQUIRED]
The clientToken portion of the clientId and clientToken pair used to verify that
the calling entity is allowed access to the job and its details.
• currentRevision (dict) – Represents information about a current revision.
– revision (string) – [REQUIRED]
The revision ID of the current version of an artifact.
– changeIdentifier (string) – [REQUIRED]
The change identifier for the current revision.
• continuationToken (string) – A system-generated token, such as a AWS Cod-
eDeploy deployment ID, that a job uses in order to continue the job asyn-
chronously.
• executionDetails (dict) – The details of the actions taken and results produced
on an artifact as it passes through stages in the pipeline.
– summary (string) –
The summary of the current status of the actions.
– externalExecutionId (string) –
The system-generated unique ID of this action used to identify this job
worker in any external systems, such as AWS CodeDeploy.
– percentComplete (integer) –
The percentage of work completed on the action, represented on a scale of
zero to one hundred percent.
Returns None
start_pipeline_execution(**kwargs)
Starts the specified pipeline. Specifically, it begins processing the latest commit to the source location
specified as part of the pipeline.
Request Syntax
response = client.start_pipeline_execution(
name='string'
)
Parameters name (string) – [REQUIRED]
The name of the pipeline to start.
Return type dict
Returns
Response Syntax
{
'pipelineExecutionId': 'string'
}
Response Structure
• (dict) –
Represents the output of a start pipeline execution action.
552 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– pipelineExecutionId (string) –
The unique system-generated ID of the pipeline that was started.
update_pipeline(**kwargs)
Updates a specified pipeline with edits or changes to its structure. Use a JSON file with the pipeline
structure in conjunction with UpdatePipeline to provide the full structure of the pipeline. Updating the
pipeline increases the version number of the pipeline by 1.
Request Syntax
response = client.update_pipeline(
pipeline={
'name': 'string',
'roleArn': 'string',
'artifactStore': {
'type': 'S3',
'location': 'string',
'encryptionKey': {
'id': 'string',
'type': 'KMS'
}
},
'stages': [
{
'name': 'string',
'blockers': [
{
'name': 'string',
'type': 'Schedule'
},
],
'actions': [
{
'name': 'string',
'actionTypeId': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'runOrder': 123,
'configuration': {
'string': 'string'
},
'outputArtifacts': [
{
'name': 'string'
},
],
'inputArtifacts': [
{
'name': 'string'
},
],
'roleArn': 'string'
},
]
},
3.1. Services 553
Boto3 Documentation, Release 1.1.4
],
'version': 123
}
)
Parameters pipeline (dict) – [REQUIRED]
The name of the pipeline to be updated.
• name (string) – [REQUIRED]
The name of the action to be performed.
• roleArn (string) – [REQUIRED]
The Amazon Resource Name (ARN) for AWS CodePipeline to use to either
perform actions with no actionRoleArn, or to use to assume roles for actions
with an actionRoleArn.
• artifactStore (dict) – [REQUIRED]
The Amazon S3 location where artifacts are stored for the pipeline. If this Ama-
zon S3 bucket is created manually, it must meet the requirements for AWS Code-
Pipeline. For more information, see the Concepts.
– type (string) – [REQUIRED]
The type of the artifact store, such as S3.
– location (string) – [REQUIRED]
The location for storing the artifacts for a pipeline, such as an S3 bucket
or folder.
– encryptionKey (dict) –
The AWS Key Management Service (AWS KMS) key used to encrypt the
data in the artifact store. If this is undefined, the default key for Amazon
S3 is used.
* id (string) – [REQUIRED]
The ID of the AWS KMS key.
* type (string) – [REQUIRED]
The type of AWS KMS key, such as a customer master key.
• stages (list) – [REQUIRED]
The stage in which to perform the action.
– (dict) –
Represents information about a stage and its definition.
* name (string) – [REQUIRED]
The name of the stage.
* blockers (list) –
The gates included in a stage.
· (dict) –
Represents information about a gate declaration.
· name (string) – [REQUIRED]
The name of the gate declaration.
· type (string) – [REQUIRED]
The type of the gate declaration.
554 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* actions (list) – [REQUIRED]
The actions included in a stage.
· (dict) –
Represents information about an action declaration.
· name (string) – [REQUIRED]
The action declaration’s name.
· actionTypeId (dict) – [REQUIRED]
The configuration information for the action type.
· category (string) – [REQUIRED]
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) – [REQUIRED]
The creator of the action being called.
· provider (string) – [REQUIRED]
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) – [REQUIRED]
A string that identifies the action type.
· runOrder (integer) –
The order in which actions are run.
· configuration (dict) –
The action declaration’s configuration.
· (string) –
· (string) –
· outputArtifacts (list) –
The name or ID of the result of the action declaration, such as
a test or build artifact.
· (dict) –
Represents information about the output of an action.
· name (string) – [REQUIRED]
The name of the output of an artifact, such as “My App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
Output artifact names must be unique within a pipeline.
· inputArtifacts (list) –
The name or ID of the artifact consumed by the action, such
as a test or build artifact.
· (dict) –
3.1. Services 555
Boto3 Documentation, Release 1.1.4
Represents information about an artifact to be worked on,
such as a test or build artifact.
· name (string) – [REQUIRED]
The name of the artifact to be worked on, for example, “My
App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
· roleArn (string) –
The ARN of the IAM service role that will perform the de-
clared action. This is assumed through the roleArn for the
pipeline.
• version (integer) –
The version number of the pipeline. A new pipeline always has a version number
of 1. This number is automatically incremented when a pipeline is updated.
Return type dict
Returns
Response Syntax
{
'pipeline': {
'name': 'string',
'roleArn': 'string',
'artifactStore': {
'type': 'S3',
'location': 'string',
'encryptionKey': {
'id': 'string',
'type': 'KMS'
}
},
'stages': [
{
'name': 'string',
'blockers': [
{
'name': 'string',
'type': 'Schedule'
},
],
'actions': [
{
'name': 'string',
'actionTypeId': {
'category': 'Source'|'Build'|'Deploy'|'Test'|'Invoke',
'owner': 'AWS'|'ThirdParty'|'Custom',
'provider': 'string',
'version': 'string'
},
'runOrder': 123,
'configuration': {
556 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string': 'string'
},
'outputArtifacts': [
{
'name': 'string'
},
],
'inputArtifacts': [
{
'name': 'string'
},
],
'roleArn': 'string'
},
]
},
],
'version': 123
}
}
Response Structure
• (dict) –
Represents the output of an update pipeline action.
– pipeline (dict) –
The structure of the updated pipeline.
* name (string) –
The name of the action to be performed.
* roleArn (string) –
The Amazon Resource Name (ARN) for AWS CodePipeline to use
to either perform actions with no actionRoleArn, or to use to assume
roles for actions with an actionRoleArn.
* artifactStore (dict) –
The Amazon S3 location where artifacts are stored for the pipeline.
If this Amazon S3 bucket is created manually, it must meet the re-
quirements for AWS CodePipeline. For more information, see the
Concepts.
· type (string) –
The type of the artifact store, such as S3.
· location (string) –
The location for storing the artifacts for a pipeline, such as an
S3 bucket or folder.
· encryptionKey (dict) –
The AWS Key Management Service (AWS KMS) key used to
encrypt the data in the artifact store. If this is undefined, the
default key for Amazon S3 is used.
· id (string) –
The ID of the AWS KMS key.
· type (string) –
The type of AWS KMS key, such as a customer master key.
3.1. Services 557
Boto3 Documentation, Release 1.1.4
* stages (list) –
The stage in which to perform the action.
· (dict) –
Represents information about a stage and its definition.
· name (string) –
The name of the stage.
· blockers (list) –
The gates included in a stage.
· (dict) –
Represents information about a gate declaration.
· name (string) –
The name of the gate declaration.
· type (string) –
The type of the gate declaration.
· actions (list) –
The actions included in a stage.
· (dict) –
Represents information about an action declaration.
· name (string) –
The action declaration’s name.
· actionTypeId (dict) –
The configuration information for the action type.
· category (string) –
A category defines what kind of action can be taken in the
stage, and constrains the provider type for the action. Valid
categories are limited to one of the values below.
· owner (string) –
The creator of the action being called.
· provider (string) –
The provider of the service being called by the action. Valid
providers are determined by the action category. For example,
an action in the Deploy category type might have a provider of
AWS CodeDeploy, which would be specified as CodeDeploy.
· version (string) –
A string that identifies the action type.
· runOrder (integer) –
The order in which actions are run.
· configuration (dict) –
The action declaration’s configuration.
· (string) –
· (string) –
· outputArtifacts (list) –
The name or ID of the result of the action declaration, such as
a test or build artifact.
558 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Represents information about the output of an action.
· name (string) –
The name of the output of an artifact, such as “My App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
Output artifact names must be unique within a pipeline.
· inputArtifacts (list) –
The name or ID of the artifact consumed by the action, such
as a test or build artifact.
· (dict) –
Represents information about an artifact to be worked on,
such as a test or build artifact.
· name (string) –
The name of the artifact to be worked on, for example, “My
App”.
The input artifact of an action must exactly match the output
artifact declared in a preceding action, but the input artifact
does not have to be the next action in strict sequence from the
action that provided the output artifact. Actions in parallel can
declare different output artifacts, which are in turn consumed
by different following actions.
· roleArn (string) –
The ARN of the IAM service role that will perform the de-
clared action. This is assumed through the roleArn for the
pipeline.
* version (integer) –
The version number of the pipeline. A new pipeline always has
a version number of 1. This number is automatically incremented
when a pipeline is updated.
CognitoIdentity
Table of Contents
• CognitoIdentity
– Client
Client
class CognitoIdentity.Client
A low-level client representing Amazon Cognito Identity:
3.1. Services 559
Boto3 Documentation, Release 1.1.4
import boto3
client = boto3.client('cognito-identity')
These are the available methods:
•can_paginate()
•create_identity_pool()
•delete_identities()
•delete_identity_pool()
•describe_identity()
•describe_identity_pool()
•generate_presigned_url()
•get_credentials_for_identity()
•get_id()
•get_identity_pool_roles()
•get_open_id_token()
•get_open_id_token_for_developer_identity()
•get_paginator()
•get_waiter()
•list_identities()
•list_identity_pools()
•lookup_developer_identity()
•merge_developer_identities()
•set_identity_pool_roles()
•unlink_developer_identity()
•unlink_identity()
•update_identity_pool()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
create_identity_pool(**kwargs)
Creates a new identity pool. The identity pool is a store of user identity information that is
specific to your AWS account. The limit on identity pools is 60 per account. The keys for
SupportedLoginProviders are as follows:
•Facebook: graph.facebook.com
•Google: accounts.google.com
•Amazon: www.amazon.com
•Twitter: api.twitter.com
•Digits: www.digits.com
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.create_identity_pool(
IdentityPoolName='string',
AllowUnauthenticatedIdentities=True|False,
SupportedLoginProviders={
'string': 'string'
},
560 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
DeveloperProviderName='string',
OpenIdConnectProviderARNs=[
'string',
]
)
Parameters
• IdentityPoolName (string) – [REQUIRED]
A string that you provide.
• AllowUnauthenticatedIdentities (boolean) – [REQUIRED]
TRUE if the identity pool supports unauthenticated logins.
• SupportedLoginProviders (dict) – Optional key:value pairs mapping provider
names to provider app IDs.
– (string) –
* (string) –
• DeveloperProviderName (string) – The “domain” by which Cognito will re-
fer to your users. This name acts as a placeholder that allows your backend
and the Cognito service to communicate about the developer provider. For the
DeveloperProviderName , you can use letters as well as period (. ), un-
derscore (_ ), and dash (- ).
Once you have set a developer provider name, you cannot change it. Please take
care in setting this parameter.
• OpenIdConnectProviderARNs (list) – A list of OpendID Connect provider
ARNs.
– (string) –
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string',
'IdentityPoolName': 'string',
'AllowUnauthenticatedIdentities': True|False,
'SupportedLoginProviders': {
'string': 'string'
},
'DeveloperProviderName': 'string',
'OpenIdConnectProviderARNs': [
'string',
]
}
Response Structure
• (dict) – An object representing a Cognito identity pool.
– IdentityPoolId (string) – An identity pool ID in the format RE-
GION:GUID.
– IdentityPoolName (string) –
A string that you provide.
– AllowUnauthenticatedIdentities (boolean) – TRUE if the identity pool
supports unauthenticated logins.
– SupportedLoginProviders (dict) –
Optional key:value pairs mapping provider names to provider app IDs.
3.1. Services 561
Boto3 Documentation, Release 1.1.4
* (string) –
· (string) –
– DeveloperProviderName (string) –
The “domain” by which Cognito will refer to your users.
– OpenIdConnectProviderARNs (list) –
A list of OpendID Connect provider ARNs.
* (string) –
delete_identities(**kwargs)
Deletes identities from an identity pool. You can specify a list of 1-60 identities that you want to delete.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.delete_identities(
IdentityIdsToDelete=[
'string',
]
)
Parameters IdentityIdsToDelete (list) – [REQUIRED]
A list of 1-60 identities that you want to delete.
• (string) –
Return type dict
Returns
Response Syntax
{
'UnprocessedIdentityIds': [
{
'IdentityId': 'string',
'ErrorCode': 'AccessDenied'|'InternalServerError'
},
]
}
Response Structure
• (dict) –
Returned in response to a successful DeleteIdentities operation.
– UnprocessedIdentityIds (list) –
An array of UnprocessedIdentityId objects, each of which contains an Er-
rorCode and IdentityId.
* (dict) –
An array of UnprocessedIdentityId objects, each of which contains
an ErrorCode and IdentityId.
· IdentityId (string) –
A unique identifier in the format REGION:GUID.
· ErrorCode (string) –
The error code indicating the type of error that occurred.
562 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
delete_identity_pool(**kwargs)
Deletes a user pool. Once a pool is deleted, users will not be able to authenticate with the pool.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.delete_identity_pool(
IdentityPoolId='string'
)
Parameters IdentityPoolId (string) – [REQUIRED] An identity pool ID in the format RE-
GION:GUID.
Returns None
describe_identity(**kwargs)
Returns metadata related to the given identity, including when the identity was created and any associated
linked logins.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.describe_identity(
IdentityId='string'
)
Parameters IdentityId (string) – [REQUIRED]
A unique identifier in the format REGION:GUID.
Return type dict
Returns
Response Syntax
{
'IdentityId': 'string',
'Logins': [
'string',
],
'CreationDate': datetime(2015, 1, 1),
'LastModifiedDate': datetime(2015, 1, 1)
}
Response Structure
• (dict) – A description of the identity.
– IdentityId (string) – A unique identifier in the format REGION:GUID.
– Logins (list) – A set of optional name-value pairs that map provider names
to provider tokens.
* (string) –
– CreationDate (datetime) –
Date on which the identity was created.
– LastModifiedDate (datetime) –
Date on which the identity was last modified.
describe_identity_pool(**kwargs)
Gets details about a particular identity pool, including the pool name, ID description, creation date, and
current number of users.
3.1. Services 563
Boto3 Documentation, Release 1.1.4
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.describe_identity_pool(
IdentityPoolId='string'
)
Parameters IdentityPoolId (string) – [REQUIRED] An identity pool ID in the format RE-
GION:GUID.
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string',
'IdentityPoolName': 'string',
'AllowUnauthenticatedIdentities': True|False,
'SupportedLoginProviders': {
'string': 'string'
},
'DeveloperProviderName': 'string',
'OpenIdConnectProviderARNs': [
'string',
]
}
Response Structure
• (dict) – An object representing a Cognito identity pool.
– IdentityPoolId (string) – An identity pool ID in the format RE-
GION:GUID.
– IdentityPoolName (string) –
A string that you provide.
– AllowUnauthenticatedIdentities (boolean) – TRUE if the identity pool
supports unauthenticated logins.
– SupportedLoginProviders (dict) –
Optional key:value pairs mapping provider names to provider app IDs.
* (string) –
· (string) –
– DeveloperProviderName (string) –
The “domain” by which Cognito will refer to your users.
– OpenIdConnectProviderARNs (list) –
A list of OpendID Connect provider ARNs.
* (string) –
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
564 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns The presigned url
get_credentials_for_identity(**kwargs)
Returns credentials for the provided identity ID. Any provided logins will be validated against supported
login providers. If the token is for cognito-identity.amazonaws.com, it will be passed through to AWS
Security Token Service with the appropriate role for the token.
This is a public API. You do not need any credentials to call this API.
Request Syntax
response = client.get_credentials_for_identity(
IdentityId='string',
Logins={
'string': 'string'
}
)
Parameters
• IdentityId (string) – [REQUIRED]
A unique identifier in the format REGION:GUID.
• Logins (dict) – A set of optional name-value pairs that map provider names to
provider tokens.
– (string) –
* (string) –
Return type dict
Returns
Response Syntax
{
'IdentityId': 'string',
'Credentials': {
'AccessKeyId': 'string',
'SecretKey': 'string',
'SessionToken': 'string',
'Expiration': datetime(2015, 1, 1)
}
}
Response Structure
• (dict) –
Returned in response to a successful GetCredentialsForIdentity oper-
ation.
– IdentityId (string) –
A unique identifier in the format REGION:GUID.
– Credentials (dict) –
Credentials for the provided identity ID.
* AccessKeyId (string) –
The Access Key portion of the credentials.
* SecretKey (string) –
The Secret Access Key portion of the credentials
* SessionToken (string) –
The Session Token portion of the credentials
3.1. Services 565
Boto3 Documentation, Release 1.1.4
* Expiration (datetime) –
The date at which these credentials will expire.
get_id(**kwargs)
Generates (or retrieves) a Cognito ID. Supplying multiple logins will create an implicit linked account.
This is a public API. You do not need any credentials to call this API.
Request Syntax
response = client.get_id(
AccountId='string',
IdentityPoolId='string',
Logins={
'string': 'string'
}
)
Parameters
• AccountId (string) – A standard AWS account ID (9+ digits).
• IdentityPoolId (string) – [REQUIRED] An identity pool ID in the format RE-
GION:GUID.
• Logins (dict) – A set of optional name-value pairs that map provider names to
provider tokens.
The available provider names for Logins are as follows:
– Facebook: graph.facebook.com
– Google: accounts.google.com
– Amazon: www.amazon.com
– Twitter: api.twitter.com
– Digits: www.digits.com
– (string) –
* (string) –
Return type dict
Returns
Response Syntax
{
'IdentityId': 'string'
}
Response Structure
• (dict) – Returned in response to a GetId request.
– IdentityId (string) – A unique identifier in the format REGION:GUID.
get_identity_pool_roles(**kwargs)
Gets the roles for an identity pool.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.get_identity_pool_roles(
IdentityPoolId='string'
)
566 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters IdentityPoolId (string) – [REQUIRED]
An identity pool ID in the format REGION:GUID.
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string',
'Roles': {
'string': 'string'
}
}
Response Structure
• (dict) –
Returned in response to a successful GetIdentityPoolRoles operation.
– IdentityPoolId (string) –
An identity pool ID in the format REGION:GUID.
– Roles (dict) –
The map of roles associated with this pool. Currently only authenticated
and unauthenticated roles are supported.
* (string) –
· (string) –
get_open_id_token(**kwargs)
Gets an OpenID token, using a known Cognito ID. This known Cognito ID is returned by GetId . You can
optionally add additional logins for the identity. Supplying multiple logins creates an implicit link.
The OpenId token is valid for 15 minutes.
This is a public API. You do not need any credentials to call this API.
Request Syntax
response = client.get_open_id_token(
IdentityId='string',
Logins={
'string': 'string'
}
)
Parameters
• IdentityId (string) – [REQUIRED] A unique identifier in the format RE-
GION:GUID.
• Logins (dict) – A set of optional name-value pairs that map provider names
to provider tokens. When using graph.facebook.com and www.amazon.com,
supply the access_token returned from the provider’s authflow. For ac-
counts.google.com or any other OpenId Connect provider, always include the
id_token.
– (string) –
* (string) –
Return type dict
Returns
Response Syntax
3.1. Services 567
Boto3 Documentation, Release 1.1.4
{
'IdentityId': 'string',
'Token': 'string'
}
Response Structure
• (dict) – Returned in response to a successful GetOpenIdToken request.
– IdentityId (string) – A unique identifier in the format REGION:GUID.
Note that the IdentityId returned may not match the one passed on input.
– Token (string) – An OpenID token, valid for 15 minutes.
get_open_id_token_for_developer_identity(**kwargs)
Registers (or retrieves) a Cognito IdentityId and an OpenID Connect token for a user authenticated
by your backend authentication process. Supplying multiple logins will create an implicit linked account.
You can only specify one developer provider as part of the Logins map, which is linked to the identity
pool. The developer provider is the “domain” by which Cognito will refer to your users.
You can use GetOpenIdTokenForDeveloperIdentity to create a new identity and to link new
logins (that is, user credentials issued by a public provider or developer provider) to an existing identity.
When you want to create a new identity, the IdentityId should be null. When you want to associate a
new login with an existing authenticated/unauthenticated identity, you can do so by providing the existing
IdentityId . This API will create the identity in the specified IdentityPoolId .
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.get_open_id_token_for_developer_identity(
IdentityPoolId='string',
IdentityId='string',
Logins={
'string': 'string'
},
TokenDuration=123
)
Parameters
• IdentityPoolId (string) – [REQUIRED]
An identity pool ID in the format REGION:GUID.
• IdentityId (string) – A unique identifier in the format REGION:GUID.
• Logins (dict) – [REQUIRED]
A set of optional name-value pairs that map provider names to provider
tokens. Each name-value pair represents a user from a public provider
or developer provider. If the user is from a developer provider, the
name-value pair will follow the syntax "developer_provider_name":
"developer_user_identifier" . The developer provider is the “do-
main” by which Cognito will refer to your users; you provided this domain while
creating/updating the identity pool. The developer user identifier is an identifier
from your backend that uniquely identifies a user. When you create an identity
pool, you can specify the supported logins.
– (string) –
* (string) –
• TokenDuration (integer) – The expiration time of the token, in seconds. You
can specify a custom expiration time for the token so that you can cache it. If
you don’t provide an expiration time, the token is valid for 15 minutes. You can
568 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
exchange the token with Amazon STS for temporary AWS credentials, which
are valid for a maximum of one hour. The maximum token duration you can set
is 24 hours. You should take care in setting the expiration time for a token, as
there are significant security implications: an attacker could use a leaked token
to access your AWS resources for the token’s duration.
Return type dict
Returns
Response Syntax
{
'IdentityId': 'string',
'Token': 'string'
}
Response Structure
• (dict) –
Returned in response to a successful GetOpenIdTokenForDeveloperIdentity
request.
– IdentityId (string) –
A unique identifier in the format REGION:GUID.
– Token (string) –
An OpenID token.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
list_identities(**kwargs)
Lists the identities in a pool.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.list_identities(
IdentityPoolId='string',
MaxResults=123,
NextToken='string',
HideDisabled=True|False
)
Parameters
• IdentityPoolId (string) – [REQUIRED] An identity pool ID in the format RE-
GION:GUID.
3.1. Services 569
Boto3 Documentation, Release 1.1.4
• MaxResults (integer) – [REQUIRED] The maximum number of identities to
return.
• NextToken (string) – A pagination token.
• HideDisabled (boolean) – An optional boolean parameter that allows you to
hide disabled identities. If omitted, the ListIdentities API will include disabled
identities in the response.
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string',
'Identities': [
{
'IdentityId': 'string',
'Logins': [
'string',
],
'CreationDate': datetime(2015, 1, 1),
'LastModifiedDate': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
• (dict) – The response to a ListIdentities request.
– IdentityPoolId (string) – An identity pool ID in the format RE-
GION:GUID.
– Identities (list) – An object containing a set of identities and associated
mappings.
* (dict) – A description of the identity.
· IdentityId (string) – A unique identifier in the format RE-
GION:GUID.
· Logins (list) – A set of optional name-value pairs that map
provider names to provider tokens.
· (string) –
· CreationDate (datetime) –
Date on which the identity was created.
· LastModifiedDate (datetime) –
Date on which the identity was last modified.
– NextToken (string) – A pagination token.
list_identity_pools(**kwargs)
Lists all of the Cognito identity pools registered for your account.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.list_identity_pools(
MaxResults=123,
NextToken='string'
)
Parameters
570 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• MaxResults (integer) – [REQUIRED] The maximum number of identities to
return.
• NextToken (string) – A pagination token.
Return type dict
Returns
Response Syntax
{
'IdentityPools': [
{
'IdentityPoolId': 'string',
'IdentityPoolName': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) – The result of a successful ListIdentityPools action.
– IdentityPools (list) – The identity pools returned by the ListIdentityPools
action.
* (dict) – A description of the identity pool.
· IdentityPoolId (string) – An identity pool ID in the format
REGION:GUID.
· IdentityPoolName (string) – A string that you provide.
– NextToken (string) – A pagination token.
lookup_developer_identity(**kwargs)
Retrieves the IdentityID associated with a DeveloperUserIdentifier or the list of
DeveloperUserIdentifier s associated with an IdentityId for an existing identity. Either
IdentityID or DeveloperUserIdentifier must not be null. If you supply only one of these
values, the other value will be searched in the database and returned as a part of the response. If you
supply both, DeveloperUserIdentifier will be matched against IdentityID . If the values are
verified against the database, the response returns both values and is the same as the request. Otherwise a
ResourceConflictException is thrown.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.lookup_developer_identity(
IdentityPoolId='string',
IdentityId='string',
DeveloperUserIdentifier='string',
MaxResults=123,
NextToken='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED]
An identity pool ID in the format REGION:GUID.
• IdentityId (string) – A unique identifier in the format REGION:GUID.
• DeveloperUserIdentifier (string) – A unique ID used by your backend authen-
tication process to identify a user. Typically, a developer identity provider would
issue many developer user identifiers, in keeping with the number of users.
• MaxResults (integer) – The maximum number of identities to return.
3.1. Services 571
Boto3 Documentation, Release 1.1.4
• NextToken (string) – A pagination token. The first call you make will have
NextToken set to null. After that the service will return NextToken values
as needed. For example, let’s say you make a request with MaxResults set to
10, and there are 20 matches in the database. The service will return a pagination
token as a part of the response. This token can be used to call the API again and
get results starting from the 11th match.
Return type dict
Returns
Response Syntax
{
'IdentityId': 'string',
'DeveloperUserIdentifierList': [
'string',
],
'NextToken': 'string'
}
Response Structure
• (dict) –
Returned in response to a successful LookupDeveloperIdentity action.
– IdentityId (string) –
A unique identifier in the format REGION:GUID.
– DeveloperUserIdentifierList (list) –
This is the list of developer user identifiers associated with an identity
ID. Cognito supports the association of multiple developer user identifiers
with an identity ID.
* (string) –
– NextToken (string) –
A pagination token. The first call you make will have NextToken set to
null. After that the service will return NextToken values as needed. For
example, let’s say you make a request with MaxResults set to 10, and
there are 20 matches in the database. The service will return a pagination
token as a part of the response. This token can be used to call the API
again and get results starting from the 11th match.
merge_developer_identities(**kwargs)
Merges two users having different IdentityId s, existing in the same identity pool, and identi-
fied by the same developer provider. You can use this action to request that discrete users be merged
and identified as a single user in the Cognito environment. Cognito associates the given source user
(SourceUserIdentifier ) with the IdentityId of the DestinationUserIdentifier .
Only developer-authenticated users can be merged. If the users to be merged are associated with the same
public provider, but as two different users, an exception will be thrown.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.merge_developer_identities(
SourceUserIdentifier='string',
DestinationUserIdentifier='string',
DeveloperProviderName='string',
IdentityPoolId='string'
)
572 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• SourceUserIdentifier (string) – [REQUIRED]
User identifier for the source user. The value should be a
DeveloperUserIdentifier .
• DestinationUserIdentifier (string) – [REQUIRED]
User identifier for the destination user. The value should be a
DeveloperUserIdentifier .
• DeveloperProviderName (string) – [REQUIRED]
The “domain” by which Cognito will refer to your users. This is a (pseudo)
domain name that you provide while creating an identity pool. This name acts as
a placeholder that allows your backend and the Cognito service to communicate
about the developer provider. For the DeveloperProviderName , you can
use letters as well as period (.), underscore (_), and dash (-).
• IdentityPoolId (string) – [REQUIRED]
An identity pool ID in the format REGION:GUID.
Return type dict
Returns
Response Syntax
{
'IdentityId': 'string'
}
Response Structure
• (dict) –
Returned in response to a successful MergeDeveloperIdentities action.
– IdentityId (string) –
A unique identifier in the format REGION:GUID.
set_identity_pool_roles(**kwargs)
Sets the roles for an identity pool. These roles are used when making calls to
GetCredentialsForIdentity action.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.set_identity_pool_roles(
IdentityPoolId='string',
Roles={
'string': 'string'
}
)
Parameters
• IdentityPoolId (string) – [REQUIRED]
An identity pool ID in the format REGION:GUID.
• Roles (dict) – [REQUIRED]
The map of roles associated with this pool. For a given role, the key will be
either “authenticated” or “unauthenticated” and the value will be the Role ARN.
– (string) –
* (string) –
3.1. Services 573
Boto3 Documentation, Release 1.1.4
Returns None
unlink_developer_identity(**kwargs)
Unlinks a DeveloperUserIdentifier from an existing identity. Unlinked developer users will be
considered new identities next time they are seen. If, for a given Cognito identity, you remove all federated
identities as well as the developer user identifier, the Cognito identity becomes inaccessible.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.unlink_developer_identity(
IdentityId='string',
IdentityPoolId='string',
DeveloperProviderName='string',
DeveloperUserIdentifier='string'
)
Parameters
• IdentityId (string) – [REQUIRED]
A unique identifier in the format REGION:GUID.
• IdentityPoolId (string) – [REQUIRED]
An identity pool ID in the format REGION:GUID.
• DeveloperProviderName (string) – [REQUIRED]
The “domain” by which Cognito will refer to your users.
• DeveloperUserIdentifier (string) – [REQUIRED] A unique ID used by your
backend authentication process to identify a user.
Returns None
unlink_identity(**kwargs)
Unlinks a federated identity from an existing account. Unlinked logins will be considered new identities
next time they are seen. Removing the last linked login will make this identity inaccessible.
This is a public API. You do not need any credentials to call this API.
Request Syntax
response = client.unlink_identity(
IdentityId='string',
Logins={
'string': 'string'
},
LoginsToRemove=[
'string',
]
)
Parameters
• IdentityId (string) – [REQUIRED] A unique identifier in the format RE-
GION:GUID.
• Logins (dict) – [REQUIRED] A set of optional name-value pairs that map
provider names to provider tokens.
– (string) –
* (string) –
• LoginsToRemove (list) – [REQUIRED] Provider names to unlink from this
identity.
– (string) –
574 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns None
update_identity_pool(**kwargs)
Updates a user pool.
You must use AWS Developer credentials to call this API.
Request Syntax
response = client.update_identity_pool(
IdentityPoolId='string',
IdentityPoolName='string',
AllowUnauthenticatedIdentities=True|False,
SupportedLoginProviders={
'string': 'string'
},
DeveloperProviderName='string',
OpenIdConnectProviderARNs=[
'string',
]
)
Parameters
• IdentityPoolId (string) – [REQUIRED] An identity pool ID in the format RE-
GION:GUID.
• IdentityPoolName (string) – [REQUIRED]
A string that you provide.
• AllowUnauthenticatedIdentities (boolean) – [REQUIRED] TRUE if the iden-
tity pool supports unauthenticated logins.
• SupportedLoginProviders (dict) – Optional key:value pairs mapping provider
names to provider app IDs.
– (string) –
* (string) –
• DeveloperProviderName (string) – The “domain” by which Cognito will refer
to your users.
• OpenIdConnectProviderARNs (list) – A list of OpendID Connect provider
ARNs.
– (string) –
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string',
'IdentityPoolName': 'string',
'AllowUnauthenticatedIdentities': True|False,
'SupportedLoginProviders': {
'string': 'string'
},
'DeveloperProviderName': 'string',
'OpenIdConnectProviderARNs': [
'string',
]
}
Response Structure
• (dict) – An object representing a Cognito identity pool.
3.1. Services 575
Boto3 Documentation, Release 1.1.4
– IdentityPoolId (string) – An identity pool ID in the format RE-
GION:GUID.
– IdentityPoolName (string) –
A string that you provide.
– AllowUnauthenticatedIdentities (boolean) – TRUE if the identity pool
supports unauthenticated logins.
– SupportedLoginProviders (dict) –
Optional key:value pairs mapping provider names to provider app IDs.
* (string) –
· (string) –
– DeveloperProviderName (string) –
The “domain” by which Cognito will refer to your users.
– OpenIdConnectProviderARNs (list) –
A list of OpendID Connect provider ARNs.
* (string) –
CognitoSync
Table of Contents
• CognitoSync
– Client
Client
class CognitoSync.Client
A low-level client representing Amazon Cognito Sync:
import boto3
client = boto3.client('cognito-sync')
These are the available methods:
•bulk_publish()
•can_paginate()
•delete_dataset()
•describe_dataset()
•describe_identity_pool_usage()
•describe_identity_usage()
•generate_presigned_url()
•get_bulk_publish_details()
•get_cognito_events()
•get_identity_pool_configuration()
•get_paginator()
•get_waiter()
•list_datasets()
•list_identity_pool_usage()
•list_records()
•register_device()
576 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
•set_cognito_events()
•set_identity_pool_configuration()
•subscribe_to_dataset()
•unsubscribe_from_dataset()
•update_records()
bulk_publish(**kwargs)
Initiates a bulk publish of all existing datasets for an Identity Pool to the configured stream. Customers are
limited to one successful bulk publish per 24 hours. Bulk publish is an asynchronous request, customers
can see the status of the request via the GetBulkPublishDetails operation.
This API can only be called with developer credentials. You cannot call this API with the temporary user
credentials provided by Cognito Identity.
Request Syntax
response = client.bulk_publish(
IdentityPoolId='string'
)
Parameters IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon Cog-
nito. GUID generation is unique within a region.
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string'
}
Response Structure
• (dict) – The output for the BulkPublish operation.
– IdentityPoolId (string) – A name-spaced GUID (for example, us-east-
1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon
Cognito. GUID generation is unique within a region.
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
delete_dataset(**kwargs)
Deletes the specific dataset. The dataset will be deleted permanently, and the action can’t be undone.
Datasets that this dataset was merged with will no longer report the merge. Any subsequent operation on
this dataset will result in a ResourceNotFoundException.
This API can be called with temporary user credentials provided by Cognito Identity or with developer
credentials.
Request Syntax
3.1. Services 577
Boto3 Documentation, Release 1.1.4
response = client.delete_dataset(
IdentityPoolId='string',
IdentityId='string',
DatasetName='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Ama-
zon Cognito. GUID generation is unique within a region.
• IdentityId (string) – [REQUIRED] A name-spaced GUID (for example, us-
east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon
Cognito. GUID generation is unique within a region.
• DatasetName (string) – [REQUIRED] A string of up to 128 characters. Al-
lowed characters are a-z, A-Z, 0-9, ‘_’ (underscore), ‘-‘ (dash), and ‘.’ (dot).
Return type dict
Returns
Response Syntax
{
'Dataset': {
'IdentityId': 'string',
'DatasetName': 'string',
'CreationDate': datetime(2015, 1, 1),
'LastModifiedDate': datetime(2015, 1, 1),
'LastModifiedBy': 'string',
'DataStorage': 123,
'NumRecords': 123
}
}
Response Structure
• (dict) – Response to a successful DeleteDataset request.
– Dataset (dict) – A collection of data for an identity pool. An identity pool
can have multiple datasets. A dataset is per identity and can be general or
associated with a particular entity in an application (like a saved game).
Datasets are automatically created if they don’t exist. Data is synced by
dataset, and a dataset can hold up to 1MB of key-value pairs.
* IdentityId (string) – A name-spaced GUID (for example, us-east-
1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by
Amazon Cognito. GUID generation is unique within a region.
* DatasetName (string) – A string of up to 128 characters. Allowed
characters are a-z, A-Z, 0-9, ‘_’ (underscore), ‘-‘ (dash), and ‘.’
(dot).
* CreationDate (datetime) – Date on which the dataset was created.
* LastModifiedDate (datetime) – Date when the dataset was last
modified.
* LastModifiedBy (string) – The device that made the last change to
this dataset.
* DataStorage (integer) – Total size in bytes of the records in this
dataset.
* NumRecords (integer) – Number of records in this dataset.
describe_dataset(**kwargs)
Gets meta data about a dataset by identity and dataset name. With Amazon Cognito Sync, each identity
578 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
has access only to its own data. Thus, the credentials used to make this API call need to have access to
the identity data.
This API can be called with temporary user credentials provided by Cognito Identity or with developer
credentials. You should use Cognito Identity credentials to make this API call.
Request Syntax
response = client.describe_dataset(
IdentityPoolId='string',
IdentityId='string',
DatasetName='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Ama-
zon Cognito. GUID generation is unique within a region.
• IdentityId (string) – [REQUIRED] A name-spaced GUID (for example, us-
east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon
Cognito. GUID generation is unique within a region.
• DatasetName (string) – [REQUIRED] A string of up to 128 characters. Al-
lowed characters are a-z, A-Z, 0-9, ‘_’ (underscore), ‘-‘ (dash), and ‘.’ (dot).
Return type dict
Returns
Response Syntax
{
'Dataset': {
'IdentityId': 'string',
'DatasetName': 'string',
'CreationDate': datetime(2015, 1, 1),
'LastModifiedDate': datetime(2015, 1, 1),
'LastModifiedBy': 'string',
'DataStorage': 123,
'NumRecords': 123
}
}
Response Structure
• (dict) – Response to a successful DescribeDataset request.
– Dataset (dict) – Meta data for a collection of data for an identity. An
identity can have multiple datasets. A dataset can be general or associated
with a particular entity in an application (like a saved game). Datasets are
automatically created if they don’t exist. Data is synced by dataset, and a
dataset can hold up to 1MB of key-value pairs.
* IdentityId (string) – A name-spaced GUID (for example, us-east-
1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by
Amazon Cognito. GUID generation is unique within a region.
* DatasetName (string) – A string of up to 128 characters. Allowed
characters are a-z, A-Z, 0-9, ‘_’ (underscore), ‘-‘ (dash), and ‘.’
(dot).
* CreationDate (datetime) – Date on which the dataset was created.
* LastModifiedDate (datetime) – Date when the dataset was last
modified.
3.1. Services 579
Boto3 Documentation, Release 1.1.4
* LastModifiedBy (string) – The device that made the last change to
this dataset.
* DataStorage (integer) – Total size in bytes of the records in this
dataset.
* NumRecords (integer) – Number of records in this dataset.
describe_identity_pool_usage(**kwargs)
Gets usage details (for example, data storage) about a particular identity pool.
This API can only be called with developer credentials. You cannot call this API with the temporary user
credentials provided by Cognito Identity.
Request Syntax
response = client.describe_identity_pool_usage(
IdentityPoolId='string'
)
Parameters IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon Cog-
nito. GUID generation is unique within a region.
Return type dict
Returns
Response Syntax
{
'IdentityPoolUsage': {
'IdentityPoolId': 'string',
'SyncSessionsCount': 123,
'DataStorage': 123,
'LastModifiedDate': datetime(2015, 1, 1)
}
}
Response Structure
• (dict) – Response to a successful DescribeIdentityPoolUsage request.
– IdentityPoolUsage (dict) – Information about the usage of the identity
pool.
* IdentityPoolId (string) – A name-spaced GUID (for example, us-
east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created
by Amazon Cognito. GUID generation is unique within a region.
* SyncSessionsCount (integer) – Number of sync sessions for the
identity pool.
* DataStorage (integer) – Data storage information for the identity
pool.
* LastModifiedDate (datetime) – Date on which the identity pool was
last modified.
describe_identity_usage(**kwargs)
Gets usage information for an identity, including number of datasets and data usage.
This API can be called with temporary user credentials provided by Cognito Identity or with developer
credentials.
Request Syntax
580 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.describe_identity_usage(
IdentityPoolId='string',
IdentityId='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Ama-
zon Cognito. GUID generation is unique within a region.
• IdentityId (string) – [REQUIRED] A name-spaced GUID (for example, us-
east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon
Cognito. GUID generation is unique within a region.
Return type dict
Returns
Response Syntax
{
'IdentityUsage': {
'IdentityId': 'string',
'IdentityPoolId': 'string',
'LastModifiedDate': datetime(2015, 1, 1),
'DatasetCount': 123,
'DataStorage': 123
}
}
Response Structure
• (dict) – The response to a successful DescribeIdentityUsage request.
– IdentityUsage (dict) – Usage information for the identity.
* IdentityId (string) – A name-spaced GUID (for example, us-east-
1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by
Amazon Cognito. GUID generation is unique within a region.
* IdentityPoolId (string) – A name-spaced GUID (for example, us-
east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created
by Amazon Cognito. GUID generation is unique within a region.
* LastModifiedDate (datetime) – Date on which the identity was last
modified.
* DatasetCount (integer) – Number of datasets for the identity.
* DataStorage (integer) – Total data storage for this identity.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_bulk_publish_details(**kwargs)
Get the status of the last BulkPublish operation for an identity pool.
This API can only be called with developer credentials. You cannot call this API with the temporary user
credentials provided by Cognito Identity.
3.1. Services 581
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.get_bulk_publish_details(
IdentityPoolId='string'
)
Parameters IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon Cog-
nito. GUID generation is unique within a region.
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string',
'BulkPublishStartTime': datetime(2015, 1, 1),
'BulkPublishCompleteTime': datetime(2015, 1, 1),
'BulkPublishStatus': 'NOT_STARTED'|'IN_PROGRESS'|'FAILED'|'SUCCEEDED',
'FailureMessage': 'string'
}
Response Structure
• (dict) – The output for the GetBulkPublishDetails operation.
– IdentityPoolId (string) – A name-spaced GUID (for example, us-east-
1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon
Cognito. GUID generation is unique within a region.
– BulkPublishStartTime (datetime) – The date/time at which the last bulk
publish was initiated.
– BulkPublishCompleteTime (datetime) – If BulkPublishStatus is SUC-
CEEDED, the time the last bulk publish operation completed.
– BulkPublishStatus (string) – Status of the last bulk publish operation,
valid values are:
NOT_STARTED - No bulk publish has been requested for this identity
pool
IN_PROGRESS - Data is being published to the configured stream
SUCCEEDED - All data for the identity pool has been published to the
configured stream
FAILED - Some portion of the data has failed to publish, check Fail-
ureMessage for the cause.
– FailureMessage (string) – If BulkPublishStatus is FAILED this field will
contain the error message that caused the bulk publish to fail.
get_cognito_events(**kwargs)
Gets the events and the corresponding Lambda functions associated with an identity pool.
This API can only be called with developer credentials. You cannot call this API with the temporary user
credentials provided by Cognito Identity.
Request Syntax
response = client.get_cognito_events(
IdentityPoolId='string'
)
582 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters IdentityPoolId (string) – [REQUIRED]
The Cognito Identity Pool ID for the request
Return type dict
Returns
Response Syntax
{
'Events': {
'string': 'string'
}
}
Response Structure
• (dict) –
The response from the GetCognitoEvents request
– Events (dict) –
The Cognito Events returned from the GetCognitoEvents request
* (string) –
· (string) –
get_identity_pool_configuration(**kwargs)
Gets the configuration settings of an identity pool.
This API can only be called with developer credentials. You cannot call this API with the temporary user
credentials provided by Cognito Identity.
Request Syntax
response = client.get_identity_pool_configuration(
IdentityPoolId='string'
)
Parameters IdentityPoolId (string) – [REQUIRED]
A name-spaced GUID (for example, us-east-1:23EC4050-6AEA-7089-A2DD-
08002EXAMPLE) created by Amazon Cognito. This is the ID of the pool for which
to return a configuration.
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string',
'PushSync': {
'ApplicationArns': [
'string',
],
'RoleArn': 'string'
},
'CognitoStreams': {
'StreamName': 'string',
'RoleArn': 'string',
'StreamingStatus': 'ENABLED'|'DISABLED'
}
}
3.1. Services 583
Boto3 Documentation, Release 1.1.4
Response Structure
• (dict) –
The output for the GetIdentityPoolConfiguration operation.
– IdentityPoolId (string) –
A name-spaced GUID (for example, us-east-1:23EC4050-6AEA-7089-
A2DD-08002EXAMPLE) created by Amazon Cognito.
– PushSync (dict) –
Options to apply to this identity pool for push synchronization.
* ApplicationArns (list) –
List of SNS platform application ARNs that could be used by
clients.
· (string) –
* RoleArn (string) –
A role configured to allow Cognito to call SNS on behalf of the
developer.
– CognitoStreams (dict) – Options to apply to this identity pool for Amazon
Cognito streams.
* StreamName (string) – The name of the Cognito stream to receive
updates. This stream must be in the developers account and in the
same region as the identity pool.
* RoleArn (string) – The ARN of the role Amazon Cognito can as-
sume in order to publish to the stream. This role must grant access to
Amazon Cognito (cognito-sync) to invoke PutRecord on your Cog-
nito stream.
* StreamingStatus (string) – Status of the Cognito streams. Valid
values are:
ENABLED - Streaming of updates to identity pool is enabled.
DISABLED - Streaming of updates to identity pool is disabled.
Bulk publish will also fail if StreamingStatus is DISABLED.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
list_datasets(**kwargs)
Lists datasets for an identity. With Amazon Cognito Sync, each identity has access only to its own data.
Thus, the credentials used to make this API call need to have access to the identity data.
ListDatasets can be called with temporary user credentials provided by Cognito Identity or with developer
credentials. You should use the Cognito Identity credentials to make this API call.
Request Syntax
584 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.list_datasets(
IdentityPoolId='string',
IdentityId='string',
NextToken='string',
MaxResults=123
)
Parameters
• IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Ama-
zon Cognito. GUID generation is unique within a region.
• IdentityId (string) – [REQUIRED] A name-spaced GUID (for example, us-
east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon
Cognito. GUID generation is unique within a region.
• NextToken (string) – A pagination token for obtaining the next page of results.
• MaxResults (integer) – The maximum number of results to be returned.
Return type dict
Returns
Response Syntax
{
'Datasets': [
{
'IdentityId': 'string',
'DatasetName': 'string',
'CreationDate': datetime(2015, 1, 1),
'LastModifiedDate': datetime(2015, 1, 1),
'LastModifiedBy': 'string',
'DataStorage': 123,
'NumRecords': 123
},
],
'Count': 123,
'NextToken': 'string'
}
Response Structure
• (dict) – Returned for a successful ListDatasets request.
– Datasets (list) – A set of datasets.
* (dict) – A collection of data for an identity pool. An identity pool
can have multiple datasets. A dataset is per identity and can be
general or associated with a particular entity in an application (like
a saved game). Datasets are automatically created if they don’t exist.
Data is synced by dataset, and a dataset can hold up to 1MB of key-
value pairs.
· IdentityId (string) – A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE)
created by Amazon Cognito. GUID generation is unique
within a region.
· DatasetName (string) – A string of up to 128 characters.
Allowed characters are a-z, A-Z, 0-9, ‘_’ (underscore), ‘-‘
(dash), and ‘.’ (dot).
· CreationDate (datetime) – Date on which the dataset was
created.
3.1. Services 585
Boto3 Documentation, Release 1.1.4
· LastModifiedDate (datetime) – Date when the dataset was
last modified.
· LastModifiedBy (string) – The device that made the last
change to this dataset.
· DataStorage (integer) – Total size in bytes of the records in
this dataset.
· NumRecords (integer) – Number of records in this dataset.
– Count (integer) – Number of datasets returned.
– NextToken (string) – A pagination token for obtaining the next page of
results.
list_identity_pool_usage(**kwargs)
Gets a list of identity pools registered with Cognito.
ListIdentityPoolUsage can only be called with developer credentials. You cannot make this API call with
the temporary user credentials provided by Cognito Identity.
Request Syntax
response = client.list_identity_pool_usage(
NextToken='string',
MaxResults=123
)
Parameters
• NextToken (string) – A pagination token for obtaining the next page of results.
• MaxResults (integer) – The maximum number of results to be returned.
Return type dict
Returns
Response Syntax
{
'IdentityPoolUsages': [
{
'IdentityPoolId': 'string',
'SyncSessionsCount': 123,
'DataStorage': 123,
'LastModifiedDate': datetime(2015, 1, 1)
},
],
'MaxResults': 123,
'Count': 123,
'NextToken': 'string'
}
Response Structure
• (dict) – Returned for a successful ListIdentityPoolUsage request.
– IdentityPoolUsages (list) – Usage information for the identity pools.
* (dict) – Usage information for the identity pool.
· IdentityPoolId (string) – A name-spaced GUID (for
example, us-east-1:23EC4050-6AEA-7089-A2DD-
08002EXAMPLE) created by Amazon Cognito. GUID
generation is unique within a region.
· SyncSessionsCount (integer) – Number of sync sessions for
the identity pool.
· DataStorage (integer) – Data storage information for the
identity pool.
586 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· LastModifiedDate (datetime) – Date on which the identity
pool was last modified.
– MaxResults (integer) – The maximum number of results to be returned.
– Count (integer) – Total number of identities for the identity pool.
– NextToken (string) – A pagination token for obtaining the next page of
results.
list_records(**kwargs)
Gets paginated records, optionally changed after a particular sync count for a dataset and identity. With
Amazon Cognito Sync, each identity has access only to its own data. Thus, the credentials used to make
this API call need to have access to the identity data.
ListRecords can be called with temporary user credentials provided by Cognito Identity or with developer
credentials. You should use Cognito Identity credentials to make this API call.
Request Syntax
response = client.list_records(
IdentityPoolId='string',
IdentityId='string',
DatasetName='string',
LastSyncCount=123,
NextToken='string',
MaxResults=123,
SyncSessionToken='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Ama-
zon Cognito. GUID generation is unique within a region.
• IdentityId (string) – [REQUIRED] A name-spaced GUID (for example, us-
east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon
Cognito. GUID generation is unique within a region.
• DatasetName (string) – [REQUIRED] A string of up to 128 characters. Al-
lowed characters are a-z, A-Z, 0-9, ‘_’ (underscore), ‘-‘ (dash), and ‘.’ (dot).
• LastSyncCount (integer) – The last server sync count for this record.
• NextToken (string) – A pagination token for obtaining the next page of results.
• MaxResults (integer) – The maximum number of results to be returned.
• SyncSessionToken (string) – A token containing a session ID, identity ID, and
expiration.
Return type dict
Returns
Response Syntax
{
'Records': [
{
'Key': 'string',
'Value': 'string',
'SyncCount': 123,
'LastModifiedDate': datetime(2015, 1, 1),
'LastModifiedBy': 'string',
'DeviceLastModifiedDate': datetime(2015, 1, 1)
},
],
3.1. Services 587
Boto3 Documentation, Release 1.1.4
'NextToken': 'string',
'Count': 123,
'DatasetSyncCount': 123,
'LastModifiedBy': 'string',
'MergedDatasetNames': [
'string',
],
'DatasetExists': True|False,
'DatasetDeletedAfterRequestedSyncCount': True|False,
'SyncSessionToken': 'string'
}
Response Structure
• (dict) – Returned for a successful ListRecordsRequest.
– Records (list) – A list of all records.
* (dict) – The basic data structure of a dataset.
· Key (string) – The key for the record.
· Value (string) – The value for the record.
· SyncCount (integer) – The server sync count for this record.
· LastModifiedDate (datetime) – The date on which the record
was last modified.
· LastModifiedBy (string) – The user/device that made the last
change to this record.
· DeviceLastModifiedDate (datetime) – The last modified date
of the client device.
– NextToken (string) – A pagination token for obtaining the next page of
results.
– Count (integer) – Total number of records.
– DatasetSyncCount (integer) – Server sync count for this dataset.
– LastModifiedBy (string) – The user/device that made the last change to
this record.
– MergedDatasetNames (list) – Names of merged datasets.
* (string) –
– DatasetExists (boolean) – Indicates whether the dataset exists.
– DatasetDeletedAfterRequestedSyncCount (boolean) – A boolean value
specifying whether to delete the dataset locally.
– SyncSessionToken (string) – A token containing a session ID, identity ID,
and expiration.
register_device(**kwargs)
Registers a device to receive push sync notifications.
This API can only be called with temporary credentials provided by Cognito Identity. You cannot call this
API with developer credentials.
Request Syntax
response = client.register_device(
IdentityPoolId='string',
IdentityId='string',
Platform='APNS'|'APNS_SANDBOX'|'GCM'|'ADM',
Token='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED]
588 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A name-spaced GUID (for example, us-east-1:23EC4050-6AEA-7089-A2DD-
08002EXAMPLE) created by Amazon Cognito. Here, the ID of the pool that
the identity belongs to.
• IdentityId (string) – [REQUIRED]
The unique ID for this identity.
• Platform (string) – [REQUIRED]
The SNS platform type (e.g. GCM, SDM, APNS, APNS_SANDBOX).
• Token (string) – [REQUIRED]
The push token.
Return type dict
Returns
Response Syntax
{
'DeviceId': 'string'
}
Response Structure
• (dict) –
Response to a RegisterDevice request.
– DeviceId (string) –
The unique ID generated for this device by Cognito.
set_cognito_events(**kwargs)
Sets the AWS Lambda function for a given event type for an identity pool. This request only updates the
key/value pair specified. Other key/values pairs are not updated. To remove a key value pair, pass a empty
value for the particular key.
This API can only be called with developer credentials. You cannot call this API with the temporary user
credentials provided by Cognito Identity.
Request Syntax
response = client.set_cognito_events(
IdentityPoolId='string',
Events={
'string': 'string'
}
)
Parameters
• IdentityPoolId (string) – [REQUIRED]
The Cognito Identity Pool to use when configuring Cognito Events
• Events (dict) – [REQUIRED]
The events to configure
– (string) –
* (string) –
Returns None
set_identity_pool_configuration(**kwargs)
Sets the necessary configuration for push sync.
3.1. Services 589
Boto3 Documentation, Release 1.1.4
This API can only be called with developer credentials. You cannot call this API with the temporary user
credentials provided by Cognito Identity.
Request Syntax
response = client.set_identity_pool_configuration(
IdentityPoolId='string',
PushSync={
'ApplicationArns': [
'string',
],
'RoleArn': 'string'
},
CognitoStreams={
'StreamName': 'string',
'RoleArn': 'string',
'StreamingStatus': 'ENABLED'|'DISABLED'
}
)
Parameters
• IdentityPoolId (string) – [REQUIRED]
A name-spaced GUID (for example, us-east-1:23EC4050-6AEA-7089-A2DD-
08002EXAMPLE) created by Amazon Cognito. This is the ID of the pool to
modify.
• PushSync (dict) – Options to apply to this identity pool for push synchroniza-
tion.
– ApplicationArns (list) –
List of SNS platform application ARNs that could be used by clients.
* (string) –
– RoleArn (string) –
A role configured to allow Cognito to call SNS on behalf of the developer.
• CognitoStreams (dict) – Options to apply to this identity pool for Amazon Cog-
nito streams.
– StreamName (string) – The name of the Cognito stream to receive up-
dates. This stream must be in the developers account and in the same
region as the identity pool.
– RoleArn (string) – The ARN of the role Amazon Cognito can assume in
order to publish to the stream. This role must grant access to Amazon
Cognito (cognito-sync) to invoke PutRecord on your Cognito stream.
– StreamingStatus (string) – Status of the Cognito streams. Valid values
are:
ENABLED - Streaming of updates to identity pool is enabled.
DISABLED - Streaming of updates to identity pool is disabled. Bulk pub-
lish will also fail if StreamingStatus is DISABLED.
Return type dict
Returns
Response Syntax
{
'IdentityPoolId': 'string',
'PushSync': {
'ApplicationArns': [
590 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string',
],
'RoleArn': 'string'
},
'CognitoStreams': {
'StreamName': 'string',
'RoleArn': 'string',
'StreamingStatus': 'ENABLED'|'DISABLED'
}
}
Response Structure
• (dict) –
The output for the SetIdentityPoolConfiguration operation
– IdentityPoolId (string) –
A name-spaced GUID (for example, us-east-1:23EC4050-6AEA-7089-
A2DD-08002EXAMPLE) created by Amazon Cognito.
– PushSync (dict) –
Options to apply to this identity pool for push synchronization.
* ApplicationArns (list) –
List of SNS platform application ARNs that could be used by
clients.
· (string) –
* RoleArn (string) –
A role configured to allow Cognito to call SNS on behalf of the
developer.
– CognitoStreams (dict) – Options to apply to this identity pool for Amazon
Cognito streams.
* StreamName (string) – The name of the Cognito stream to receive
updates. This stream must be in the developers account and in the
same region as the identity pool.
* RoleArn (string) – The ARN of the role Amazon Cognito can as-
sume in order to publish to the stream. This role must grant access to
Amazon Cognito (cognito-sync) to invoke PutRecord on your Cog-
nito stream.
* StreamingStatus (string) – Status of the Cognito streams. Valid
values are:
ENABLED - Streaming of updates to identity pool is enabled.
DISABLED - Streaming of updates to identity pool is disabled.
Bulk publish will also fail if StreamingStatus is DISABLED.
subscribe_to_dataset(**kwargs)
Subscribes to receive notifications when a dataset is modified by another device.
This API can only be called with temporary credentials provided by Cognito Identity. You cannot call this
API with developer credentials.
Request Syntax
response = client.subscribe_to_dataset(
IdentityPoolId='string',
IdentityId='string',
3.1. Services 591
Boto3 Documentation, Release 1.1.4
DatasetName='string',
DeviceId='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED]
A name-spaced GUID (for example, us-east-1:23EC4050-6AEA-7089-A2DD-
08002EXAMPLE) created by Amazon Cognito. The ID of the pool to which the
identity belongs.
• IdentityId (string) – [REQUIRED]
Unique ID for this identity.
• DatasetName (string) – [REQUIRED]
The name of the dataset to subcribe to.
• DeviceId (string) – [REQUIRED]
The unique ID generated for this device by Cognito.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Response to a SubscribeToDataset request.
unsubscribe_from_dataset(**kwargs)
Unsubscribes from receiving notifications when a dataset is modified by another device.
This API can only be called with temporary credentials provided by Cognito Identity. You cannot call this
API with developer credentials.
Request Syntax
response = client.unsubscribe_from_dataset(
IdentityPoolId='string',
IdentityId='string',
DatasetName='string',
DeviceId='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED]
A name-spaced GUID (for example, us-east-1:23EC4050-6AEA-7089-A2DD-
08002EXAMPLE) created by Amazon Cognito. The ID of the pool to which
this identity belongs.
• IdentityId (string) – [REQUIRED]
Unique ID for this identity.
• DatasetName (string) – [REQUIRED]
The name of the dataset from which to unsubcribe.
• DeviceId (string) – [REQUIRED]
The unique ID generated for this device by Cognito.
592 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Response to an UnsubscribeFromDataset request.
update_records(**kwargs)
Posts updates to records and adds and deletes records for a dataset and user.
The sync count in the record patch is your last known sync count for that record. The server will reject an
UpdateRecords request with a ResourceConflictException if you try to patch a record with a new value
but a stale sync count.
For example, if the sync count on the server is 5 for a key called highScore and you try and submit a new
highScore with sync count of 4, the request will be rejected. To obtain the current sync count for a record,
call ListRecords. On a successful update of the record, the response returns the new sync count for that
record. You should present that sync count the next time you try to update that same record. When the
record does not exist, specify the sync count as 0.
This API can be called with temporary user credentials provided by Cognito Identity or with developer
credentials.
Request Syntax
response = client.update_records(
IdentityPoolId='string',
IdentityId='string',
DatasetName='string',
DeviceId='string',
RecordPatches=[
{
'Op': 'replace'|'remove',
'Key': 'string',
'Value': 'string',
'SyncCount': 123,
'DeviceLastModifiedDate': datetime(2015, 1, 1)
},
],
SyncSessionToken='string',
ClientContext='string'
)
Parameters
• IdentityPoolId (string) – [REQUIRED] A name-spaced GUID (for example,
us-east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Ama-
zon Cognito. GUID generation is unique within a region.
• IdentityId (string) – [REQUIRED] A name-spaced GUID (for example, us-
east-1:23EC4050-6AEA-7089-A2DD-08002EXAMPLE) created by Amazon
Cognito. GUID generation is unique within a region.
• DatasetName (string) – [REQUIRED] A string of up to 128 characters. Al-
lowed characters are a-z, A-Z, 0-9, ‘_’ (underscore), ‘-‘ (dash), and ‘.’ (dot).
• DeviceId (string) – The unique ID generated for this device by Cognito.
• RecordPatches (list) – A list of patch operations.
3.1. Services 593
Boto3 Documentation, Release 1.1.4
– (dict) – An update operation for a record.
* Op (string) – [REQUIRED] An operation, either replace or re-
move.
* Key (string) – [REQUIRED] The key associated with the record
patch.
* Value (string) – The value associated with the record patch.
* SyncCount (integer) – [REQUIRED] Last known server sync
count for this record. Set to 0 if unknown.
* DeviceLastModifiedDate (datetime) – The last modified date of the
client device.
• SyncSessionToken (string) – [REQUIRED] The SyncSessionToken returned
by a previous call to ListRecords for this dataset and identity.
• ClientContext (string) – Intended to supply a device ID that will populate the
lastModifiedBy field referenced in other methods. The ClientContext field is not
yet implemented.
Return type dict
Returns
Response Syntax
{
'Records': [
{
'Key': 'string',
'Value': 'string',
'SyncCount': 123,
'LastModifiedDate': datetime(2015, 1, 1),
'LastModifiedBy': 'string',
'DeviceLastModifiedDate': datetime(2015, 1, 1)
},
]
}
Response Structure
• (dict) – Returned for a successful UpdateRecordsRequest.
– Records (list) – A list of records that have been updated.
* (dict) – The basic data structure of a dataset.
· Key (string) – The key for the record.
· Value (string) – The value for the record.
· SyncCount (integer) – The server sync count for this record.
· LastModifiedDate (datetime) – The date on which the record
was last modified.
· LastModifiedBy (string) – The user/device that made the last
change to this record.
· DeviceLastModifiedDate (datetime) – The last modified date
of the client device.
ConfigService
Table of Contents
• ConfigService
– Client
594 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Client
class ConfigService.Client
A low-level client representing AWS Config (Config Service):
import boto3
client = boto3.client('config')
These are the available methods:
•can_paginate()
•delete_delivery_channel()
•deliver_config_snapshot()
•describe_configuration_recorder_status()
•describe_configuration_recorders()
•describe_delivery_channel_status()
•describe_delivery_channels()
•generate_presigned_url()
•get_paginator()
•get_resource_config_history()
•get_waiter()
•list_discovered_resources()
•put_configuration_recorder()
•put_delivery_channel()
•start_configuration_recorder()
•stop_configuration_recorder()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
delete_delivery_channel(**kwargs)
Deletes the specified delivery channel.
The delivery channel cannot be deleted if it is the only delivery channel and the configuration recorder is
still running. To delete the delivery channel, stop the running configuration recorder using the StopCon-
figurationRecorder action.
Request Syntax
response = client.delete_delivery_channel(
DeliveryChannelName='string'
)
Parameters DeliveryChannelName (string) – [REQUIRED]
The name of the delivery channel to delete.
Returns None
deliver_config_snapshot(**kwargs)
Schedules delivery of a configuration snapshot to the Amazon S3 bucket in the specified delivery channel.
After the delivery has started, AWS Config sends following notifications using an Amazon SNS topic that
you have specified.
3.1. Services 595
Boto3 Documentation, Release 1.1.4
•Notification of starting the delivery.
•Notification of delivery completed, if the delivery was successfully completed.
•Notification of delivery failure, if the delivery failed to complete.
Request Syntax
response = client.deliver_config_snapshot(
deliveryChannelName='string'
)
Parameters deliveryChannelName (string) – [REQUIRED]
The name of the delivery channel through which the snapshot is delivered.
Return type dict
Returns
Response Syntax
{
'configSnapshotId': 'string'
}
Response Structure
• (dict) –
The output for the DeliverConfigSnapshot action in JSON format.
– configSnapshotId (string) –
The ID of the snapshot that is being created.
describe_configuration_recorder_status(**kwargs)
Returns the current status of the specified configuration recorder. If a configuration recorder is not speci-
fied, this action returns the status of all configuration recorder associated with the account.
Note: Currently, you can specify only one configuration recorder per account.
Request Syntax
response = client.describe_configuration_recorder_status(
ConfigurationRecorderNames=[
'string',
]
)
Parameters ConfigurationRecorderNames (list) – The name(s) of the configuration
recorder. If the name is not specified, the action returns the current status of all the
configuration recorders associated with the account.
• (string) –
Return type dict
Returns
Response Syntax
{
'ConfigurationRecordersStatus': [
{
'name': 'string',
'lastStartTime': datetime(2015, 1, 1),
'lastStopTime': datetime(2015, 1, 1),
596 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'recording': True|False,
'lastStatus': 'Pending'|'Success'|'Failure',
'lastErrorCode': 'string',
'lastErrorMessage': 'string',
'lastStatusChangeTime': datetime(2015, 1, 1)
},
]
}
Response Structure
• (dict) –
The output for the DescribeConfigurationRecorderStatus action in JSON format.
– ConfigurationRecordersStatus (list) –
A list that contains status of the specified recorders.
* (dict) –
The current status of the configuration recorder.
· name (string) –
The name of the configuration recorder.
· lastStartTime (datetime) –
The time the recorder was last started.
· lastStopTime (datetime) –
The time the recorder was last stopped.
· recording (boolean) –
Specifies whether the recorder is currently recording or not.
· lastStatus (string) –
The last (previous) status of the recorder.
· lastErrorCode (string) –
The error code indicating that the recording failed.
· lastErrorMessage (string) –
The message indicating that the recording failed due to an
error.
· lastStatusChangeTime (datetime) –
The time when the status was last changed.
describe_configuration_recorders(**kwargs)
Returns the name of one or more specified configuration recorders. If the recorder name is not specified,
this action returns the names of all the configuration recorders associated with the account.
Note: Currently, you can specify only one configuration recorder per account.
Request Syntax
response = client.describe_configuration_recorders(
ConfigurationRecorderNames=[
'string',
]
)
Parameters ConfigurationRecorderNames (list) – A list of configuration recorder names.
• (string) –
3.1. Services 597
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'ConfigurationRecorders': [
{
'name': 'string',
'roleARN': 'string',
'recordingGroup': {
'allSupported': True|False,
'resourceTypes': [
'AWS::EC2::CustomerGateway'|'AWS::EC2::EIP'|'AWS::EC2::Instanc
]
}
},
]
}
Response Structure
• (dict) –
The output for the DescribeConfigurationRecorders action.
– ConfigurationRecorders (list) –
A list that contains the descriptions of the specified configuration
recorders.
* (dict) –
An object that represents the recording of configuration changes of
an AWS resource.
· name (string) –
The name of the recorder. By default, AWS Config automati-
cally assigns the name “default” when creating the configura-
tion recorder. You cannot change the assigned name.
· roleARN (string) –
Amazon Resource Name (ARN) of the IAM role used to de-
scribe the AWS resources associated with the account.
· recordingGroup (dict) –
The recording group specifies either to record configurations
for all supported resources or to provide a list of resource
types to record. The list of resource types must be a subset
of supported resource types.
· allSupported (boolean) –
Records all supported resource types in the recording group.
For a list of supported resource types, see Supported resource
types . If you specify allSupported , you cannot enumerate a
list of resourceTypes .
· resourceTypes (list) –
A comma-separated list of strings representing valid AWS
resource types (for example, AWS::EC2::Instance or
AWS::CloudTrail::Trail ). resourceTypes is only
valid if you have chosen not to select allSupported . For
a list of valid resourceTypes values, see the resourceType
598 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Value column in the following topic: Supported AWS Re-
source Types .
· (string) –
describe_delivery_channel_status(**kwargs)
Returns the current status of the specified delivery channel. If a delivery channel is not specified, this
action returns the current status of all delivery channels associated with the account.
Note: Currently, you can specify only one delivery channel per account.
Request Syntax
response = client.describe_delivery_channel_status(
DeliveryChannelNames=[
'string',
]
)
Parameters DeliveryChannelNames (list) – A list of delivery channel names.
• (string) –
Return type dict
Returns
Response Syntax
{
'DeliveryChannelsStatus': [
{
'name': 'string',
'configSnapshotDeliveryInfo': {
'lastStatus': 'Success'|'Failure'|'Not_Applicable',
'lastErrorCode': 'string',
'lastErrorMessage': 'string',
'lastAttemptTime': datetime(2015, 1, 1),
'lastSuccessfulTime': datetime(2015, 1, 1)
},
'configHistoryDeliveryInfo': {
'lastStatus': 'Success'|'Failure'|'Not_Applicable',
'lastErrorCode': 'string',
'lastErrorMessage': 'string',
'lastAttemptTime': datetime(2015, 1, 1),
'lastSuccessfulTime': datetime(2015, 1, 1)
},
'configStreamDeliveryInfo': {
'lastStatus': 'Success'|'Failure'|'Not_Applicable',
'lastErrorCode': 'string',
'lastErrorMessage': 'string',
'lastStatusChangeTime': datetime(2015, 1, 1)
}
},
]
}
Response Structure
• (dict) –
The output for the DescribeDeliveryChannelStatus action.
3.1. Services 599
Boto3 Documentation, Release 1.1.4
– DeliveryChannelsStatus (list) –
A list that contains the status of a specified delivery channel.
* (dict) –
The status of a specified delivery channel.
Valid values: Success | Failure
· name (string) –
The name of the delivery channel.
· configSnapshotDeliveryInfo (dict) –
A list containing the status of the delivery of the snapshot to
the specified Amazon S3 bucket.
· lastStatus (string) –
Status of the last attempted delivery.
· lastErrorCode (string) –
The error code from the last attempted delivery.
· lastErrorMessage (string) –
The error message from the last attempted delivery.
· lastAttemptTime (datetime) –
The time of the last attempted delivery.
· lastSuccessfulTime (datetime) –
The time of the last successful delivery.
· configHistoryDeliveryInfo (dict) –
A list that contains the status of the delivery of the configura-
tion history to the specified Amazon S3 bucket.
· lastStatus (string) –
Status of the last attempted delivery.
· lastErrorCode (string) –
The error code from the last attempted delivery.
· lastErrorMessage (string) –
The error message from the last attempted delivery.
· lastAttemptTime (datetime) –
The time of the last attempted delivery.
· lastSuccessfulTime (datetime) –
The time of the last successful delivery.
· configStreamDeliveryInfo (dict) –
A list containing the status of the delivery of the configuration
stream notification to the specified Amazon SNS topic.
· lastStatus (string) –
Status of the last attempted delivery.
Note Providing an SNS topic on a DeliveryChannel for AWS
Config is optional. If the SNS delivery is turned off, the last
status will be Not_Applicable .
· lastErrorCode (string) –
The error code from the last attempted delivery.
600 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· lastErrorMessage (string) –
The error message from the last attempted delivery.
· lastStatusChangeTime (datetime) –
The time from the last status change.
describe_delivery_channels(**kwargs)
Returns details about the specified delivery channel. If a delivery channel is not specified, this action
returns the details of all delivery channels associated with the account.
Note: Currently, you can specify only one delivery channel per account.
Request Syntax
response = client.describe_delivery_channels(
DeliveryChannelNames=[
'string',
]
)
Parameters DeliveryChannelNames (list) – A list of delivery channel names.
• (string) –
Return type dict
Returns
Response Syntax
{
'DeliveryChannels': [
{
'name': 'string',
's3BucketName': 'string',
's3KeyPrefix': 'string',
'snsTopicARN': 'string'
},
]
}
Response Structure
• (dict) –
The output for the DescribeDeliveryChannels action.
– DeliveryChannels (list) –
A list that contains the descriptions of the specified delivery channel.
* (dict) –
A logical container used for storing the configuration changes of an
AWS resource.
· name (string) –
The name of the delivery channel. By default, AWS Config
automatically assigns the name “default” when creating the
delivery channel. You cannot change the assigned name.
· s3BucketName (string) –
The name of the Amazon S3 bucket used to store configura-
tion history for the delivery channel.
3.1. Services 601
Boto3 Documentation, Release 1.1.4
· s3KeyPrefix (string) –
The prefix for the specified Amazon S3 bucket.
· snsTopicARN (string) –
The Amazon Resource Name (ARN) of the SNS topic that
AWS Config delivers notifications to.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_resource_config_history(**kwargs)
Returns a list of configuration items for the specified resource. The list contains details about each state
of the resource during the specified time interval.
The response is paginated, and by default, AWS Config returns a limit of 10 configuration items per
page. You can customize this number with the limit parameter. The response includes a nextToken
string, and to get the next page of results, run the request again and enter this string for the nextToken
parameter.
Note: Each call to the API is limited to span a duration of seven days. It is likely that the number of
records returned is smaller than the specified limit . In such cases, you can make another call, using the
nextToken .
Request Syntax
response = client.get_resource_config_history(
resourceType='AWS::EC2::CustomerGateway'|'AWS::EC2::EIP'|'AWS::EC2::Instance'|'AWS::EC2:
resourceId='string',
laterTime=datetime(2015, 1, 1),
earlierTime=datetime(2015, 1, 1),
chronologicalOrder='Reverse'|'Forward',
limit=123,
nextToken='string'
)
Parameters
602 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• resourceType (string) – [REQUIRED]
The resource type.
• resourceId (string) – [REQUIRED]
The ID of the resource (for example., sg-xxxxxx ).
• laterTime (datetime) – The time stamp that indicates a later time. If not speci-
fied, current time is taken.
• earlierTime (datetime) – The time stamp that indicates an earlier time. If not
specified, the action returns paginated results that contain configuration items
that start from when the first configuration item was recorded.
• chronologicalOrder (string) – The chronological order for configuration items
listed. By default the results are listed in reverse chronological order.
• limit (integer) – The maximum number of configuration items returned on each
page. The default is 10. You cannot specify a limit greater than 100. If you
specify 0, AWS Config uses the default.
• nextToken (string) – The nextToken string returned on a previous page that
you use to get the next page of results in a paginated response.
Return type dict
Returns
Response Syntax
{
'configurationItems': [
{
'version': 'string',
'accountId': 'string',
'configurationItemCaptureTime': datetime(2015, 1, 1),
'configurationItemStatus': 'Ok'|'Failed'|'Discovered'|'Deleted',
'configurationStateId': 'string',
'configurationItemMD5Hash': 'string',
'arn': 'string',
'resourceType': 'AWS::EC2::CustomerGateway'|'AWS::EC2::EIP'|'AWS::EC2:
'resourceId': 'string',
'resourceName': 'string',
'awsRegion': 'string',
'availabilityZone': 'string',
'resourceCreationTime': datetime(2015, 1, 1),
'tags': {
'string': 'string'
},
'relatedEvents': [
'string',
],
'relationships': [
{
'resourceType': 'AWS::EC2::CustomerGateway'|'AWS::EC2::EIP'|'A
'resourceId': 'string',
'resourceName': 'string',
'relationshipName': 'string'
},
],
'configuration': 'string'
},
],
'nextToken': 'string'
}
3.1. Services 603
Boto3 Documentation, Release 1.1.4
Response Structure
• (dict) –
The output for the GetResourceConfigHistory action.
– configurationItems (list) –
A list that contains the configuration history of one or more resources.
* (dict) –
A list that contains detailed configurations of a specified resource.
Note: Currently, the list does not contain information about non-
AWS components (for example, applications on your Amazon EC2
instances).
· version (string) –
The version number of the resource configuration.
· accountId (string) –
The 12 digit AWS account ID associated with the resource.
· configurationItemCaptureTime (datetime) –
The time when the configuration recording was initiated.
· configurationItemStatus (string) –
The configuration item status.
· configurationStateId (string) –
An identifier that indicates the ordering of the configuration
items of a resource.
· configurationItemMD5Hash (string) –
Unique MD5 hash that represents the configuration item’s
state.
You can use MD5 hash to compare the states of two or
more configuration items that are associated with the same
resource.
· arn (string) –
The Amazon Resource Name (ARN) of the resource.
· resourceType (string) –
The type of AWS resource.
· resourceId (string) –
The ID of the resource (for example., sg-xxxxxx ).
· resourceName (string) –
The custom name of the resource, if available.
· awsRegion (string) –
The region where the resource resides.
· availabilityZone (string) –
The Availability Zone associated with the resource.
· resourceCreationTime (datetime) –
The time stamp when the resource was created.
· tags (dict) –
A mapping of key value tags associated with the resource.
604 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (string) –
· (string) –
· relatedEvents (list) –
A list of CloudTrail event IDs.
A populated field indicates that the current configuration was
initiated by the events recorded in the CloudTrail log. For
more information about CloudTrail, see What is AWS Cloud-
Trail? .
An empty field indicates that the current configuration was
not initiated by any event.
· (string) –
· relationships (list) –
A list of related AWS resources.
· (dict) –
The relationship of the related resource to the main resource.
· resourceType (string) –
The resource type of the related resource.
· resourceId (string) –
The ID of the related resource (for example, sg-xxxxxx ).
· resourceName (string) –
The custom name of the related resource, if available.
· relationshipName (string) –
The type of relationship with the related resource.
· configuration (string) –
The description of the resource configuration.
– nextToken (string) –
The string that you use in a subsequent request to get the next page of
results in a paginated response.
get_waiter(waiter_name)
list_discovered_resources(**kwargs)
Accepts a resource type and returns a list of resource identifiers for the resources of that type. A resource
identifier includes the resource type, ID, and (if available) the custom resource name. The results consist
of resources that AWS Config has discovered, including those that AWS Config is not currently recording.
You can narrow the results to include only resources that have specific resource IDs or a resource name.
Note: You can specify either resource IDs or a resource name but not both in the same request.
The response is paginated, and by default AWS Config lists 100 resource identifiers on each page. You
can customize this number with the limit parameter. The response includes a nextToken string, and
to get the next page of results, run the request again and enter this string for the nextToken parameter.
Request Syntax
response = client.list_discovered_resources(
resourceType='AWS::EC2::CustomerGateway'|'AWS::EC2::EIP'|'AWS::EC2::Instance'|'AWS::EC2:
resourceIds=[
'string',
],
3.1. Services 605
Boto3 Documentation, Release 1.1.4
resourceName='string',
limit=123,
includeDeletedResources=True|False,
nextToken='string'
)
Parameters
• resourceType (string) – [REQUIRED]
The type of resources that you want AWS Config to list in the response.
• resourceIds (list) – The IDs of only those resources that you want AWS Config
to list in the response. If you do not specify this parameter, AWS Config lists all
resources of the specified type that it has discovered.
– (string) –
• resourceName (string) – The custom name of only those resources that you
want AWS Config to list in the response. If you do not specify this parameter,
AWS Config lists all resources of the specified type that it has discovered.
• limit (integer) – The maximum number of resource identifiers returned on each
page. The default is 100. You cannot specify a limit greater than 100. If you
specify 0, AWS Config uses the default.
• includeDeletedResources (boolean) – Specifies whether AWS Config includes
deleted resources in the results. By default, deleted resources are not included.
• nextToken (string) – The nextToken string returned on a previous page that
you use to get the next page of results in a paginated response.
Return type dict
Returns
Response Syntax
{
'resourceIdentifiers': [
{
'resourceType': 'AWS::EC2::CustomerGateway'|'AWS::EC2::EIP'|'AWS::EC2:
'resourceId': 'string',
'resourceName': 'string',
'resourceDeletionTime': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
– resourceIdentifiers (list) –
The details that identify a resource that is discovered by AWS Config,
including the resource type, ID, and (if available) the custom resource
name.
* (dict) –
The details that identify a resource that is discovered by AWS Con-
fig, including the resource type, ID, and (if available) the custom
resource name.
· resourceType (string) –
The type of resource.
· resourceId (string) –
606 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The ID of the resource (for example., sg-xxxxxx ).
· resourceName (string) –
The custom name of the resource (if available).
· resourceDeletionTime (datetime) –
The time that the resource was deleted.
– nextToken (string) –
The string that you use in a subsequent request to get the next page of
results in a paginated response.
put_configuration_recorder(**kwargs)
Creates a new configuration recorder to record the selected resource configurations.
You can use this action to change the role roleARN and/or the recordingGroup of an existing
recorder. To change the role, call the action on the existing configuration recorder and specify a role.
Note: Currently, you can specify only one configuration recorder per account.
If ConfigurationRecorder does not have the recordingGroup parameter specified, the default is
to record all supported resource types.
Request Syntax
response = client.put_configuration_recorder(
ConfigurationRecorder={
'name': 'string',
'roleARN': 'string',
'recordingGroup': {
'allSupported': True|False,
'resourceTypes': [
'AWS::EC2::CustomerGateway'|'AWS::EC2::EIP'|'AWS::EC2::Instance'|'AWS::EC2::
]
}
}
)
Parameters ConfigurationRecorder (dict) – [REQUIRED]
The configuration recorder object that records each configuration change made to the
resources.
• name (string) –
The name of the recorder. By default, AWS Config automatically assigns the
name “default” when creating the configuration recorder. You cannot change the
assigned name.
• roleARN (string) –
Amazon Resource Name (ARN) of the IAM role used to describe the AWS re-
sources associated with the account.
• recordingGroup (dict) –
The recording group specifies either to record configurations for all supported
resources or to provide a list of resource types to record. The list of resource
types must be a subset of supported resource types.
– allSupported (boolean) –
Records all supported resource types in the recording group. For a list of
supported resource types, see Supported resource types . If you specify
3.1. Services 607
Boto3 Documentation, Release 1.1.4
allSupported , you cannot enumerate a list of resourceTypes .
– resourceTypes (list) –
A comma-separated list of strings representing valid AWS
resource types (for example, AWS::EC2::Instance or
AWS::CloudTrail::Trail ). resourceTypes is only valid if
you have chosen not to select allSupported . For a list of valid resource-
Types values, see the resourceType Value column in the following topic:
Supported AWS Resource Types .
* (string) –
Returns None
put_delivery_channel(**kwargs)
Creates a new delivery channel object to deliver the configuration information to an Amazon S3 bucket,
and to an Amazon SNS topic.
You can use this action to change the Amazon S3 bucket or an Amazon SNS topic of the existing delivery
channel. To change the Amazon S3 bucket or an Amazon SNS topic, call this action and specify the
changed values for the S3 bucket and the SNS topic. If you specify a different value for either the S3
bucket or the SNS topic, this action will keep the existing value for the parameter that is not changed.
Note: Currently, you can specify only one delivery channel per account.
Request Syntax
response = client.put_delivery_channel(
DeliveryChannel={
'name': 'string',
's3BucketName': 'string',
's3KeyPrefix': 'string',
'snsTopicARN': 'string'
}
)
Parameters DeliveryChannel (dict) – [REQUIRED]
The configuration delivery channel object that delivers the configuration information
to an Amazon S3 bucket, and to an Amazon SNS topic.
• name (string) –
The name of the delivery channel. By default, AWS Config automatically assigns
the name “default” when creating the delivery channel. You cannot change the
assigned name.
• s3BucketName (string) –
The name of the Amazon S3 bucket used to store configuration history for the
delivery channel.
• s3KeyPrefix (string) –
The prefix for the specified Amazon S3 bucket.
• snsTopicARN (string) –
The Amazon Resource Name (ARN) of the SNS topic that AWS Config delivers
notifications to.
Returns None
start_configuration_recorder(**kwargs)
Starts recording configurations of the AWS resources you have selected to record in your AWS account.
608 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
You must have created at least one delivery channel to successfully start the configuration recorder.
Request Syntax
response = client.start_configuration_recorder(
ConfigurationRecorderName='string'
)
Parameters ConfigurationRecorderName (string) – [REQUIRED]
The name of the recorder object that records each configuration change made to the
resources.
Returns None
stop_configuration_recorder(**kwargs)
Stops recording configurations of the AWS resources you have selected to record in your AWS account.
Request Syntax
response = client.stop_configuration_recorder(
ConfigurationRecorderName='string'
)
Parameters ConfigurationRecorderName (string) – [REQUIRED]
The name of the recorder object that records each configuration change made to the
resources.
Returns None
DataPipeline
Table of Contents
• DataPipeline
– Client
– Paginators
Client
class DataPipeline.Client
A low-level client representing AWS Data Pipeline:
import boto3
client = boto3.client('datapipeline')
These are the available methods:
•activate_pipeline()
•add_tags()
•can_paginate()
•create_pipeline()
•deactivate_pipeline()
•delete_pipeline()
•describe_objects()
3.1. Services 609
Boto3 Documentation, Release 1.1.4
•describe_pipelines()
•evaluate_expression()
•generate_presigned_url()
•get_paginator()
•get_pipeline_definition()
•get_waiter()
•list_pipelines()
•poll_for_task()
•put_pipeline_definition()
•query_objects()
•remove_tags()
•report_task_progress()
•report_task_runner_heartbeat()
•set_status()
•set_task_status()
•validate_pipeline_definition()
activate_pipeline(**kwargs)
Validates the specified pipeline and starts processing pipeline tasks. If the pipeline does not pass valida-
tion, activation fails.
If you need to pause the pipeline to investigate an issue with a component, such as a data source or script,
call DeactivatePipeline .
To activate a finished pipeline, modify the end date for the pipeline and then activate it.
Request Syntax
response = client.activate_pipeline(
pipelineId='string',
parameterValues=[
{
'id': 'string',
'stringValue': 'string'
},
],
startTimestamp=datetime(2015, 1, 1)
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• parameterValues (list) – A list of parameter values to pass to the pipeline at
activation.
– (dict) –
A value or list of parameter values.
* id (string) – [REQUIRED]
The ID of the parameter value.
* stringValue (string) – [REQUIRED]
The field value, expressed as a String.
• startTimestamp (datetime) – The date and time to resume the pipeline. By
default, the pipeline resumes from the last completed execution.
Return type dict
Returns
Response Syntax
610 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{}
Response Structure
• (dict) –
Contains the output of ActivatePipeline.
add_tags(**kwargs)
Adds or modifies tags for the specified pipeline.
Request Syntax
response = client.add_tags(
pipelineId='string',
tags=[
{
'key': 'string',
'value': 'string'
},
]
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• tags (list) – [REQUIRED]
The tags to add, as key/value pairs.
– (dict) –
Tags are key/value pairs defined by a user and associated with a pipeline
to control access. AWS Data Pipeline allows you to associate ten tags per
pipeline. For more information, see Controlling User Access to Pipelines
in the AWS Data Pipeline Developer Guide .
* key (string) – [REQUIRED]
The key name of a tag defined by a user. For more information,
see Controlling User Access to Pipelines in the AWS Data Pipeline
Developer Guide .
* value (string) – [REQUIRED]
The optional value portion of a tag defined by a user. For more
information, see Controlling User Access to Pipelines in the AWS
Data Pipeline Developer Guide .
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the output of AddTags.
can_paginate(operation_name)
Check if an operation can be paginated.
3.1. Services 611
Boto3 Documentation, Release 1.1.4
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
create_pipeline(**kwargs)
Creates a new, empty pipeline. Use PutPipelineDefinition to populate the pipeline.
Request Syntax
response = client.create_pipeline(
name='string',
uniqueId='string',
description='string',
tags=[
{
'key': 'string',
'value': 'string'
},
]
)
Parameters
• name (string) – [REQUIRED]
The name for the pipeline. You can use the same name for multiple pipelines
associated with your AWS account, because AWS Data Pipeline assigns each
pipeline a unique pipeline identifier.
• uniqueId (string) – [REQUIRED]
A unique identifier. This identifier is not the same as the pipeline identifier
assigned by AWS Data Pipeline. You are responsible for defining the format
and ensuring the uniqueness of this identifier. You use this parameter to en-
sure idempotency during repeated calls to CreatePipeline . For example,
if the first call to CreatePipeline does not succeed, you can pass in the
same unique identifier and pipeline name combination on a subsequent call to
CreatePipeline . CreatePipeline ensures that if a pipeline already
exists with the same name and unique identifier, a new pipeline is not created.
Instead, you’ll receive the pipeline identifier from the previous attempt. The
uniqueness of the name and unique identifier combination is scoped to the AWS
account or IAM user credentials.
• description (string) – The description for the pipeline.
• tags (list) – A list of tags to associate with the pipeline at creation. Tags let you
control access to pipelines. For more information, see Controlling User Access
to Pipelines in the AWS Data Pipeline Developer Guide .
– (dict) –
Tags are key/value pairs defined by a user and associated with a pipeline
to control access. AWS Data Pipeline allows you to associate ten tags per
pipeline. For more information, see Controlling User Access to Pipelines
in the AWS Data Pipeline Developer Guide .
* key (string) – [REQUIRED]
The key name of a tag defined by a user. For more information,
see Controlling User Access to Pipelines in the AWS Data Pipeline
Developer Guide .
612 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* value (string) – [REQUIRED]
The optional value portion of a tag defined by a user. For more
information, see Controlling User Access to Pipelines in the AWS
Data Pipeline Developer Guide .
Return type dict
Returns
Response Syntax
{
'pipelineId': 'string'
}
Response Structure
• (dict) –
Contains the output of CreatePipeline.
– pipelineId (string) –
The ID that AWS Data Pipeline assigns the newly created pipeline. For
example, df-06372391ZG65EXAMPLE .
deactivate_pipeline(**kwargs)
Deactivates the specified running pipeline. The pipeline is set to the DEACTIVATING state until the
deactivation process completes.
To resume a deactivated pipeline, use ActivatePipeline . By default, the pipeline resumes from the last
completed execution. Optionally, you can specify the date and time to resume the pipeline.
Request Syntax
response = client.deactivate_pipeline(
pipelineId='string',
cancelActive=True|False
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• cancelActive (boolean) – Indicates whether to cancel any running objects. The
default is true, which sets the state of any running objects to CANCELED . If this
value is false, the pipeline is deactivated after all running objects finish.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the output of DeactivatePipeline.
delete_pipeline(**kwargs)
Deletes a pipeline, its pipeline definition, and its run history. AWS Data Pipeline attempts to cancel
instances associated with the pipeline that are currently being processed by task runners.
3.1. Services 613
Boto3 Documentation, Release 1.1.4
Deleting a pipeline cannot be undone. You cannot query or restore a deleted pipeline. To temporarily
pause a pipeline instead of deleting it, call SetStatus with the status set to PAUSE on individual compo-
nents. Components that are paused by SetStatus can be resumed.
Request Syntax
response = client.delete_pipeline(
pipelineId='string'
)
Parameters pipelineId (string) – [REQUIRED]
The ID of the pipeline.
Returns None
describe_objects(**kwargs)
Gets the object definitions for a set of objects associated with the pipeline. Object definitions are com-
posed of a set of fields that define the properties of the object.
Request Syntax
response = client.describe_objects(
pipelineId='string',
objectIds=[
'string',
],
evaluateExpressions=True|False,
marker='string'
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline that contains the object definitions.
• objectIds (list) – [REQUIRED]
The IDs of the pipeline objects that contain the definitions to be described. You
can pass as many as 25 identifiers in a single call to DescribeObjects .
– (string) –
• evaluateExpressions (boolean) – Indicates whether any expressions in the ob-
ject should be evaluated when the object descriptions are returned.
• marker (string) – The starting point for the results to be returned. For the first
call, this value should be empty. As long as there are more results, continue
to call DescribeObjects with the marker value from the previous call to
retrieve the next set of results.
Return type dict
Returns
Response Syntax
{
'pipelineObjects': [
{
'id': 'string',
'name': 'string',
'fields': [
{
'key': 'string',
'stringValue': 'string',
614 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'refValue': 'string'
},
]
},
],
'marker': 'string',
'hasMoreResults': True|False
}
Response Structure
• (dict) –
Contains the output of DescribeObjects.
– pipelineObjects (list) –
An array of object definitions.
* (dict) –
Contains information about a pipeline object. This can be a logical,
physical, or physical attempt pipeline object. The complete set of
components of a pipeline defines the pipeline.
· id (string) –
The ID of the object.
· name (string) –
The name of the object.
· fields (list) –
Key-value pairs that define the properties of the object.
· (dict) –
A key-value pair that describes a property of a pipeline
object. The value is specified as either a string
value (StringValue ) or a reference to another object
(RefValue ) but not as both.
· key (string) –
The field identifier.
· stringValue (string) –
The field value, expressed as a String.
· refValue (string) –
The field value, expressed as the identifier of another object.
– marker (string) –
The starting point for the next page of results. To view the next page of
results, call DescribeObjects again with this marker value. If the
value is null, there are no more results.
– hasMoreResults (boolean) –
Indicates whether there are more results to return.
describe_pipelines(**kwargs)
Retrieves metadata about one or more pipelines. The information retrieved includes the name of the
pipeline, the pipeline identifier, its current state, and the user account that owns the pipeline. Using
account credentials, you can retrieve metadata about pipelines that you or your IAM users have created.
If you are using an IAM user account, you can retrieve metadata about only those pipelines for which you
have read permissions.
3.1. Services 615
Boto3 Documentation, Release 1.1.4
To retrieve the full pipeline definition instead of metadata about the pipeline, call GetPipelineDefinition .
Request Syntax
response = client.describe_pipelines(
pipelineIds=[
'string',
]
)
Parameters pipelineIds (list) – [REQUIRED]
The IDs of the pipelines to describe. You can pass as many as 25 identifiers in a single
call. To obtain pipeline IDs, call ListPipelines .
• (string) –
Return type dict
Returns
Response Syntax
{
'pipelineDescriptionList': [
{
'pipelineId': 'string',
'name': 'string',
'fields': [
{
'key': 'string',
'stringValue': 'string',
'refValue': 'string'
},
],
'description': 'string',
'tags': [
{
'key': 'string',
'value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
Contains the output of DescribePipelines.
– pipelineDescriptionList (list) –
An array of descriptions for the specified pipelines.
* (dict) –
Contains pipeline metadata.
· pipelineId (string) –
The pipeline identifier that was assigned by AWS
Data Pipeline. This is a string of the form
df-297EG78HU43EEXAMPLE .
616 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· name (string) –
The name of the pipeline.
· fields (list) –
A list of read-only fields that contain metadata about the
pipeline: @userId, @accountId, and @pipelineState.
· (dict) –
A key-value pair that describes a property of a pipeline
object. The value is specified as either a string
value (StringValue ) or a reference to another object
(RefValue ) but not as both.
· key (string) –
The field identifier.
· stringValue (string) –
The field value, expressed as a String.
· refValue (string) –
The field value, expressed as the identifier of another object.
· description (string) –
Description of the pipeline.
· tags (list) –
A list of tags to associated with a pipeline. Tags let you con-
trol access to pipelines. For more information, see Control-
ling User Access to Pipelines in the AWS Data Pipeline De-
veloper Guide .
· (dict) –
Tags are key/value pairs defined by a user and associated
with a pipeline to control access. AWS Data Pipeline allows
you to associate ten tags per pipeline. For more information,
see Controlling User Access to Pipelines in the AWS Data
Pipeline Developer Guide .
· key (string) –
The key name of a tag defined by a user. For more infor-
mation, see Controlling User Access to Pipelines in the AWS
Data Pipeline Developer Guide .
· value (string) –
The optional value portion of a tag defined by a user. For
more information, see Controlling User Access to Pipelines
in the AWS Data Pipeline Developer Guide .
evaluate_expression(**kwargs)
Task runners call EvaluateExpression to evaluate a string in the context of the specified object. For
example, a task runner can evaluate SQL queries stored in Amazon S3.
Request Syntax
response = client.evaluate_expression(
pipelineId='string',
objectId='string',
expression='string'
)
3.1. Services 617
Boto3 Documentation, Release 1.1.4
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• objectId (string) – [REQUIRED]
The ID of the object.
• expression (string) – [REQUIRED]
The expression to evaluate.
Return type dict
Returns
Response Syntax
{
'evaluatedExpression': 'string'
}
Response Structure
• (dict) –
Contains the output of EvaluateExpression.
– evaluatedExpression (string) –
The evaluated expression.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_pipeline_definition(**kwargs)
Gets the definition of the specified pipeline. You can call GetPipelineDefinition to retrieve the
pipeline definition that you provided using PutPipelineDefinition .
Request Syntax
response = client.get_pipeline_definition(
pipelineId='string',
618 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
version='string'
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• version (string) – The version of the pipeline definition to retrieve. Set this
parameter to latest (default) to use the last definition saved to the pipeline or
active to use the last definition that was activated.
Return type dict
Returns
Response Syntax
{
'pipelineObjects': [
{
'id': 'string',
'name': 'string',
'fields': [
{
'key': 'string',
'stringValue': 'string',
'refValue': 'string'
},
]
},
],
'parameterObjects': [
{
'id': 'string',
'attributes': [
{
'key': 'string',
'stringValue': 'string'
},
]
},
],
'parameterValues': [
{
'id': 'string',
'stringValue': 'string'
},
]
}
Response Structure
• (dict) –
Contains the output of GetPipelineDefinition.
– pipelineObjects (list) –
The objects defined in the pipeline.
* (dict) –
Contains information about a pipeline object. This can be a logical,
physical, or physical attempt pipeline object. The complete set of
3.1. Services 619
Boto3 Documentation, Release 1.1.4
components of a pipeline defines the pipeline.
· id (string) –
The ID of the object.
· name (string) –
The name of the object.
· fields (list) –
Key-value pairs that define the properties of the object.
· (dict) –
A key-value pair that describes a property of a pipeline
object. The value is specified as either a string
value (StringValue ) or a reference to another object
(RefValue ) but not as both.
· key (string) –
The field identifier.
· stringValue (string) –
The field value, expressed as a String.
· refValue (string) –
The field value, expressed as the identifier of another object.
– parameterObjects (list) –
The parameter objects used in the pipeline definition.
* (dict) –
Contains information about a parameter object.
· id (string) –
The ID of the parameter object.
· attributes (list) –
The attributes of the parameter object.
· (dict) –
The attributes allowed or specified with a parameter object.
· key (string) –
The field identifier.
· stringValue (string) –
The field value, expressed as a String.
– parameterValues (list) –
The parameter values used in the pipeline definition.
* (dict) –
A value or list of parameter values.
· id (string) –
The ID of the parameter value.
· stringValue (string) –
The field value, expressed as a String.
get_waiter(waiter_name)
list_pipelines(**kwargs)
Lists the pipeline identifiers for all active pipelines that you have permission to access.
620 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.list_pipelines(
marker='string'
)
Parameters marker (string) – The starting point for the results to be returned. For the first
call, this value should be empty. As long as there are more results, continue to call
ListPipelines with the marker value from the previous call to retrieve the next
set of results.
Return type dict
Returns
Response Syntax
{
'pipelineIdList': [
{
'id': 'string',
'name': 'string'
},
],
'marker': 'string',
'hasMoreResults': True|False
}
Response Structure
• (dict) –
Contains the output of ListPipelines.
– pipelineIdList (list) –
The pipeline identifiers. If you require additional information about the
pipelines, you can use these identifiers to call DescribePipelines and Get-
PipelineDefinition .
* (dict) –
Contains the name and identifier of a pipeline.
· id (string) –
The ID of the pipeline that was assigned by
AWS Data Pipeline. This is a string of the form
df-297EG78HU43EEXAMPLE .
· name (string) –
The name of the pipeline.
– marker (string) –
The starting point for the next page of results. To view the next page of
results, call ListPipelinesOutput again with this marker value. If
the value is null, there are no more results.
– hasMoreResults (boolean) –
Indicates whether there are more results that can be obtained by a subse-
quent call.
poll_for_task(**kwargs)
Task runners call PollForTask to receive a task to perform from AWS Data Pipeline. The task runner
specifies which tasks it can perform by setting a value for the workerGroup parameter. The task
3.1. Services 621
Boto3 Documentation, Release 1.1.4
returned can come from any of the pipelines that match the workerGroup value passed in by the task
runner and that was launched using the IAM user credentials specified by the task runner.
If tasks are ready in the work queue, PollForTask returns a response immediately. If no tasks are
available in the queue, PollForTask uses long-polling and holds on to a poll connection for up to a 90
seconds, during which time the first newly scheduled task is handed to the task runner. To accomodate this,
set the socket timeout in your task runner to 90 seconds. The task runner should not call PollForTask
again on the same workerGroup until it receives a response, and this can take up to 90 seconds.
Request Syntax
response = client.poll_for_task(
workerGroup='string',
hostname='string',
instanceIdentity={
'document': 'string',
'signature': 'string'
}
)
Parameters
• workerGroup (string) – [REQUIRED]
The type of task the task runner is configured to accept and process. The worker
group is set as a field on objects in the pipeline when they are created. You can
only specify a single value for workerGroup in the call to PollForTask .
There are no wildcard values permitted in workerGroup ; the string must be
an exact, case-sensitive, match.
• hostname (string) – The public DNS name of the calling task runner.
• instanceIdentity (dict) – Identity information for the EC2 instance that is
hosting the task runner. You can get this value from the instance using
http://169.254.169.254/latest/meta-data/instance-id .
For more information, see Instance Metadata in the Amazon Elastic Compute
Cloud User Guide. Passing in this value proves that your task runner is running
on an EC2 instance, and ensures the proper AWS Data Pipeline service charges
are applied to your pipeline.
– document (string) –
A description of an EC2 instance that is generated when the instance is
launched and exposed to the instance via the instance metadata service in
the form of a JSON representation of an object.
– signature (string) –
A signature which can be used to verify the accuracy and authenticity of
the information provided in the instance identity document.
Return type dict
Returns
Response Syntax
{
'taskObject': {
'taskId': 'string',
'pipelineId': 'string',
'attemptId': 'string',
'objects': {
'string': {
'id': 'string',
622 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'name': 'string',
'fields': [
{
'key': 'string',
'stringValue': 'string',
'refValue': 'string'
},
]
}
}
}
}
Response Structure
• (dict) –
Contains the output of PollForTask.
– taskObject (dict) –
The information needed to complete the task that is being assigned to the
task runner. One of the fields returned in this object is taskId , which
contains an identifier for the task being assigned. The calling task runner
uses taskId in subsequent calls to ReportTaskProgress and SetTaskSta-
tus .
* taskId (string) –
An internal identifier for the task. This ID is passed to the Set-
TaskStatus and ReportTaskProgress actions.
* pipelineId (string) –
The ID of the pipeline that provided the task.
* attemptId (string) –
The ID of the pipeline task attempt object. AWS Data Pipeline uses
this value to track how many times a task is attempted.
* objects (dict) –
Connection information for the location where the task runner will
publish the output of the task.
· (string) –
· (dict) –
Contains information about a pipeline object. This can be
a logical, physical, or physical attempt pipeline object. The
complete set of components of a pipeline defines the pipeline.
· id (string) –
The ID of the object.
· name (string) –
The name of the object.
· fields (list) –
Key-value pairs that define the properties of the object.
· (dict) –
A key-value pair that describes a property of a pipeline
object. The value is specified as either a string
value (StringValue ) or a reference to another object
(RefValue ) but not as both.
3.1. Services 623
Boto3 Documentation, Release 1.1.4
· key (string) –
The field identifier.
· stringValue (string) –
The field value, expressed as a String.
· refValue (string) –
The field value, expressed as the identifier of another object.
put_pipeline_definition(**kwargs)
Adds tasks, schedules, and preconditions to the specified pipeline. You can use
PutPipelineDefinition to populate a new pipeline.
PutPipelineDefinition also validates the configuration as it adds it to the pipeline.
Changes to the pipeline are saved unless one of the following three validation errors exists in
the pipeline.
•An object is missing a name or identifier field.
•A string or reference field is empty.
•The number of objects in the pipeline exceeds the maximum allowed objects.
•The pipeline is in a FINISHED state.
Pipeline object definitions are passed to the PutPipelineDefinition action and returned by the
GetPipelineDefinition action.
Request Syntax
response = client.put_pipeline_definition(
pipelineId='string',
pipelineObjects=[
{
'id': 'string',
'name': 'string',
'fields': [
{
'key': 'string',
'stringValue': 'string',
'refValue': 'string'
},
]
},
],
parameterObjects=[
{
'id': 'string',
'attributes': [
{
'key': 'string',
'stringValue': 'string'
},
]
},
],
parameterValues=[
{
'id': 'string',
'stringValue': 'string'
},
]
)
624 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• pipelineObjects (list) – [REQUIRED]
The objects that define the pipeline. These objects overwrite the existing pipeline
definition.
– (dict) –
Contains information about a pipeline object. This can be a logical, phys-
ical, or physical attempt pipeline object. The complete set of components
of a pipeline defines the pipeline.
* id (string) – [REQUIRED]
The ID of the object.
* name (string) – [REQUIRED]
The name of the object.
* fields (list) – [REQUIRED]
Key-value pairs that define the properties of the object.
· (dict) –
A key-value pair that describes a property of a pipeline
object. The value is specified as either a string
value (StringValue ) or a reference to another object
(RefValue ) but not as both.
· key (string) – [REQUIRED]
The field identifier.
· stringValue (string) –
The field value, expressed as a String.
· refValue (string) –
The field value, expressed as the identifier of another object.
• parameterObjects (list) – The parameter objects used with the pipeline.
– (dict) –
Contains information about a parameter object.
* id (string) – [REQUIRED]
The ID of the parameter object.
* attributes (list) – [REQUIRED]
The attributes of the parameter object.
· (dict) –
The attributes allowed or specified with a parameter object.
· key (string) – [REQUIRED]
The field identifier.
· stringValue (string) – [REQUIRED]
The field value, expressed as a String.
• parameterValues (list) – The parameter values used with the pipeline.
– (dict) –
A value or list of parameter values.
* id (string) – [REQUIRED]
The ID of the parameter value.
3.1. Services 625
Boto3 Documentation, Release 1.1.4
* stringValue (string) – [REQUIRED]
The field value, expressed as a String.
Return type dict
Returns
Response Syntax
{
'validationErrors': [
{
'id': 'string',
'errors': [
'string',
]
},
],
'validationWarnings': [
{
'id': 'string',
'warnings': [
'string',
]
},
],
'errored': True|False
}
Response Structure
• (dict) –
Contains the output of PutPipelineDefinition.
– validationErrors (list) –
The validation errors that are associated with the objects defined in
pipelineObjects .
* (dict) –
Defines a validation error. Validation errors prevent pipeline activa-
tion. The set of validation errors that can be returned are defined by
AWS Data Pipeline.
· id (string) –
The identifier of the object that contains the validation error.
· errors (list) –
A description of the validation error.
· (string) –
– validationWarnings (list) –
The validation warnings that are associated with the objects defined in
pipelineObjects .
* (dict) –
Defines a validation warning. Validation warnings do not prevent
pipeline activation. The set of validation warnings that can be re-
turned are defined by AWS Data Pipeline.
· id (string) –
The identifier of the object that contains the validation warn-
ing.
626 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· warnings (list) –
A description of the validation warning.
· (string) –
– errored (boolean) –
Indicates whether there were validation errors, and the pipeline definition
is stored but cannot be activated until you correct the pipeline and call
PutPipelineDefinition to commit the corrected pipeline.
query_objects(**kwargs)
Queries the specified pipeline for the names of objects that match the specified set of conditions.
Request Syntax
response = client.query_objects(
pipelineId='string',
query={
'selectors': [
{
'fieldName': 'string',
'operator': {
'type': 'EQ'|'REF_EQ'|'LE'|'GE'|'BETWEEN',
'values': [
'string',
]
}
},
]
},
sphere='string',
marker='string',
limit=123
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• query (dict) – The query that defines the objects to be returned. The Query
object can contain a maximum of ten selectors. The conditions in the query are
limited to top-level String fields in the object. These filters can be applied to
components, instances, and attempts.
– selectors (list) –
List of selectors that define the query. An object must satisfy all of the
selectors to match the query.
* (dict) –
A comparision that is used to determine whether a query should
return this object.
· fieldName (string) –
The name of the field that the operator will be applied to.
The field name is the “key” portion of the field definition in
the pipeline definition syntax that is used by the AWS Data
Pipeline API. If the field is not set on the object, the condition
fails.
· operator (dict) –
3.1. Services 627
Boto3 Documentation, Release 1.1.4
Contains a logical operation for comparing the value of a field
with a specified value.
· type (string) –
The logical operation to be performed: equal (EQ ), equal
reference (REF_EQ ), less than or equal (LE ), greater than
or equal (GE ), or between (BETWEEN ). Equal reference
(REF_EQ ) can be used only with reference fields. The other
comparison types can be used only with String fields. The
comparison types you can use apply only to certain object
fields, as detailed below.
The comparison operators EQ and REF_EQ act on the fol-
lowing fields:
· name
· @sphere
· parent
· @componentParent
· @instanceParent
· @status
· @scheduledStartTime
· @scheduledEndTime
· @actualStartTime
· @actualEndTime
The comparison operators GE , LE , and BETWEEN act on the
following fields:
· @scheduledStartTime
· @scheduledEndTime
· @actualStartTime
· @actualEndTime
Note that fields beginning with the at sign (@) are read-only
and set by the web service. When you name fields, you should
choose names containing only alpha-numeric values, as sym-
bols may be reserved by AWS Data Pipeline. User-defined
fields that you add to a pipeline should prefix their name with
the string “my”.
· values (list) –
The value that the actual field value will be compared with.
· (string) –
• sphere (string) – [REQUIRED]
Indicates whether the query applies to components or instances. The possible
values are: COMPONENT , INSTANCE , and ATTEMPT .
• marker (string) – The starting point for the results to be returned. For the first
call, this value should be empty. As long as there are more results, continue to
call QueryObjects with the marker value from the previous call to retrieve
the next set of results.
• limit (integer) – The maximum number of object names that QueryObjects
will return in a single call. The default value is 100.
Return type dict
Returns
Response Syntax
628 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'ids': [
'string',
],
'marker': 'string',
'hasMoreResults': True|False
}
Response Structure
• (dict) –
Contains the output of QueryObjects.
– ids (list) –
The identifiers that match the query selectors.
* (string) –
– marker (string) –
The starting point for the next page of results. To view the next page of
results, call QueryObjects again with this marker value. If the value is
null, there are no more results.
– hasMoreResults (boolean) –
Indicates whether there are more results that can be obtained by a subse-
quent call.
remove_tags(**kwargs)
Removes existing tags from the specified pipeline.
Request Syntax
response = client.remove_tags(
pipelineId='string',
tagKeys=[
'string',
]
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• tagKeys (list) – [REQUIRED]
The keys of the tags to remove.
– (string) –
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the output of RemoveTags.
report_task_progress(**kwargs)
Task runners call ReportTaskProgress when assigned a task to acknowledge that it has the task. If
3.1. Services 629
Boto3 Documentation, Release 1.1.4
the web service does not receive this acknowledgement within 2 minutes, it assigns the task in a subse-
quent PollForTask call. After this initial acknowledgement, the task runner only needs to report progress
every 15 minutes to maintain its ownership of the task. You can change this reporting time from 15
minutes by specifying a reportProgressTimeout field in your pipeline.
If a task runner does not report its status after 5 minutes, AWS Data Pipeline assumes that the task runner
is unable to process the task and reassigns the task in a subsequent response to PollForTask . Task runners
should call ReportTaskProgress every 60 seconds.
Request Syntax
response = client.report_task_progress(
taskId='string',
fields=[
{
'key': 'string',
'stringValue': 'string',
'refValue': 'string'
},
]
)
Parameters
• taskId (string) – [REQUIRED]
The ID of the task assigned to the task runner. This value is provided in the
response for PollForTask .
• fields (list) – Key-value pairs that define the properties of the ReportTaskPro-
gressInput object.
– (dict) –
A key-value pair that describes a property of a pipeline object. The value
is specified as either a string value (StringValue ) or a reference to
another object (RefValue ) but not as both.
* key (string) – [REQUIRED]
The field identifier.
* stringValue (string) –
The field value, expressed as a String.
* refValue (string) –
The field value, expressed as the identifier of another object.
Return type dict
Returns
Response Syntax
{
'canceled': True|False
}
Response Structure
• (dict) –
Contains the output of ReportTaskProgress.
– canceled (boolean) –
If true, the calling task runner should cancel processing of the task. The
task runner does not need to call SetTaskStatus for canceled tasks.
630 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
report_task_runner_heartbeat(**kwargs)
Task runners call ReportTaskRunnerHeartbeat every 15 minutes to indicate that they are opera-
tional. If the AWS Data Pipeline Task Runner is launched on a resource managed by AWS Data Pipeline,
the web service can use this call to detect when the task runner application has failed and restart a new
instance.
Request Syntax
response = client.report_task_runner_heartbeat(
taskrunnerId='string',
workerGroup='string',
hostname='string'
)
Parameters
• taskrunnerId (string) – [REQUIRED]
The ID of the task runner. This value should be unique across your AWS account.
In the case of AWS Data Pipeline Task Runner launched on a resource managed
by AWS Data Pipeline, the web service provides a unique identifier when it
launches the application. If you have written a custom task runner, you should
assign a unique identifier for the task runner.
• workerGroup (string) – The type of task the task runner is configured to accept
and process. The worker group is set as a field on objects in the pipeline when
they are created. You can only specify a single value for workerGroup . There
are no wildcard values permitted in workerGroup ; the string must be an exact,
case-sensitive, match.
• hostname (string) – The public DNS name of the task runner.
Return type dict
Returns
Response Syntax
{
'terminate': True|False
}
Response Structure
• (dict) –
Contains the output of ReportTaskRunnerHeartbeat.
– terminate (boolean) –
Indicates whether the calling task runner should terminate.
set_status(**kwargs)
Requests that the status of the specified physical or logical pipeline objects be updated in the specified
pipeline. This update might not occur immediately, but is eventually consistent. The status that can be set
depends on the type of object (for example, DataNode or Activity). You cannot perform this operation on
FINISHED pipelines and attempting to do so returns InvalidRequestException .
Request Syntax
response = client.set_status(
pipelineId='string',
objectIds=[
'string',
],
3.1. Services 631
Boto3 Documentation, Release 1.1.4
status='string'
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline that contains the objects.
• objectIds (list) – [REQUIRED]
The IDs of the objects. The corresponding objects can be either physical or
components, but not a mix of both types.
– (string) –
• status (string) – [REQUIRED]
The status to be set on all the objects specified in objectIds . For compo-
nents, use PAUSE or RESUME . For instances, use TRY_CANCEL , RERUN , or
MARK_FINISHED .
Returns None
set_task_status(**kwargs)
Task runners call SetTaskStatus to notify AWS Data Pipeline that a task is completed and provide
information about the final status. A task runner makes this call regardless of whether the task was
sucessful. A task runner does not need to call SetTaskStatus for tasks that are canceled by the web
service during a call to ReportTaskProgress .
Request Syntax
response = client.set_task_status(
taskId='string',
taskStatus='FINISHED'|'FAILED'|'FALSE',
errorId='string',
errorMessage='string',
errorStackTrace='string'
)
Parameters
• taskId (string) – [REQUIRED]
The ID of the task assigned to the task runner. This value is provided in the
response for PollForTask .
• taskStatus (string) – [REQUIRED]
If FINISHED , the task successfully completed. If FAILED , the task ended
unsuccessfully. Preconditions use false.
• errorId (string) – If an error occurred during the task, this value specifies the
error code. This value is set on the physical attempt object. It is used to display
error information to the user. It should not start with string “Service_” which is
reserved by the system.
• errorMessage (string) – If an error occurred during the task, this value specifies
a text description of the error. This value is set on the physical attempt object. It
is used to display error information to the user. The web service does not parse
this value.
• errorStackTrace (string) – If an error occurred during the task, this value spec-
ifies the stack trace associated with the error. This value is set on the physical
attempt object. It is used to display error information to the user. The web service
does not parse this value.
Return type dict
632 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the output of SetTaskStatus.
validate_pipeline_definition(**kwargs)
Validates the specified pipeline definition to ensure that it is well formed and can be run without error.
Request Syntax
response = client.validate_pipeline_definition(
pipelineId='string',
pipelineObjects=[
{
'id': 'string',
'name': 'string',
'fields': [
{
'key': 'string',
'stringValue': 'string',
'refValue': 'string'
},
]
},
],
parameterObjects=[
{
'id': 'string',
'attributes': [
{
'key': 'string',
'stringValue': 'string'
},
]
},
],
parameterValues=[
{
'id': 'string',
'stringValue': 'string'
},
]
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• pipelineObjects (list) – [REQUIRED]
The objects that define the pipeline changes to validate against the pipeline.
– (dict) –
3.1. Services 633
Boto3 Documentation, Release 1.1.4
Contains information about a pipeline object. This can be a logical, phys-
ical, or physical attempt pipeline object. The complete set of components
of a pipeline defines the pipeline.
* id (string) – [REQUIRED]
The ID of the object.
* name (string) – [REQUIRED]
The name of the object.
* fields (list) – [REQUIRED]
Key-value pairs that define the properties of the object.
· (dict) –
A key-value pair that describes a property of a pipeline
object. The value is specified as either a string
value (StringValue ) or a reference to another object
(RefValue ) but not as both.
· key (string) – [REQUIRED]
The field identifier.
· stringValue (string) –
The field value, expressed as a String.
· refValue (string) –
The field value, expressed as the identifier of another object.
• parameterObjects (list) – The parameter objects used with the pipeline.
– (dict) –
Contains information about a parameter object.
* id (string) – [REQUIRED]
The ID of the parameter object.
* attributes (list) – [REQUIRED]
The attributes of the parameter object.
· (dict) –
The attributes allowed or specified with a parameter object.
· key (string) – [REQUIRED]
The field identifier.
· stringValue (string) – [REQUIRED]
The field value, expressed as a String.
• parameterValues (list) – The parameter values used with the pipeline.
– (dict) –
A value or list of parameter values.
* id (string) – [REQUIRED]
The ID of the parameter value.
* stringValue (string) – [REQUIRED]
The field value, expressed as a String.
Return type dict
Returns
Response Syntax
634 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'validationErrors': [
{
'id': 'string',
'errors': [
'string',
]
},
],
'validationWarnings': [
{
'id': 'string',
'warnings': [
'string',
]
},
],
'errored': True|False
}
Response Structure
• (dict) –
Contains the output of ValidatePipelineDefinition.
– validationErrors (list) –
Any validation errors that were found.
* (dict) –
Defines a validation error. Validation errors prevent pipeline activa-
tion. The set of validation errors that can be returned are defined by
AWS Data Pipeline.
· id (string) –
The identifier of the object that contains the validation error.
· errors (list) –
A description of the validation error.
· (string) –
– validationWarnings (list) –
Any validation warnings that were found.
* (dict) –
Defines a validation warning. Validation warnings do not prevent
pipeline activation. The set of validation warnings that can be re-
turned are defined by AWS Data Pipeline.
· id (string) –
The identifier of the object that contains the validation warn-
ing.
· warnings (list) –
A description of the validation warning.
· (string) –
– errored (boolean) –
Indicates whether there were validation errors.
3.1. Services 635
Boto3 Documentation, Release 1.1.4
Paginators
The available paginators are:
• DataPipeline.Paginator.DescribeObjects
• DataPipeline.Paginator.ListPipelines
• DataPipeline.Paginator.QueryObjects
class DataPipeline.Paginator.DescribeObjects
paginator = client.get_paginator('describe_objects')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
DataPipeline.Client.describe_objects().
Request Syntax
response_iterator = paginator.paginate(
pipelineId='string',
objectIds=[
'string',
],
evaluateExpressions=True|False,
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• pipelineId (string) – [REQUIRED]
The ID of the pipeline that contains the object definitions.
• objectIds (list) – [REQUIRED]
The IDs of the pipeline objects that contain the definitions to be described. You
can pass as many as 25 identifiers in a single call to DescribeObjects .
– (string) –
• evaluateExpressions (boolean) – Indicates whether any expressions in the ob-
ject should be evaluated when the object descriptions are returned.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
636 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'pipelineObjects': [
{
'id': 'string',
'name': 'string',
'fields': [
{
'key': 'string',
'stringValue': 'string',
'refValue': 'string'
},
]
},
],
'hasMoreResults': True|False,
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the output of DescribeObjects.
– pipelineObjects (list) –
An array of object definitions.
* (dict) –
Contains information about a pipeline object. This can be a logical,
physical, or physical attempt pipeline object. The complete set of
components of a pipeline defines the pipeline.
· id (string) –
The ID of the object.
· name (string) –
The name of the object.
· fields (list) –
Key-value pairs that define the properties of the object.
· (dict) –
A key-value pair that describes a property of a pipeline
object. The value is specified as either a string
value (StringValue ) or a reference to another object
(RefValue ) but not as both.
· key (string) –
The field identifier.
· stringValue (string) –
The field value, expressed as a String.
· refValue (string) –
The field value, expressed as the identifier of another object.
– hasMoreResults (boolean) –
Indicates whether there are more results to return.
3.1. Services 637
Boto3 Documentation, Release 1.1.4
– NextToken (string) –
A token to resume pagination.
class DataPipeline.Paginator.ListPipelines
paginator = client.get_paginator('list_pipelines')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
DataPipeline.Client.list_pipelines().
Request Syntax
response_iterator = paginator.paginate(
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
• MaxItems (integer) –
The total number of items to return. If the total number of items available is
more than the value specified in max-items then a NextToken will be provided
in the output that you can use to resume pagination.
• PageSize (integer) –
The size of each page.
• StartingToken (string) –
A token to specify where to start paginating. This is the NextToken from a
previous response.
Return type dict
Returns
Response Syntax
{
'pipelineIdList': [
{
'id': 'string',
'name': 'string'
},
],
'hasMoreResults': True|False,
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the output of ListPipelines.
638 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– pipelineIdList (list) –
The pipeline identifiers. If you require additional information about the
pipelines, you can use these identifiers to call DescribePipelines and Get-
PipelineDefinition .
* (dict) –
Contains the name and identifier of a pipeline.
· id (string) –
The ID of the pipeline that was assigned by
AWS Data Pipeline. This is a string of the form
df-297EG78HU43EEXAMPLE .
· name (string) –
The name of the pipeline.
– hasMoreResults (boolean) –
Indicates whether there are more results that can be obtained by a subse-
quent call.
– NextToken (string) –
A token to resume pagination.
class DataPipeline.Paginator.QueryObjects
paginator = client.get_paginator('query_objects')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
DataPipeline.Client.query_objects().
Request Syntax
response_iterator = paginator.paginate(
pipelineId='string',
query={
'selectors': [
{
'fieldName': 'string',
'operator': {
'type': 'EQ'|'REF_EQ'|'LE'|'GE'|'BETWEEN',
'values': [
'string',
]
}
},
]
},
sphere='string',
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
3.1. Services 639
Boto3 Documentation, Release 1.1.4
• pipelineId (string) – [REQUIRED]
The ID of the pipeline.
• query (dict) – The query that defines the objects to be returned. The Query
object can contain a maximum of ten selectors. The conditions in the query are
limited to top-level String fields in the object. These filters can be applied to
components, instances, and attempts.
– selectors (list) –
List of selectors that define the query. An object must satisfy all of the
selectors to match the query.
* (dict) –
A comparision that is used to determine whether a query should
return this object.
· fieldName (string) –
The name of the field that the operator will be applied to.
The field name is the “key” portion of the field definition in
the pipeline definition syntax that is used by the AWS Data
Pipeline API. If the field is not set on the object, the condition
fails.
· operator (dict) –
Contains a logical operation for comparing the value of a field
with a specified value.
· type (string) –
The logical operation to be performed: equal (EQ ), equal
reference (REF_EQ ), less than or equal (LE ), greater than
or equal (GE ), or between (BETWEEN ). Equal reference
(REF_EQ ) can be used only with reference fields. The other
comparison types can be used only with String fields. The
comparison types you can use apply only to certain object
fields, as detailed below.
The comparison operators EQ and REF_EQ act on the fol-
lowing fields:
· name
· @sphere
· parent
· @componentParent
· @instanceParent
· @status
· @scheduledStartTime
· @scheduledEndTime
· @actualStartTime
· @actualEndTime
The comparison operators GE , LE , and BETWEEN act on the
following fields:
· @scheduledStartTime
· @scheduledEndTime
· @actualStartTime
· @actualEndTime
Note that fields beginning with the at sign (@) are read-only
and set by the web service. When you name fields, you should
choose names containing only alpha-numeric values, as sym-
640 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
bols may be reserved by AWS Data Pipeline. User-defined
fields that you add to a pipeline should prefix their name with
the string “my”.
· values (list) –
The value that the actual field value will be compared with.
· (string) –
• sphere (string) – [REQUIRED]
Indicates whether the query applies to components or instances. The possible
values are: COMPONENT , INSTANCE , and ATTEMPT .
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'ids': [
'string',
],
'hasMoreResults': True|False,
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the output of QueryObjects.
– ids (list) –
The identifiers that match the query selectors.
* (string) –
– hasMoreResults (boolean) –
Indicates whether there are more results that can be obtained by a subse-
quent call.
– NextToken (string) –
A token to resume pagination.
DeviceFarm
3.1. Services 641
Boto3 Documentation, Release 1.1.4
Table of Contents
• DeviceFarm
– Client
Client
class DeviceFarm.Client
A low-level client representing AWS Device Farm:
import boto3
client = boto3.client('devicefarm')
These are the available methods:
•can_paginate()
•create_device_pool()
•create_project()
•create_upload()
•generate_presigned_url()
•get_account_settings()
•get_device()
•get_device_pool()
•get_device_pool_compatibility()
•get_job()
•get_paginator()
•get_project()
•get_run()
•get_suite()
•get_test()
•get_upload()
•get_waiter()
•list_artifacts()
•list_device_pools()
•list_devices()
•list_jobs()
•list_projects()
•list_runs()
•list_samples()
•list_suites()
•list_tests()
•list_unique_problems()
•list_uploads()
•schedule_run()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
642 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
create_device_pool(**kwargs)
Creates a device pool.
Request Syntax
response = client.create_device_pool(
projectArn='string',
name='string',
description='string',
rules=[
{
'attribute': 'ARN'|'PLATFORM'|'FORM_FACTOR'|'MANUFACTURER',
'operator': 'EQUALS'|'LESS_THAN'|'GREATER_THAN'|'IN'|'NOT_IN',
'value': 'string'
},
]
)
Parameters
• projectArn (string) – [REQUIRED]
The ARN of the project for the device pool.
• name (string) – [REQUIRED]
The device pool’s name.
• description (string) – The device pool’s description.
• rules (list) – [REQUIRED]
The device pool’s rules.
– (dict) –
Represents a condition for a device pool.
* attribute (string) –
The rule’s attribute.
Allowed values include:
· ARN: The ARN.
· FORM_FACTOR: The form factor (for example, phone or
tablet).
· MANUFACTURER: The manufacturer.
· PLATFORM: The platform (for example, Android or iOS).
* operator (string) –
The rule’s operator.
· EQUALS: The equals operator.
· GREATER_THAN: The greater-than operator.
· IN: The in operator.
· LESS_THAN: The less-than operator.
· NOT_IN: The not-in operator.
* value (string) –
The rule’s value.
Return type dict
Returns
Response Syntax
{
'devicePool': {
3.1. Services 643
Boto3 Documentation, Release 1.1.4
'arn': 'string',
'name': 'string',
'description': 'string',
'type': 'CURATED'|'PRIVATE',
'rules': [
{
'attribute': 'ARN'|'PLATFORM'|'FORM_FACTOR'|'MANUFACTURER',
'operator': 'EQUALS'|'LESS_THAN'|'GREATER_THAN'|'IN'|'NOT_IN',
'value': 'string'
},
]
}
}
Response Structure
• (dict) –
Represents the result of a create device pool request.
– devicePool (dict) –
The newly created device pool.
* arn (string) –
The device pool’s ARN.
* name (string) –
The device pool’s name.
* description (string) –
The device pool’s description.
* type (string) –
The device pool’s type.
Allowed values include:
· CURATED: A device pool that is created and managed by
AWS Device Farm.
· PRIVATE: A device pool that is created and managed by the
device pool developer.
* rules (list) –
Information about the device pool’s rules.
· (dict) –
Represents a condition for a device pool.
· attribute (string) –
The rule’s attribute.
Allowed values include:
· ARN: The ARN.
· FORM_FACTOR: The form factor (for example, phone or
tablet).
· MANUFACTURER: The manufacturer.
· PLATFORM: The platform (for example, Android or iOS).
· operator (string) –
The rule’s operator.
· EQUALS: The equals operator.
· GREATER_THAN: The greater-than operator.
· IN: The in operator.
644 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· LESS_THAN: The less-than operator.
· NOT_IN: The not-in operator.
· value (string) –
The rule’s value.
create_project(**kwargs)
Creates a new project.
Request Syntax
response = client.create_project(
name='string'
)
Parameters name (string) – [REQUIRED]
The project’s name.
Return type dict
Returns
Response Syntax
{
'project': {
'arn': 'string',
'name': 'string',
'created': datetime(2015, 1, 1)
}
}
Response Structure
• (dict) –
Represents the result of a create project request.
– project (dict) –
The newly created project.
* arn (string) –
The project’s ARN.
* name (string) –
The project’s name.
* created (datetime) –
When the project was created.
create_upload(**kwargs)
Uploads an app or test scripts.
Request Syntax
response = client.create_upload(
projectArn='string',
name='string',
type='ANDROID_APP'|'IOS_APP'|'EXTERNAL_DATA'|'APPIUM_JAVA_JUNIT_TEST_PACKAGE'|'APPIUM_JA
contentType='string'
)
Parameters
3.1. Services 645
Boto3 Documentation, Release 1.1.4
• projectArn (string) – [REQUIRED]
The ARN of the project for the upload.
• name (string) – [REQUIRED]
The upload’s file name.
• type (string) – [REQUIRED]
The upload’s upload type.
Must be one of the following values:
– ANDROID_APP: An Android upload.
– IOS_APP: An iOS upload.
– EXTERNAL_DATA: An external data upload.
– APPIUM_JAVA_JUNIT_TEST_PACKAGE: An Appium Java JUnit test
package upload.
– APPIUM_JAVA_TESTNG_TEST_PACKAGE: An Appium Java TestNG
test package upload.
– CALABASH_TEST_PACKAGE: A Calabash test package upload.
– INSTRUMENTATION_TEST_PACKAGE: An instrumentation upload.
– UIAUTOMATOR_TEST_PACKAGE: A uiautomator test package up-
load.
– XCTEST_TEST_PACKAGE: An XCode test package upload.
• contentType (string) – The upload’s content type (for example,
“application/octet-stream”).
Return type dict
Returns
Response Syntax
{
'upload': {
'arn': 'string',
'name': 'string',
'created': datetime(2015, 1, 1),
'type': 'ANDROID_APP'|'IOS_APP'|'EXTERNAL_DATA'|'APPIUM_JAVA_JUNIT_TEST_PA
'status': 'INITIALIZED'|'PROCESSING'|'SUCCEEDED'|'FAILED',
'url': 'string',
'metadata': 'string',
'contentType': 'string',
'message': 'string'
}
}
Response Structure
• (dict) –
Represents the result of a create upload request.
– upload (dict) –
The newly created upload.
* arn (string) –
The upload’s ARN.
* name (string) –
The upload’s file name.
* created (datetime) –
When the upload was created.
646 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* type (string) –
The upload’s type.
Must be one of the following values:
· ANDROID_APP: An Android upload.
· IOS_APP: An iOS upload.
· EXTERNAL_DATA: An external data upload.
· APPIUM_JAVA_JUNIT_TEST_PACKAGE: An Appium
Java JUnit test package upload.
· APPIUM_JAVA_TESTNG_TEST_PACKAGE: An Appium
Java TestNG test package upload.
· CALABASH_TEST_PACKAGE: A Calabash test package
upload.
· INSTRUMENTATION_TEST_PACKAGE: An instrumenta-
tion upload.
· UIAUTOMATOR_TEST_PACKAGE: A uiautomator test
package upload.
· XCTEST_TEST_PACKAGE: An XCode test package up-
load.
* status (string) –
The upload’s status.
Must be one of the following values:
· FAILED: A failed status.
· INITIALIZED: An initialized status.
· PROCESSING: A processing status.
· SUCCEEDED: A succeeded status.
* url (string) –
The pre-signed Amazon S3 URL that was used to store a file through
a corresponding PUT request.
* metadata (string) –
The upload’s metadata. For example, for Android, this contains in-
formation that is parsed from the manifest and is displayed in the
AWS Device Farm console after the associated app is uploaded.
* contentType (string) –
The upload’s content type (for example, “application/octet-
stream”).
* message (string) –
A message about the upload’s result.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_account_settings()
Returns the number of unmetered iOS and/or unmetered Android devices that have been purchased by the
3.1. Services 647
Boto3 Documentation, Release 1.1.4
account.
Request Syntax
response = client.get_account_settings()
Return type dict
Returns
Response Syntax
{
'accountSettings': {
'awsAccountNumber': 'string',
'unmeteredDevices': {
'string': 123
}
}
}
Response Structure
• (dict) –
– accountSettings (dict) –
A container for account-level settings within AWS Device Farm.
* awsAccountNumber (string) –
The AWS account number specified in the AccountSettings
container.
* unmeteredDevices (dict) –
Returns the unmetered devices you have purchased.
· (string) –
· (integer) –
get_device(**kwargs)
Gets information about a unique device type.
Request Syntax
response = client.get_device(
arn='string'
)
Parameters arn (string) – [REQUIRED]
The device type’s ARN.
Return type dict
Returns
Response Syntax
{
'device': {
'arn': 'string',
'name': 'string',
'manufacturer': 'string',
'model': 'string',
'formFactor': 'PHONE'|'TABLET',
'platform': 'ANDROID'|'IOS',
648 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'os': 'string',
'cpu': {
'frequency': 'string',
'architecture': 'string',
'clock': 123.0
},
'resolution': {
'width': 123,
'height': 123
},
'heapSize': 123,
'memory': 123,
'image': 'string',
'carrier': 'string',
'radio': 'string'
}
}
Response Structure
• (dict) –
Represents the result of a get device request.
– device (dict) –
Represents a device type that an app is tested against.
* arn (string) –
The device’s ARN.
* name (string) –
The device’s display name.
* manufacturer (string) –
The device’s manufacturer name.
* model (string) –
The device’s model name.
* formFactor (string) –
The device’s form factor.
Allowed values include:
· PHONE: The phone form factor.
· TABLET: The tablet form factor.
* platform (string) –
The device’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
* os (string) –
The device’s operating system type.
* cpu (dict) –
Information about the device’s CPU.
· frequency (string) –
The CPU’s frequency.
· architecture (string) –
3.1. Services 649
Boto3 Documentation, Release 1.1.4
The CPU’s architecture, for example x86 or ARM.
· clock (float) –
The clock speed of the device’s CPU, expressed in hertz (Hz).
For example, a 1.2 GHz CPU is expressed as 1200000000.
* resolution (dict) –
Represents the screen resolution of a device in height and width,
expressed in pixels.
· width (integer) –
The screen resolution’s width, expressed in pixels.
· height (integer) –
The screen resolution’s height, expressed in pixels.
* heapSize (integer) –
The device’s heap size, expressed in bytes.
* memory (integer) –
The device’s total memory size, expressed in bytes.
* image (string) –
The device’s image name.
* carrier (string) –
The device’s carrier.
* radio (string) –
The device’s radio.
get_device_pool(**kwargs)
Gets information about a device pool.
Request Syntax
response = client.get_device_pool(
arn='string'
)
Parameters arn (string) – [REQUIRED]
The device pool’s ARN.
Return type dict
Returns
Response Syntax
{
'devicePool': {
'arn': 'string',
'name': 'string',
'description': 'string',
'type': 'CURATED'|'PRIVATE',
'rules': [
{
'attribute': 'ARN'|'PLATFORM'|'FORM_FACTOR'|'MANUFACTURER',
'operator': 'EQUALS'|'LESS_THAN'|'GREATER_THAN'|'IN'|'NOT_IN',
'value': 'string'
},
]
650 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
}
}
Response Structure
• (dict) –
Represents the result of a get device pool request.
– devicePool (dict) –
Represents a collection of device types.
* arn (string) –
The device pool’s ARN.
* name (string) –
The device pool’s name.
* description (string) –
The device pool’s description.
* type (string) –
The device pool’s type.
Allowed values include:
· CURATED: A device pool that is created and managed by
AWS Device Farm.
· PRIVATE: A device pool that is created and managed by the
device pool developer.
* rules (list) –
Information about the device pool’s rules.
· (dict) –
Represents a condition for a device pool.
· attribute (string) –
The rule’s attribute.
Allowed values include:
· ARN: The ARN.
· FORM_FACTOR: The form factor (for example, phone or
tablet).
· MANUFACTURER: The manufacturer.
· PLATFORM: The platform (for example, Android or iOS).
· operator (string) –
The rule’s operator.
· EQUALS: The equals operator.
· GREATER_THAN: The greater-than operator.
· IN: The in operator.
· LESS_THAN: The less-than operator.
· NOT_IN: The not-in operator.
· value (string) –
The rule’s value.
get_device_pool_compatibility(**kwargs)
Gets information about compatibility with a device pool.
Request Syntax
3.1. Services 651
Boto3 Documentation, Release 1.1.4
response = client.get_device_pool_compatibility(
devicePoolArn='string',
appArn='string',
testType='BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_JAVA_TESTNG'|'CAL
)
Parameters
• devicePoolArn (string) – [REQUIRED]
The device pool’s ARN.
• appArn (string) – [REQUIRED]
The ARN of the app that is associated with the specified device pool.
• testType (string) – The test type for the specified device pool.
Allowed values include the following:
– BUILTIN_FUZZ: The built-in fuzz type.
– BUILTIN_EXPLORER: For Android, an app explorer that will traverse
an Android app, interacting with it and capturing screenshots at the same
time.
– APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
– APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
– CALABASH: The Calabash type.
– INSTRUMENTATION: The Instrumentation type.
– UIAUTOMATION: The uiautomation type.
– UIAUTOMATOR: The uiautomator type.
– XCTEST: The XCode test type.
Return type dict
Returns
Response Syntax
{
'compatibleDevices': [
{
'device': {
'arn': 'string',
'name': 'string',
'manufacturer': 'string',
'model': 'string',
'formFactor': 'PHONE'|'TABLET',
'platform': 'ANDROID'|'IOS',
'os': 'string',
'cpu': {
'frequency': 'string',
'architecture': 'string',
'clock': 123.0
},
'resolution': {
'width': 123,
'height': 123
},
'heapSize': 123,
'memory': 123,
'image': 'string',
'carrier': 'string',
'radio': 'string'
652 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
'compatible': True|False,
'incompatibilityMessages': [
{
'message': 'string',
'type': 'ARN'|'PLATFORM'|'FORM_FACTOR'|'MANUFACTURER'
},
]
},
],
'incompatibleDevices': [
{
'device': {
'arn': 'string',
'name': 'string',
'manufacturer': 'string',
'model': 'string',
'formFactor': 'PHONE'|'TABLET',
'platform': 'ANDROID'|'IOS',
'os': 'string',
'cpu': {
'frequency': 'string',
'architecture': 'string',
'clock': 123.0
},
'resolution': {
'width': 123,
'height': 123
},
'heapSize': 123,
'memory': 123,
'image': 'string',
'carrier': 'string',
'radio': 'string'
},
'compatible': True|False,
'incompatibilityMessages': [
{
'message': 'string',
'type': 'ARN'|'PLATFORM'|'FORM_FACTOR'|'MANUFACTURER'
},
]
},
]
}
Response Structure
• (dict) –
Represents the result of describe device pool compatibility request.
– compatibleDevices (list) –
Information about compatible devices.
* (dict) –
Represents a device pool compatibility result.
· device (dict) –
Represents a device type that an app is tested against.
3.1. Services 653
Boto3 Documentation, Release 1.1.4
· arn (string) –
The device’s ARN.
· name (string) –
The device’s display name.
· manufacturer (string) –
The device’s manufacturer name.
· model (string) –
The device’s model name.
· formFactor (string) –
The device’s form factor.
Allowed values include:
· PHONE: The phone form factor.
· TABLET: The tablet form factor.
· platform (string) –
The device’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
· os (string) –
The device’s operating system type.
· cpu (dict) –
Information about the device’s CPU.
· frequency (string) –
The CPU’s frequency.
· architecture (string) –
The CPU’s architecture, for example x86 or ARM.
· clock (float) –
The clock speed of the device’s CPU, expressed in hertz (Hz).
For example, a 1.2 GHz CPU is expressed as 1200000000.
· resolution (dict) –
Represents the screen resolution of a device in height and
width, expressed in pixels.
· width (integer) –
The screen resolution’s width, expressed in pixels.
· height (integer) –
The screen resolution’s height, expressed in pixels.
· heapSize (integer) –
The device’s heap size, expressed in bytes.
· memory (integer) –
The device’s total memory size, expressed in bytes.
· image (string) –
The device’s image name.
· carrier (string) –
The device’s carrier.
654 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· radio (string) –
The device’s radio.
· compatible (boolean) –
Whether the result was compatible with the device pool.
· incompatibilityMessages (list) –
Information about the compatibility.
· (dict) –
Represents information about incompatibility.
· message (string) –
A message about the incompatibility.
· type (string) –
The type of incompatibility.
Allowed values include:
· ARN: The ARN.
· FORM_FACTOR: The form factor (for example, phone or
tablet).
· MANUFACTURER: The manufacturer.
· PLATFORM: The platform (for example, Android or iOS).
– incompatibleDevices (list) –
Information about incompatible devices.
* (dict) –
Represents a device pool compatibility result.
· device (dict) –
Represents a device type that an app is tested against.
· arn (string) –
The device’s ARN.
· name (string) –
The device’s display name.
· manufacturer (string) –
The device’s manufacturer name.
· model (string) –
The device’s model name.
· formFactor (string) –
The device’s form factor.
Allowed values include:
· PHONE: The phone form factor.
· TABLET: The tablet form factor.
· platform (string) –
The device’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
· os (string) –
The device’s operating system type.
3.1. Services 655
Boto3 Documentation, Release 1.1.4
· cpu (dict) –
Information about the device’s CPU.
· frequency (string) –
The CPU’s frequency.
· architecture (string) –
The CPU’s architecture, for example x86 or ARM.
· clock (float) –
The clock speed of the device’s CPU, expressed in hertz (Hz).
For example, a 1.2 GHz CPU is expressed as 1200000000.
· resolution (dict) –
Represents the screen resolution of a device in height and
width, expressed in pixels.
· width (integer) –
The screen resolution’s width, expressed in pixels.
· height (integer) –
The screen resolution’s height, expressed in pixels.
· heapSize (integer) –
The device’s heap size, expressed in bytes.
· memory (integer) –
The device’s total memory size, expressed in bytes.
· image (string) –
The device’s image name.
· carrier (string) –
The device’s carrier.
· radio (string) –
The device’s radio.
· compatible (boolean) –
Whether the result was compatible with the device pool.
· incompatibilityMessages (list) –
Information about the compatibility.
· (dict) –
Represents information about incompatibility.
· message (string) –
A message about the incompatibility.
· type (string) –
The type of incompatibility.
Allowed values include:
· ARN: The ARN.
· FORM_FACTOR: The form factor (for example, phone or
tablet).
· MANUFACTURER: The manufacturer.
· PLATFORM: The platform (for example, Android or iOS).
get_job(**kwargs)
Gets information about a job.
656 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.get_job(
arn='string'
)
Parameters arn (string) – [REQUIRED]
The job’s ARN.
Return type dict
Returns
Response Syntax
{
'job': {
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_JAVA
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'STOPPE
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
'passed': 123,
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string',
'device': {
'arn': 'string',
'name': 'string',
'manufacturer': 'string',
'model': 'string',
'formFactor': 'PHONE'|'TABLET',
'platform': 'ANDROID'|'IOS',
'os': 'string',
'cpu': {
'frequency': 'string',
'architecture': 'string',
'clock': 123.0
},
'resolution': {
'width': 123,
'height': 123
},
'heapSize': 123,
'memory': 123,
'image': 'string',
'carrier': 'string',
'radio': 'string'
}
}
}
3.1. Services 657
Boto3 Documentation, Release 1.1.4
Response Structure
• (dict) –
Represents the result of a get job request.
– job (dict) –
Represents a device.
* arn (string) –
The job’s ARN.
* name (string) –
The job’s name.
* type (string) –
The job’s type.
Allowed values include the following:
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
ing screenshots at the same time.
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
* created (datetime) –
When the job was created.
* status (string) –
The job’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
* result (string) –
The job’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
* started (datetime) –
The job’s start time.
* stopped (datetime) –
The job’s stop time.
658 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* counters (dict) –
The job’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
· stopped (integer) –
The number of stopped entities.
· skipped (integer) –
The number of skipped entities.
* message (string) –
A message about the job’s result.
* device (dict) –
Represents a device type that an app is tested against.
· arn (string) –
The device’s ARN.
· name (string) –
The device’s display name.
· manufacturer (string) –
The device’s manufacturer name.
· model (string) –
The device’s model name.
· formFactor (string) –
The device’s form factor.
Allowed values include:
· PHONE: The phone form factor.
· TABLET: The tablet form factor.
· platform (string) –
The device’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
· os (string) –
The device’s operating system type.
· cpu (dict) –
Information about the device’s CPU.
3.1. Services 659
Boto3 Documentation, Release 1.1.4
· frequency (string) –
The CPU’s frequency.
· architecture (string) –
The CPU’s architecture, for example x86 or ARM.
· clock (float) –
The clock speed of the device’s CPU, expressed in hertz (Hz).
For example, a 1.2 GHz CPU is expressed as 1200000000.
· resolution (dict) –
Represents the screen resolution of a device in height and
width, expressed in pixels.
· width (integer) –
The screen resolution’s width, expressed in pixels.
· height (integer) –
The screen resolution’s height, expressed in pixels.
· heapSize (integer) –
The device’s heap size, expressed in bytes.
· memory (integer) –
The device’s total memory size, expressed in bytes.
· image (string) –
The device’s image name.
· carrier (string) –
The device’s carrier.
· radio (string) –
The device’s radio.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_project(**kwargs)
Gets information about a project.
Request Syntax
response = client.get_project(
arn='string'
)
Parameters arn (string) – [REQUIRED]
The project’s ARN.
Return type dict
660 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'project': {
'arn': 'string',
'name': 'string',
'created': datetime(2015, 1, 1)
}
}
Response Structure
• (dict) –
Represents the result of a get project request.
– project (dict) –
Represents an operating-system neutral workspace for running and man-
aging tests.
* arn (string) –
The project’s ARN.
* name (string) –
The project’s name.
* created (datetime) –
When the project was created.
get_run(**kwargs)
Gets information about a run.
Request Syntax
response = client.get_run(
arn='string'
)
Parameters arn (string) – [REQUIRED]
The run’s ARN.
Return type dict
Returns
Response Syntax
{
'run': {
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_JAVA
'platform': 'ANDROID'|'IOS',
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'STOPPE
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
'passed': 123,
3.1. Services 661
Boto3 Documentation, Release 1.1.4
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string',
'totalJobs': 123,
'completedJobs': 123,
'billingMethod': 'METERED'|'UNMETERED'
}
}
Response Structure
• (dict) –
Represents the result of a get run request.
– run (dict) –
Represents an app on a set of devices with a specific test and configuration.
* arn (string) –
The run’s ARN.
* name (string) –
The run’s name.
* type (string) –
The run’s type.
Must be one of the following values:
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
ing screenshots at the same time.
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
* platform (string) –
The run’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
* created (datetime) –
When the run was created.
* status (string) –
The run’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
662 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
* result (string) –
The run’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
* started (datetime) –
The run’s start time.
* stopped (datetime) –
The run’s stop time.
* counters (dict) –
The run’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
· stopped (integer) –
The number of stopped entities.
· skipped (integer) –
The number of skipped entities.
* message (string) –
A message about the run’s result.
* totalJobs (integer) –
The total number of jobs for the run.
* completedJobs (integer) –
The total number of completed jobs.
* billingMethod (string) –
Specifies the billing method for a test run: metered or
unmetered . If the parameter is not specified, the default value
is unmetered .
get_suite(**kwargs)
Gets information about a suite.
Request Syntax
3.1. Services 663
Boto3 Documentation, Release 1.1.4
response = client.get_suite(
arn='string'
)
Parameters arn (string) – [REQUIRED]
The suite’s ARN.
Return type dict
Returns
Response Syntax
{
'suite': {
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_JAVA
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'STOPPE
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
'passed': 123,
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string'
}
}
Response Structure
• (dict) –
Represents the result of a get suite request.
– suite (dict) –
Represents a collection of one or more tests.
* arn (string) –
The suite’s ARN.
* name (string) –
The suite’s name.
* type (string) –
The suite’s type.
Must be one of the following values:
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
ing screenshots at the same time.
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
664 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
* created (datetime) –
When the suite was created.
* status (string) –
The suite’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
* result (string) –
The suite’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
* started (datetime) –
The suite’s start time.
* stopped (datetime) –
The suite’s stop time.
* counters (dict) –
The suite’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
· stopped (integer) –
The number of stopped entities.
· skipped (integer) –
The number of skipped entities.
3.1. Services 665
Boto3 Documentation, Release 1.1.4
* message (string) –
A message about the suite’s result.
get_test(**kwargs)
Gets information about a test.
Request Syntax
response = client.get_test(
arn='string'
)
Parameters arn (string) – [REQUIRED]
The test’s ARN.
Return type dict
Returns
Response Syntax
{
'test': {
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_JAVA
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'STOPPE
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
'passed': 123,
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string'
}
}
Response Structure
• (dict) –
Represents the result of a get test request.
– test (dict) –
Represents a condition that is evaluated.
* arn (string) –
The test’s ARN.
* name (string) –
The test’s name.
* type (string) –
The test’s type.
Must be one of the following values:
666 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
ing screenshots at the same time.
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
* created (datetime) –
When the test was created.
* status (string) –
The test’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
* result (string) –
The test’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
* started (datetime) –
The test’s start time.
* stopped (datetime) –
The test’s stop time.
* counters (dict) –
The test’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
3.1. Services 667
Boto3 Documentation, Release 1.1.4
· stopped (integer) –
The number of stopped entities.
· skipped (integer) –
The number of skipped entities.
* message (string) –
A message about the test’s result.
get_upload(**kwargs)
Gets information about an upload.
Request Syntax
response = client.get_upload(
arn='string'
)
Parameters arn (string) – [REQUIRED]
The upload’s ARN.
Return type dict
Returns
Response Syntax
{
'upload': {
'arn': 'string',
'name': 'string',
'created': datetime(2015, 1, 1),
'type': 'ANDROID_APP'|'IOS_APP'|'EXTERNAL_DATA'|'APPIUM_JAVA_JUNIT_TEST_PA
'status': 'INITIALIZED'|'PROCESSING'|'SUCCEEDED'|'FAILED',
'url': 'string',
'metadata': 'string',
'contentType': 'string',
'message': 'string'
}
}
Response Structure
• (dict) –
Represents the result of a get upload request.
– upload (dict) –
An app or a set of one or more tests to upload or that have been uploaded.
* arn (string) –
The upload’s ARN.
* name (string) –
The upload’s file name.
* created (datetime) –
When the upload was created.
* type (string) –
The upload’s type.
Must be one of the following values:
668 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
·ANDROID_APP: An Android upload.
·IOS_APP: An iOS upload.
·EXTERNAL_DATA: An external data upload.
·APPIUM_JAVA_JUNIT_TEST_PACKAGE: An Appium
Java JUnit test package upload.
· APPIUM_JAVA_TESTNG_TEST_PACKAGE: An Appium
Java TestNG test package upload.
· CALABASH_TEST_PACKAGE: A Calabash test package
upload.
· INSTRUMENTATION_TEST_PACKAGE: An instrumenta-
tion upload.
· UIAUTOMATOR_TEST_PACKAGE: A uiautomator test
package upload.
· XCTEST_TEST_PACKAGE: An XCode test package up-
load.
* status (string) –
The upload’s status.
Must be one of the following values:
· FAILED: A failed status.
· INITIALIZED: An initialized status.
· PROCESSING: A processing status.
· SUCCEEDED: A succeeded status.
* url (string) –
The pre-signed Amazon S3 URL that was used to store a file through
a corresponding PUT request.
* metadata (string) –
The upload’s metadata. For example, for Android, this contains in-
formation that is parsed from the manifest and is displayed in the
AWS Device Farm console after the associated app is uploaded.
* contentType (string) –
The upload’s content type (for example, “application/octet-
stream”).
* message (string) –
A message about the upload’s result.
get_waiter(waiter_name)
list_artifacts(**kwargs)
Gets information about artifacts.
Request Syntax
response = client.list_artifacts(
arn='string',
type='SCREENSHOT'|'FILE'|'LOG',
nextToken='string'
)
Parameters
• arn (string) – [REQUIRED]
The Run, Job, Suite, or Test ARN.
3.1. Services 669
Boto3 Documentation, Release 1.1.4
• type (string) – [REQUIRED]
The artifacts’ type.
Allowed values include:
– FILE: The artifacts are files.
– LOG: The artifacts are logs.
– SCREENSHOT: The artifacts are screenshots.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'artifacts': [
{
'arn': 'string',
'name': 'string',
'type': 'UNKNOWN'|'SCREENSHOT'|'DEVICE_LOG'|'MESSAGE_LOG'|'RESULT_LOG'
'extension': 'string',
'url': 'string'
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list artifacts operation.
– artifacts (list) –
Information about the artifacts.
* (dict) –
Represents the output of a test. Examples of artifacts include logs
and screenshots.
· arn (string) –
The artifact’s ARN.
· name (string) –
The artifact’s name.
· type (string) –
The artifact’s type.
Allowed values include the following:
· APPIUM_JAVA_OUTPUT: The Appium Java output type.
· APPIUM_JAVA_XML_OUTPUT: The Appium Java XML
output type.
· APPIUM_SERVER_OUTPUT: The Appium server output
type.
· AUTOMATION_OUTPUT: The automation output type.
· CALABASH_JSON_OUTPUT: The Calabash JSON output
type.
· CALABASH_JAVA_XML_OUTPUT: The Calabash Java
XML output type.
670 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· CALABASH_PRETTY_OUTPUT: The Calabash pretty out-
put type.
· CALABASH_STANDARD_OUTPUT: The Calabash stan-
dard output type.
· DEVICE_LOG: The device log type.
· EXERCISER_MONKEY_OUTPUT: For Android, the arti-
fact (log) generated by an Android fuzz test.
· INSTRUMENTATION_OUTPUT: The instrumentation type.
· MESSAGE_LOG: The message log type.
· RESULT_LOG: The result log type.
· SCREENSHOT: The screenshot type.
· SERVICE_LOG: The service log type.
· UNKNOWN: An unknown type.
· extension (string) –
The artifact’s file extension.
· url (string) –
The pre-signed Amazon S3 URL that can be used with a cor-
responding GET request to download the artifact’s file.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
list_device_pools(**kwargs)
Gets information about device pools.
Request Syntax
response = client.list_device_pools(
arn='string',
type='CURATED'|'PRIVATE',
nextToken='string'
)
Parameters
• arn (string) – [REQUIRED]
The project ARN.
• type (string) – The device pools’ type.
Allowed values include:
– CURATED: A device pool that is created and managed by AWS Device
Farm.
– PRIVATE: A device pool that is created and managed by the device pool
developer.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'devicePools': [
{
3.1. Services 671
Boto3 Documentation, Release 1.1.4
'arn': 'string',
'name': 'string',
'description': 'string',
'type': 'CURATED'|'PRIVATE',
'rules': [
{
'attribute': 'ARN'|'PLATFORM'|'FORM_FACTOR'|'MANUFACTURER',
'operator': 'EQUALS'|'LESS_THAN'|'GREATER_THAN'|'IN'|'NOT_IN',
'value': 'string'
},
]
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list device pools request.
– devicePools (list) –
Information about the device pools.
* (dict) –
Represents a collection of device types.
· arn (string) –
The device pool’s ARN.
· name (string) –
The device pool’s name.
· description (string) –
The device pool’s description.
· type (string) –
The device pool’s type.
Allowed values include:
· CURATED: A device pool that is created and managed by
AWS Device Farm.
· PRIVATE: A device pool that is created and managed by the
device pool developer.
· rules (list) –
Information about the device pool’s rules.
· (dict) –
Represents a condition for a device pool.
· attribute (string) –
The rule’s attribute.
Allowed values include:
· ARN: The ARN.
· FORM_FACTOR: The form factor (for example, phone or
tablet).
· MANUFACTURER: The manufacturer.
· PLATFORM: The platform (for example, Android or iOS).
672 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· operator (string) –
The rule’s operator.
· EQUALS: The equals operator.
· GREATER_THAN: The greater-than operator.
· IN: The in operator.
· LESS_THAN: The less-than operator.
· NOT_IN: The not-in operator.
· value (string) –
The rule’s value.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
list_devices(**kwargs)
Gets information about unique device types.
Request Syntax
response = client.list_devices(
arn='string',
nextToken='string'
)
Parameters
• arn (string) – The device types’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'devices': [
{
'arn': 'string',
'name': 'string',
'manufacturer': 'string',
'model': 'string',
'formFactor': 'PHONE'|'TABLET',
'platform': 'ANDROID'|'IOS',
'os': 'string',
'cpu': {
'frequency': 'string',
'architecture': 'string',
'clock': 123.0
},
'resolution': {
'width': 123,
'height': 123
},
'heapSize': 123,
'memory': 123,
'image': 'string',
'carrier': 'string',
3.1. Services 673
Boto3 Documentation, Release 1.1.4
'radio': 'string'
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list devices operation.
– devices (list) –
Information about the devices.
* (dict) –
Represents a device type that an app is tested against.
· arn (string) –
The device’s ARN.
· name (string) –
The device’s display name.
· manufacturer (string) –
The device’s manufacturer name.
· model (string) –
The device’s model name.
· formFactor (string) –
The device’s form factor.
Allowed values include:
· PHONE: The phone form factor.
· TABLET: The tablet form factor.
· platform (string) –
The device’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
· os (string) –
The device’s operating system type.
· cpu (dict) –
Information about the device’s CPU.
· frequency (string) –
The CPU’s frequency.
· architecture (string) –
The CPU’s architecture, for example x86 or ARM.
· clock (float) –
The clock speed of the device’s CPU, expressed in hertz (Hz).
For example, a 1.2 GHz CPU is expressed as 1200000000.
· resolution (dict) –
Represents the screen resolution of a device in height and
width, expressed in pixels.
674 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· width (integer) –
The screen resolution’s width, expressed in pixels.
· height (integer) –
The screen resolution’s height, expressed in pixels.
· heapSize (integer) –
The device’s heap size, expressed in bytes.
· memory (integer) –
The device’s total memory size, expressed in bytes.
· image (string) –
The device’s image name.
· carrier (string) –
The device’s carrier.
· radio (string) –
The device’s radio.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
list_jobs(**kwargs)
Gets information about jobs.
Request Syntax
response = client.list_jobs(
arn='string',
nextToken='string'
)
Parameters
• arn (string) – [REQUIRED]
The jobs’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'jobs': [
{
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'ST
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
3.1. Services 675
Boto3 Documentation, Release 1.1.4
'passed': 123,
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string',
'device': {
'arn': 'string',
'name': 'string',
'manufacturer': 'string',
'model': 'string',
'formFactor': 'PHONE'|'TABLET',
'platform': 'ANDROID'|'IOS',
'os': 'string',
'cpu': {
'frequency': 'string',
'architecture': 'string',
'clock': 123.0
},
'resolution': {
'width': 123,
'height': 123
},
'heapSize': 123,
'memory': 123,
'image': 'string',
'carrier': 'string',
'radio': 'string'
}
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list jobs request.
– jobs (list) –
Information about the jobs.
* (dict) –
Represents a device.
· arn (string) –
The job’s ARN.
· name (string) –
The job’s name.
· type (string) –
The job’s type.
Allowed values include the following:
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
676 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
ing screenshots at the same time.
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
· created (datetime) –
When the job was created.
· status (string) –
The job’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
· result (string) –
The job’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
· started (datetime) –
The job’s start time.
· stopped (datetime) –
The job’s stop time.
· counters (dict) –
The job’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
· stopped (integer) –
The number of stopped entities.
3.1. Services 677
Boto3 Documentation, Release 1.1.4
· skipped (integer) –
The number of skipped entities.
· message (string) –
A message about the job’s result.
· device (dict) –
Represents a device type that an app is tested against.
· arn (string) –
The device’s ARN.
· name (string) –
The device’s display name.
· manufacturer (string) –
The device’s manufacturer name.
· model (string) –
The device’s model name.
· formFactor (string) –
The device’s form factor.
Allowed values include:
· PHONE: The phone form factor.
· TABLET: The tablet form factor.
· platform (string) –
The device’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
· os (string) –
The device’s operating system type.
· cpu (dict) –
Information about the device’s CPU.
· frequency (string) –
The CPU’s frequency.
· architecture (string) –
The CPU’s architecture, for example x86 or ARM.
· clock (float) –
The clock speed of the device’s CPU, expressed in hertz (Hz).
For example, a 1.2 GHz CPU is expressed as 1200000000.
· resolution (dict) –
Represents the screen resolution of a device in height and
width, expressed in pixels.
· width (integer) –
The screen resolution’s width, expressed in pixels.
· height (integer) –
The screen resolution’s height, expressed in pixels.
· heapSize (integer) –
The device’s heap size, expressed in bytes.
678 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· memory (integer) –
The device’s total memory size, expressed in bytes.
· image (string) –
The device’s image name.
· carrier (string) –
The device’s carrier.
· radio (string) –
The device’s radio.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
list_projects(**kwargs)
Gets information about projects.
Request Syntax
response = client.list_projects(
arn='string',
nextToken='string'
)
Parameters
• arn (string) – The projects’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'projects': [
{
'arn': 'string',
'name': 'string',
'created': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list projects request.
– projects (list) –
Information about the projects.
* (dict) –
Represents an operating-system neutral workspace for running and
managing tests.
3.1. Services 679
Boto3 Documentation, Release 1.1.4
· arn (string) –
The project’s ARN.
· name (string) –
The project’s name.
· created (datetime) –
When the project was created.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
list_runs(**kwargs)
Gets information about runs.
Request Syntax
response = client.list_runs(
arn='string',
nextToken='string'
)
Parameters
• arn (string) – [REQUIRED]
The runs’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'runs': [
{
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_
'platform': 'ANDROID'|'IOS',
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'ST
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
'passed': 123,
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string',
'totalJobs': 123,
'completedJobs': 123,
680 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'billingMethod': 'METERED'|'UNMETERED'
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list runs request.
– runs (list) –
Information about the runs.
* (dict) –
Represents an app on a set of devices with a specific test and con-
figuration.
· arn (string) –
The run’s ARN.
· name (string) –
The run’s name.
· type (string) –
The run’s type.
Must be one of the following values:
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
ing screenshots at the same time.
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
· platform (string) –
The run’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
· created (datetime) –
When the run was created.
· status (string) –
The run’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
3.1. Services 681
Boto3 Documentation, Release 1.1.4
· result (string) –
The run’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
· started (datetime) –
The run’s start time.
· stopped (datetime) –
The run’s stop time.
· counters (dict) –
The run’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
· stopped (integer) –
The number of stopped entities.
· skipped (integer) –
The number of skipped entities.
· message (string) –
A message about the run’s result.
· totalJobs (integer) –
The total number of jobs for the run.
· completedJobs (integer) –
The total number of completed jobs.
· billingMethod (string) –
Specifies the billing method for a test run: metered or
unmetered . If the parameter is not specified, the default
value is unmetered .
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
682 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
list_samples(**kwargs)
Gets information about samples.
Request Syntax
response = client.list_samples(
arn='string',
nextToken='string'
)
Parameters
• arn (string) – [REQUIRED]
The samples’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'samples': [
{
'arn': 'string',
'type': 'CPU'|'MEMORY'|'THREADS'|'RX_RATE'|'TX_RATE'|'RX'|'TX'|'NATIVE
'url': 'string'
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list samples request.
– samples (list) –
Information about the samples.
* (dict) –
Represents a sample of performance data.
· arn (string) –
The sample’s ARN.
· type (string) –
The sample’s type.
Must be one of the following values:
· CPU: A CPU sample type. This is expressed as the app pro-
cessing CPU time (including child processes) as reported by
process, as a percentage.
· MEMORY: A memory usage sample type. This is expressed
as the total proportional set size of an app process, in kilo-
bytes.
· NATIVE_AVG_DRAWTIME
· NATIVE_FPS
· NATIVE_FRAMES
· NATIVE_MAX_DRAWTIME
3.1. Services 683
Boto3 Documentation, Release 1.1.4
· NATIVE_MIN_DRAWTIME
· OPENGL_AVG_DRAWTIME
· OPENGL_FPS
· OPENGL_FRAMES
· OPENGL_MAX_DRAWTIME
· OPENGL_MIN_DRAWTIME
· RX
· RX_RATE: The total number of bytes per second (TCP and
UDP) that are sent, by app process.
· THREADS: A threads sample type. This is expressed as the
total number of threads per app process.
· TX
· TX_RATE: The total number of bytes per second (TCP and
UDP) that are received, by app process.
· url (string) –
The pre-signed Amazon S3 URL that can be used with a cor-
responding GET request to download the sample’s file.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
list_suites(**kwargs)
Gets information about suites.
Request Syntax
response = client.list_suites(
arn='string',
nextToken='string'
)
Parameters
• arn (string) – [REQUIRED]
The suites’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'suites': [
{
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'ST
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
684 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'passed': 123,
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string'
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list suites request.
– suites (list) –
Information about the suites.
* (dict) –
Represents a collection of one or more tests.
· arn (string) –
The suite’s ARN.
· name (string) –
The suite’s name.
· type (string) –
The suite’s type.
Must be one of the following values:
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
ing screenshots at the same time.
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
· created (datetime) –
When the suite was created.
· status (string) –
The suite’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
· result (string) –
3.1. Services 685
Boto3 Documentation, Release 1.1.4
The suite’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
· started (datetime) –
The suite’s start time.
· stopped (datetime) –
The suite’s stop time.
· counters (dict) –
The suite’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
· stopped (integer) –
The number of stopped entities.
· skipped (integer) –
The number of skipped entities.
· message (string) –
A message about the suite’s result.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
list_tests(**kwargs)
Gets information about tests.
Request Syntax
response = client.list_tests(
arn='string',
nextToken='string'
)
Parameters
686 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• arn (string) – [REQUIRED]
The tests’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'tests': [
{
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'ST
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
'passed': 123,
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string'
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list tests request.
– tests (list) –
Information about the tests.
* (dict) –
Represents a condition that is evaluated.
· arn (string) –
The test’s ARN.
· name (string) –
The test’s name.
· type (string) –
The test’s type.
Must be one of the following values:
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
ing screenshots at the same time.
3.1. Services 687
Boto3 Documentation, Release 1.1.4
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
· created (datetime) –
When the test was created.
· status (string) –
The test’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
· result (string) –
The test’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
· started (datetime) –
The test’s start time.
· stopped (datetime) –
The test’s stop time.
· counters (dict) –
The test’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
· stopped (integer) –
The number of stopped entities.
· skipped (integer) –
688 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The number of skipped entities.
· message (string) –
A message about the test’s result.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
list_unique_problems(**kwargs)
Gets information about unique problems.
Request Syntax
response = client.list_unique_problems(
arn='string',
nextToken='string'
)
Parameters
• arn (string) – [REQUIRED]
The unique problems’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'uniqueProblems': {
'string': [
{
'message': 'string',
'problems': [
{
'run': {
'arn': 'string',
'name': 'string'
},
'job': {
'arn': 'string',
'name': 'string'
},
'suite': {
'arn': 'string',
'name': 'string'
},
'test': {
'arn': 'string',
'name': 'string'
},
'device': {
'arn': 'string',
'name': 'string',
'manufacturer': 'string',
'model': 'string',
3.1. Services 689
Boto3 Documentation, Release 1.1.4
'formFactor': 'PHONE'|'TABLET',
'platform': 'ANDROID'|'IOS',
'os': 'string',
'cpu': {
'frequency': 'string',
'architecture': 'string',
'clock': 123.0
},
'resolution': {
'width': 123,
'height': 123
},
'heapSize': 123,
'memory': 123,
'image': 'string',
'carrier': 'string',
'radio': 'string'
},
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'
'message': 'string'
},
]
},
]
},
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list unique problems request.
– uniqueProblems (dict) –
Information about the unique problems.
Allowed values include:
* ERRORED: An error condition.
* FAILED: A failed condition.
* SKIPPED: A skipped condition.
* STOPPED: A stopped condition.
* PASSED: A passing condition.
* PENDING: A pending condition.
* WARNED: A warning condition.
* (string) –
· (list) –
· (dict) –
A collection of one or more problems, grouped by their result.
· message (string) –
A message about the unique problems’ result.
· problems (list) –
Information about the problems.
· (dict) –
Represents a specific warning or failure.
· run (dict) –
690 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Information about the associated run.
· arn (string) –
The problem detail’s ARN.
· name (string) –
The problem detail’s name.
· job (dict) –
Information about the associated job.
· arn (string) –
The problem detail’s ARN.
· name (string) –
The problem detail’s name.
· suite (dict) –
Information about the associated suite.
· arn (string) –
The problem detail’s ARN.
· name (string) –
The problem detail’s name.
· test (dict) –
Information about the associated test.
· arn (string) –
The problem detail’s ARN.
· name (string) –
The problem detail’s name.
· device (dict) –
Information about the associated device.
· arn (string) –
The device’s ARN.
· name (string) –
The device’s display name.
· manufacturer (string) –
The device’s manufacturer name.
· model (string) –
The device’s model name.
· formFactor (string) –
The device’s form factor.
Allowed values include:
· PHONE: The phone form factor.
· TABLET: The tablet form factor.
· platform (string) –
The device’s platform.
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
3.1. Services 691
Boto3 Documentation, Release 1.1.4
· os (string) –
The device’s operating system type.
· cpu (dict) –
Information about the device’s CPU.
· frequency (string) –
The CPU’s frequency.
· architecture (string) –
The CPU’s architecture, for example x86 or ARM.
· clock (float) –
The clock speed of the device’s CPU, expressed in hertz (Hz).
For example, a 1.2 GHz CPU is expressed as 1200000000.
· resolution (dict) –
Represents the screen resolution of a device in height and
width, expressed in pixels.
· width (integer) –
The screen resolution’s width, expressed in pixels.
· height (integer) –
The screen resolution’s height, expressed in pixels.
· heapSize (integer) –
The device’s heap size, expressed in bytes.
· memory (integer) –
The device’s total memory size, expressed in bytes.
· image (string) –
The device’s image name.
· carrier (string) –
The device’s carrier.
· radio (string) –
The device’s radio.
· result (string) –
The problem’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
· message (string) –
A message about the problem’s result.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
692 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
list_uploads(**kwargs)
Gets information about uploads.
Request Syntax
response = client.list_uploads(
arn='string',
nextToken='string'
)
Parameters
• arn (string) – [REQUIRED]
The uploads’ ARNs.
• nextToken (string) – An identifier that was returned from the previous call to
this operation, which can be used to return the next set of items in the list.
Return type dict
Returns
Response Syntax
{
'uploads': [
{
'arn': 'string',
'name': 'string',
'created': datetime(2015, 1, 1),
'type': 'ANDROID_APP'|'IOS_APP'|'EXTERNAL_DATA'|'APPIUM_JAVA_JUNIT_TES
'status': 'INITIALIZED'|'PROCESSING'|'SUCCEEDED'|'FAILED',
'url': 'string',
'metadata': 'string',
'contentType': 'string',
'message': 'string'
},
],
'nextToken': 'string'
}
Response Structure
• (dict) –
Represents the result of a list uploads request.
– uploads (list) –
Information about the uploads.
* (dict) –
An app or a set of one or more tests to upload or that have been
uploaded.
· arn (string) –
The upload’s ARN.
· name (string) –
The upload’s file name.
· created (datetime) –
When the upload was created.
· type (string) –
The upload’s type.
3.1. Services 693
Boto3 Documentation, Release 1.1.4
Must be one of the following values:
· ANDROID_APP: An Android upload.
· IOS_APP: An iOS upload.
· EXTERNAL_DATA: An external data upload.
· APPIUM_JAVA_JUNIT_TEST_PACKAGE: An Appium
Java JUnit test package upload.
· APPIUM_JAVA_TESTNG_TEST_PACKAGE: An Appium
Java TestNG test package upload.
· CALABASH_TEST_PACKAGE: A Calabash test package
upload.
· INSTRUMENTATION_TEST_PACKAGE: An instrumenta-
tion upload.
· UIAUTOMATOR_TEST_PACKAGE: A uiautomator test
package upload.
· XCTEST_TEST_PACKAGE: An XCode test package up-
load.
· status (string) –
The upload’s status.
Must be one of the following values:
· FAILED: A failed status.
· INITIALIZED: An initialized status.
· PROCESSING: A processing status.
· SUCCEEDED: A succeeded status.
· url (string) –
The pre-signed Amazon S3 URL that was used to store a file
through a corresponding PUT request.
· metadata (string) –
The upload’s metadata. For example, for Android, this con-
tains information that is parsed from the manifest and is dis-
played in the AWS Device Farm console after the associated
app is uploaded.
· contentType (string) –
The upload’s content type (for example, “application/octet-
stream”).
· message (string) –
A message about the upload’s result.
– nextToken (string) –
If the number of items that are returned is significantly large, this is an
identifier that is also returned, which can be used in a subsequent call to
this operation to return the next set of items in the list.
schedule_run(**kwargs)
Schedules a run.
Request Syntax
response = client.schedule_run(
projectArn='string',
appArn='string',
devicePoolArn='string',
name='string',
test={
694 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_JAVA_TESTNG'|'
'testPackageArn': 'string',
'filter': 'string',
'parameters': {
'string': 'string'
}
},
configuration={
'extraDataPackageArn': 'string',
'networkProfileArn': 'string',
'locale': 'string',
'location': {
'latitude': 123.0,
'longitude': 123.0
},
'radios': {
'wifi': True|False,
'bluetooth': True|False,
'nfc': True|False,
'gps': True|False
},
'auxiliaryApps': [
'string',
],
'billingMethod': 'METERED'|'UNMETERED'
}
)
Parameters
• projectArn (string) – [REQUIRED]
The ARN of the project for the run to be scheduled.
• appArn (string) – [REQUIRED]
The ARN of the app to schedule a run.
• devicePoolArn (string) – [REQUIRED]
The ARN of the device pool for the run to be scheduled.
• name (string) – The name for the run to be scheduled.
• test (dict) – [REQUIRED]
Information about the test for the run to be scheduled.
– type (string) – [REQUIRED]
The test’s type.
Must be one of the following values:
* BUILTIN_FUZZ: The built-in fuzz type.
* BUILTIN_EXPLORER: For Android, an app explorer that will tra-
verse an Android app, interacting with it and capturing screenshots
at the same time.
* APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
* APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
* CALABASH: The Calabash type.
* INSTRUMENTATION: The Instrumentation type.
* UIAUTOMATION: The uiautomation type.
* UIAUTOMATOR: The uiautomator type.
* XCTEST: The XCode test type.
– testPackageArn (string) –
3.1. Services 695
Boto3 Documentation, Release 1.1.4
The ARN of the uploaded test that will be run.
– filter (string) –
The test’s filter.
– parameters (dict) –
The test’s parameters, such as test framework parameters and fixture set-
tings.
* (string) –
· (string) –
• configuration (dict) – Information about the settings for the run to be scheduled.
– extraDataPackageArn (string) –
The ARN of the extra data for the run. The extra data is a .zip file that
AWS Device Farm will extract to external data for Android or the app’s
sandbox for iOS.
– networkProfileArn (string) –
Reserved for internal use.
– locale (string) –
Information about the locale that is used for the run.
– location (dict) –
Information about the location that is used for the run.
* latitude (float) – [REQUIRED]
The latitude.
* longitude (float) – [REQUIRED]
The longitude.
– radios (dict) –
Information about the radio states for the run.
* wifi (boolean) –
True if Wi-Fi is enabled at the beginning of the test; otherwise, false.
* bluetooth (boolean) –
True if Bluetooth is enabled at the beginning of the test; otherwise,
false.
* nfc (boolean) –
True if NFC is enabled at the beginning of the test; otherwise, false.
* gps (boolean) –
True if GPS is enabled at the beginning of the test; otherwise, false.
– auxiliaryApps (list) –
A list of auxiliary apps for the run.
* (string) –
– billingMethod (string) –
Specifies the billing method for a test run: metered or unmetered . If
the parameter is not specified, the default value is unmetered .
Return type dict
Returns
Response Syntax
696 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'run': {
'arn': 'string',
'name': 'string',
'type': 'BUILTIN_FUZZ'|'BUILTIN_EXPLORER'|'APPIUM_JAVA_JUNIT'|'APPIUM_JAVA
'platform': 'ANDROID'|'IOS',
'created': datetime(2015, 1, 1),
'status': 'PENDING'|'PROCESSING'|'SCHEDULING'|'RUNNING'|'COMPLETED',
'result': 'PENDING'|'PASSED'|'WARNED'|'FAILED'|'SKIPPED'|'ERRORED'|'STOPPE
'started': datetime(2015, 1, 1),
'stopped': datetime(2015, 1, 1),
'counters': {
'total': 123,
'passed': 123,
'failed': 123,
'warned': 123,
'errored': 123,
'stopped': 123,
'skipped': 123
},
'message': 'string',
'totalJobs': 123,
'completedJobs': 123,
'billingMethod': 'METERED'|'UNMETERED'
}
}
Response Structure
• (dict) –
Represents the result of a schedule run request.
– run (dict) –
Information about the scheduled run.
* arn (string) –
The run’s ARN.
* name (string) –
The run’s name.
* type (string) –
The run’s type.
Must be one of the following values:
· BUILTIN_FUZZ: The built-in fuzz type.
· BUILTIN_EXPLORER: For Android, an app explorer that
will traverse an Android app, interacting with it and captur-
ing screenshots at the same time.
· APPIUM_JAVA_JUNIT: The Appium Java JUnit type.
· APPIUM_JAVA_TESTNG: The Appium Java TestNG type.
· CALABASH: The Calabash type.
· INSTRUMENTATION: The Instrumentation type.
· UIAUTOMATION: The uiautomation type.
· UIAUTOMATOR: The uiautomator type.
· XCTEST: The XCode test type.
* platform (string) –
The run’s platform.
3.1. Services 697
Boto3 Documentation, Release 1.1.4
Allowed values include:
· ANDROID: The Android platform.
· IOS: The iOS platform.
* created (datetime) –
When the run was created.
* status (string) –
The run’s status.
Allowed values include:
· COMPLETED: A completed status.
· PENDING: A pending status.
· PROCESSING: A processing status.
· RUNNING: A running status.
· SCHEDULING: A scheduling status.
* result (string) –
The run’s result.
Allowed values include:
· ERRORED: An error condition.
· FAILED: A failed condition.
· SKIPPED: A skipped condition.
· STOPPED: A stopped condition.
· PASSED: A passing condition.
· PENDING: A pending condition.
· WARNED: A warning condition.
* started (datetime) –
The run’s start time.
* stopped (datetime) –
The run’s stop time.
* counters (dict) –
The run’s result counters.
· total (integer) –
The total number of entities.
· passed (integer) –
The number of passed entities.
· failed (integer) –
The number of failed entities.
· warned (integer) –
The number of warned entities.
· errored (integer) –
The number of errored entities.
· stopped (integer) –
The number of stopped entities.
· skipped (integer) –
The number of skipped entities.
* message (string) –
A message about the run’s result.
698 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* totalJobs (integer) –
The total number of jobs for the run.
* completedJobs (integer) –
The total number of completed jobs.
* billingMethod (string) –
Specifies the billing method for a test run: metered or
unmetered . If the parameter is not specified, the default value
is unmetered .
DirectConnect
Table of Contents
• DirectConnect
– Client
Client
class DirectConnect.Client
A low-level client representing AWS Direct Connect:
import boto3
client = boto3.client('directconnect')
These are the available methods:
•allocate_connection_on_interconnect()
•allocate_private_virtual_interface()
•allocate_public_virtual_interface()
•can_paginate()
•confirm_connection()
•confirm_private_virtual_interface()
•confirm_public_virtual_interface()
•create_connection()
•create_interconnect()
•create_private_virtual_interface()
•create_public_virtual_interface()
•delete_connection()
•delete_interconnect()
•delete_virtual_interface()
•describe_connections()
•describe_connections_on_interconnect()
•describe_interconnects()
•describe_locations()
•describe_virtual_gateways()
•describe_virtual_interfaces()
•generate_presigned_url()
•get_paginator()
•get_waiter()
3.1. Services 699
Boto3 Documentation, Release 1.1.4
allocate_connection_on_interconnect(**kwargs)
Creates a hosted connection on an interconnect.
Allocates a VLAN number and a specified amount of bandwidth for use by a hosted connection on the
given interconnect.
Request Syntax
response = client.allocate_connection_on_interconnect(
bandwidth='string',
connectionName='string',
ownerAccount='string',
interconnectId='string',
vlan=123
)
Parameters
• bandwidth (string) – [REQUIRED]
Bandwidth of the connection.
Example: “500Mbps “
Default: None
• connectionName (string) – [REQUIRED]
Name of the provisioned connection.
Example: “500M Connection to AWS “
Default: None
• ownerAccount (string) – [REQUIRED]
Numeric account Id of the customer for whom the connection will be provi-
sioned.
Example: 123443215678
Default: None
• interconnectId (string) – [REQUIRED]
ID of the interconnect on which the connection will be provisioned.
Example: dxcon-456abc78
Default: None
• vlan (integer) – [REQUIRED]
The dedicated VLAN provisioned to the connection.
Example: 101
Default: None
Return type dict
Returns
Response Syntax
{
'ownerAccount': 'string',
'connectionId': 'string',
'connectionName': 'string',
'connectionState': 'ordering'|'requested'|'pending'|'available'|'down'|'deleti
'region': 'string',
700 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'location': 'string',
'bandwidth': 'string',
'vlan': 123,
'partnerName': 'string'
}
Response Structure
• (dict) –
A connection represents the physical network connection between the AWS Di-
rect Connect location and the customer.
– ownerAccount (string) –
– connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
– connectionName (string) –
The name of the connection.
Example: “My Connection to AWS “
Default: None
– connectionState (string) – State of the connection.
* Ordering : The initial state of a hosted connection provisioned on
an interconnect. The connection stays in the ordering state until the
owner of the hosted connection confirms or declines the connection
order.
* Requested : The initial state of a standard connection. The con-
nection stays in the requested state until the Letter of Authorization
(LOA) is sent to the customer.
* Pending : The connection has been approved, and is being initial-
ized.
* Available : The network link is up, and the connection is ready for
use.
* Down : The network link is down.
* Deleted : The connection has been deleted.
* Rejected : A hosted connection in the ‘Ordering’ state will enter
the ‘Rejected’ state if it is deleted by the end customer.
– region (string) –
The AWS region where the connection is located.
Example: us-east-1
Default: None
– location (string) –
Where the connection is located.
Example: EqSV5
Default: None
– bandwidth (string) –
Bandwidth of the connection.
Example: 1Gbps (for regular connections), or 500Mbps (for hosted con-
nections)
3.1. Services 701
Boto3 Documentation, Release 1.1.4
Default: None
– vlan (integer) –
The VLAN ID.
Example: 101
– partnerName (string) –
allocate_private_virtual_interface(**kwargs)
Provisions a private virtual interface to be owned by a different customer.
The owner of a connection calls this function to provision a private virtual interface which will be owned
by another AWS customer.
Virtual interfaces created using this function must be confirmed by the virtual interface owner by call-
ing ConfirmPrivateVirtualInterface. Until this step has been completed, the virtual interface will be in
‘Confirming’ state, and will not be available for handling traffic.
Request Syntax
response = client.allocate_private_virtual_interface(
connectionId='string',
ownerAccount='string',
newPrivateVirtualInterfaceAllocation={
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
'customerAddress': 'string'
}
)
Parameters
• connectionId (string) – [REQUIRED]
The connection ID on which the private virtual interface is provisioned.
Default: None
• ownerAccount (string) – [REQUIRED]
The AWS account that will own the new private virtual interface.
Default: None
• newPrivateVirtualInterfaceAllocation (dict) – [REQUIRED]
Detailed information for the private virtual interface to be provisioned.
Default: None
– virtualInterfaceName (string) – [REQUIRED]
The name of the virtual interface assigned by the customer.
Example: “My VPC”
– vlan (integer) – [REQUIRED]
The VLAN ID.
Example: 101
– asn (integer) – [REQUIRED]
Autonomous system (AS) number for Border Gateway Protocol (BGP)
configuration.
702 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Example: 65000
– authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
– amazonAddress (string) –
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
– customerAddress (string) –
IP address assigned to the customer interface.
Example: 192.168.1.2/30
Return type dict
Returns
Response Syntax
{
'ownerAccount': 'string',
'virtualInterfaceId': 'string',
'location': 'string',
'connectionId': 'string',
'virtualInterfaceType': 'string',
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
'customerAddress': 'string',
'virtualInterfaceState': 'confirming'|'verifying'|'pending'|'available'|'delet
'customerRouterConfig': 'string',
'virtualGatewayId': 'string',
'routeFilterPrefixes': [
{
'cidr': 'string'
},
]
}
Response Structure
• (dict) –
A virtual interface (VLAN) transmits the traffic between the AWS Direct Con-
nect location and the customer.
– ownerAccount (string) –
– virtualInterfaceId (string) –
ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
– location (string) –
Where the connection is located.
Example: EqSV5
Default: None
3.1. Services 703
Boto3 Documentation, Release 1.1.4
– connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
– virtualInterfaceType (string) –
The type of virtual interface.
Example: private (Amazon VPC) or public (Amazon S3, Amazon Dy-
namoDB, and so on.)
– virtualInterfaceName (string) –
The name of the virtual interface assigned by the customer.
Example: “My VPC”
– vlan (integer) –
The VLAN ID.
Example: 101
– asn (integer) –
Autonomous system (AS) number for Border Gateway Protocol (BGP)
configuration.
Example: 65000
– authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
– amazonAddress (string) –
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
– customerAddress (string) –
IP address assigned to the customer interface.
Example: 192.168.1.2/30
– virtualInterfaceState (string) – State of the virtual interface.
* Confirming : The creation of the virtual interface is pending confir-
mation from the virtual interface owner. If the owner of the virtual
interface is different from the owner of the connection on which it is
provisioned, then the virtual interface will remain in this state until
it is confirmed by the virtual interface owner.
* Verifying : This state only applies to public virtual interfaces. Each
public virtual interface needs validation before the virtual interface
can be created.
* Pending : A virtual interface is in this state from the time that it is
created until the virtual interface is ready to forward traffic.
* Available : A virtual interface that is able to forward traffic.
* Deleting : A virtual interface is in this state immediately after call-
ing DeleteVirtualInterface until it can no longer forward traffic.
* Deleted : A virtual interface that cannot forward traffic.
* Rejected : The virtual interface owner has declined creation of the
virtual interface. If a virtual interface in the ‘Confirming’ state is
704 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
deleted by the virtual interface owner, the virtual interface will enter
the ‘Rejected’ state.
– customerRouterConfig (string) –
Information for generating the customer router configuration.
– virtualGatewayId (string) –
The ID of the virtual private gateway to a VPC. This only applies to private
virtual interfaces.
Example: vgw-123er56
– routeFilterPrefixes (list) –
A list of routes to be advertised to the AWS network in this region (public
virtual interface) or your VPC (private virtual interface).
* (dict) –
A route filter prefix that the customer can advertise through Border
Gateway Protocol (BGP) over a public virtual interface.
· cidr (string) –
CIDR notation for the advertised route. Multiple routes are
separated by commas.
Example: 10.10.10.0/24,10.10.11.0/24
allocate_public_virtual_interface(**kwargs)
Provisions a public virtual interface to be owned by a different customer.
The owner of a connection calls this function to provision a public virtual interface which will be owned
by another AWS customer.
Virtual interfaces created using this function must be confirmed by the virtual interface owner by call-
ing ConfirmPublicVirtualInterface. Until this step has been completed, the virtual interface will be in
‘Confirming’ state, and will not be available for handling traffic.
Request Syntax
response = client.allocate_public_virtual_interface(
connectionId='string',
ownerAccount='string',
newPublicVirtualInterfaceAllocation={
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
'customerAddress': 'string',
'routeFilterPrefixes': [
{
'cidr': 'string'
},
]
}
)
Parameters
• connectionId (string) – [REQUIRED]
The connection ID on which the public virtual interface is provisioned.
Default: None
3.1. Services 705
Boto3 Documentation, Release 1.1.4
• ownerAccount (string) – [REQUIRED]
The AWS account that will own the new public virtual interface.
Default: None
• newPublicVirtualInterfaceAllocation (dict) – [REQUIRED]
Detailed information for the public virtual interface to be provisioned.
Default: None
– virtualInterfaceName (string) – [REQUIRED]
The name of the virtual interface assigned by the customer.
Example: “My VPC”
– vlan (integer) – [REQUIRED]
The VLAN ID.
Example: 101
– asn (integer) – [REQUIRED]
Autonomous system (AS) number for Border Gateway Protocol (BGP)
configuration.
Example: 65000
– authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
– amazonAddress (string) – [REQUIRED]
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
– customerAddress (string) – [REQUIRED]
IP address assigned to the customer interface.
Example: 192.168.1.2/30
– routeFilterPrefixes (list) – [REQUIRED]
A list of routes to be advertised to the AWS network in this region (public
virtual interface) or your VPC (private virtual interface).
* (dict) –
A route filter prefix that the customer can advertise through Border
Gateway Protocol (BGP) over a public virtual interface.
· cidr (string) –
CIDR notation for the advertised route. Multiple routes are
separated by commas.
Example: 10.10.10.0/24,10.10.11.0/24
Return type dict
Returns
Response Syntax
{
'ownerAccount': 'string',
'virtualInterfaceId': 'string',
'location': 'string',
706 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'connectionId': 'string',
'virtualInterfaceType': 'string',
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
'customerAddress': 'string',
'virtualInterfaceState': 'confirming'|'verifying'|'pending'|'available'|'delet
'customerRouterConfig': 'string',
'virtualGatewayId': 'string',
'routeFilterPrefixes': [
{
'cidr': 'string'
},
]
}
Response Structure
• (dict) –
A virtual interface (VLAN) transmits the traffic between the AWS Direct Con-
nect location and the customer.
– ownerAccount (string) –
– virtualInterfaceId (string) –
ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
– location (string) –
Where the connection is located.
Example: EqSV5
Default: None
– connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
– virtualInterfaceType (string) –
The type of virtual interface.
Example: private (Amazon VPC) or public (Amazon S3, Amazon Dy-
namoDB, and so on.)
– virtualInterfaceName (string) –
The name of the virtual interface assigned by the customer.
Example: “My VPC”
– vlan (integer) –
The VLAN ID.
Example: 101
– asn (integer) –
3.1. Services 707
Boto3 Documentation, Release 1.1.4
Autonomous system (AS) number for Border Gateway Protocol (BGP)
configuration.
Example: 65000
– authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
– amazonAddress (string) –
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
– customerAddress (string) –
IP address assigned to the customer interface.
Example: 192.168.1.2/30
– virtualInterfaceState (string) – State of the virtual interface.
* Confirming : The creation of the virtual interface is pending confir-
mation from the virtual interface owner. If the owner of the virtual
interface is different from the owner of the connection on which it is
provisioned, then the virtual interface will remain in this state until
it is confirmed by the virtual interface owner.
* Verifying : This state only applies to public virtual interfaces. Each
public virtual interface needs validation before the virtual interface
can be created.
* Pending : A virtual interface is in this state from the time that it is
created until the virtual interface is ready to forward traffic.
* Available : A virtual interface that is able to forward traffic.
* Deleting : A virtual interface is in this state immediately after call-
ing DeleteVirtualInterface until it can no longer forward traffic.
* Deleted : A virtual interface that cannot forward traffic.
* Rejected : The virtual interface owner has declined creation of the
virtual interface. If a virtual interface in the ‘Confirming’ state is
deleted by the virtual interface owner, the virtual interface will enter
the ‘Rejected’ state.
– customerRouterConfig (string) –
Information for generating the customer router configuration.
– virtualGatewayId (string) –
The ID of the virtual private gateway to a VPC. This only applies to private
virtual interfaces.
Example: vgw-123er56
– routeFilterPrefixes (list) –
A list of routes to be advertised to the AWS network in this region (public
virtual interface) or your VPC (private virtual interface).
* (dict) –
A route filter prefix that the customer can advertise through Border
Gateway Protocol (BGP) over a public virtual interface.
· cidr (string) –
CIDR notation for the advertised route. Multiple routes are
separated by commas.
Example: 10.10.10.0/24,10.10.11.0/24
708 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
confirm_connection(**kwargs)
Confirm the creation of a hosted connection on an interconnect.
Upon creation, the hosted connection is initially in the ‘Ordering’ state, and will remain in this state until
the owner calls ConfirmConnection to confirm creation of the hosted connection.
Request Syntax
response = client.confirm_connection(
connectionId='string'
)
Parameters connectionId (string) – [REQUIRED]
ID of the connection.
Example: dxcon-fg5678gh
Default: None
Return type dict
Returns
Response Syntax
{
'connectionState': 'ordering'|'requested'|'pending'|'available'|'down'|'deleti
}
Response Structure
• (dict) –
The response received when ConfirmConnection is called.
– connectionState (string) – State of the connection.
* Ordering : The initial state of a hosted connection provisioned on
an interconnect. The connection stays in the ordering state until the
owner of the hosted connection confirms or declines the connection
order.
* Requested : The initial state of a standard connection. The con-
nection stays in the requested state until the Letter of Authorization
(LOA) is sent to the customer.
* Pending : The connection has been approved, and is being initial-
ized.
* Available : The network link is up, and the connection is ready for
use.
* Down : The network link is down.
* Deleted : The connection has been deleted.
* Rejected : A hosted connection in the ‘Ordering’ state will enter
the ‘Rejected’ state if it is deleted by the end customer.
3.1. Services 709
Boto3 Documentation, Release 1.1.4
confirm_private_virtual_interface(**kwargs)
Accept ownership of a private virtual interface created by another customer.
After the virtual interface owner calls this function, the virtual interface will be created and attached to
the given virtual private gateway, and will be available for handling traffic.
Request Syntax
response = client.confirm_private_virtual_interface(
virtualInterfaceId='string',
virtualGatewayId='string'
)
Parameters
• virtualInterfaceId (string) – [REQUIRED]
ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
• virtualGatewayId (string) – [REQUIRED]
ID of the virtual private gateway that will be attached to the virtual interface.
A virtual private gateway can be managed via the Amazon Virtual Private Cloud
(VPC) console or the EC2 CreateVpnGateway action.
Default: None
Return type dict
Returns
Response Syntax
{
'virtualInterfaceState': 'confirming'|'verifying'|'pending'|'available'|'delet
}
Response Structure
• (dict) –
The response received when ConfirmPrivateVirtualInterface is called.
– virtualInterfaceState (string) – State of the virtual interface.
* Confirming : The creation of the virtual interface is pending confir-
mation from the virtual interface owner. If the owner of the virtual
interface is different from the owner of the connection on which it is
provisioned, then the virtual interface will remain in this state until
it is confirmed by the virtual interface owner.
* Verifying : This state only applies to public virtual interfaces. Each
public virtual interface needs validation before the virtual interface
can be created.
* Pending : A virtual interface is in this state from the time that it is
created until the virtual interface is ready to forward traffic.
* Available : A virtual interface that is able to forward traffic.
* Deleting : A virtual interface is in this state immediately after call-
ing DeleteVirtualInterface until it can no longer forward traffic.
* Deleted : A virtual interface that cannot forward traffic.
* Rejected : The virtual interface owner has declined creation of the
virtual interface. If a virtual interface in the ‘Confirming’ state is
710 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
deleted by the virtual interface owner, the virtual interface will enter
the ‘Rejected’ state.
confirm_public_virtual_interface(**kwargs)
Accept ownership of a public virtual interface created by another customer.
After the virtual interface owner calls this function, the specified virtual interface will be created and made
available for handling traffic.
Request Syntax
response = client.confirm_public_virtual_interface(
virtualInterfaceId='string'
)
Parameters virtualInterfaceId (string) – [REQUIRED]
ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
Return type dict
Returns
Response Syntax
{
'virtualInterfaceState': 'confirming'|'verifying'|'pending'|'available'|'delet
}
Response Structure
• (dict) –
The response received when ConfirmPublicVirtualInterface is called.
– virtualInterfaceState (string) – State of the virtual interface.
* Confirming : The creation of the virtual interface is pending confir-
mation from the virtual interface owner. If the owner of the virtual
interface is different from the owner of the connection on which it is
provisioned, then the virtual interface will remain in this state until
it is confirmed by the virtual interface owner.
* Verifying : This state only applies to public virtual interfaces. Each
public virtual interface needs validation before the virtual interface
can be created.
* Pending : A virtual interface is in this state from the time that it is
created until the virtual interface is ready to forward traffic.
* Available : A virtual interface that is able to forward traffic.
* Deleting : A virtual interface is in this state immediately after call-
ing DeleteVirtualInterface until it can no longer forward traffic.
* Deleted : A virtual interface that cannot forward traffic.
* Rejected : The virtual interface owner has declined creation of the
virtual interface. If a virtual interface in the ‘Confirming’ state is
deleted by the virtual interface owner, the virtual interface will enter
the ‘Rejected’ state.
create_connection(**kwargs)
Creates a new connection between the customer network and a specific AWS Direct Connect location.
A connection links your internal network to an AWS Direct Connect location over a standard 1 gigabit
or 10 gigabit Ethernet fiber-optic cable. One end of the cable is connected to your router, the other to an
3.1. Services 711
Boto3 Documentation, Release 1.1.4
AWS Direct Connect router. An AWS Direct Connect location provides access to Amazon Web Services
in the region it is associated with. You can establish connections with AWS Direct Connect locations in
multiple regions, but a connection in one region does not provide connectivity to other regions.
Request Syntax
response = client.create_connection(
location='string',
bandwidth='string',
connectionName='string'
)
Parameters
• location (string) – [REQUIRED]
Where the connection is located.
Example: EqSV5
Default: None
• bandwidth (string) – [REQUIRED]
Bandwidth of the connection.
Example: 1Gbps
Default: None
• connectionName (string) – [REQUIRED]
The name of the connection.
Example: “My Connection to AWS “
Default: None
Return type dict
Returns
Response Syntax
{
'ownerAccount': 'string',
'connectionId': 'string',
'connectionName': 'string',
'connectionState': 'ordering'|'requested'|'pending'|'available'|'down'|'deleti
'region': 'string',
'location': 'string',
'bandwidth': 'string',
'vlan': 123,
'partnerName': 'string'
}
Response Structure
• (dict) –
A connection represents the physical network connection between the AWS Di-
rect Connect location and the customer.
– ownerAccount (string) –
– connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
712 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Default: None
– connectionName (string) –
The name of the connection.
Example: “My Connection to AWS “
Default: None
– connectionState (string) – State of the connection.
* Ordering : The initial state of a hosted connection provisioned on
an interconnect. The connection stays in the ordering state until the
owner of the hosted connection confirms or declines the connection
order.
* Requested : The initial state of a standard connection. The con-
nection stays in the requested state until the Letter of Authorization
(LOA) is sent to the customer.
* Pending : The connection has been approved, and is being initial-
ized.
* Available : The network link is up, and the connection is ready for
use.
* Down : The network link is down.
* Deleted : The connection has been deleted.
* Rejected : A hosted connection in the ‘Ordering’ state will enter
the ‘Rejected’ state if it is deleted by the end customer.
– region (string) –
The AWS region where the connection is located.
Example: us-east-1
Default: None
– location (string) –
Where the connection is located.
Example: EqSV5
Default: None
– bandwidth (string) –
Bandwidth of the connection.
Example: 1Gbps (for regular connections), or 500Mbps (for hosted con-
nections)
Default: None
– vlan (integer) –
The VLAN ID.
Example: 101
– partnerName (string) –
create_interconnect(**kwargs)
Creates a new interconnect between a AWS Direct Connect partner’s network and a specific AWS Direct
Connect location.
An interconnect is a connection which is capable of hosting other connections. The AWS Direct Connect
partner can use an interconnect to provide sub-1Gbps AWS Direct Connect service to tier 2 customers
who do not have their own connections. Like a standard connection, an interconnect links the AWS
Direct Connect partner’s network to an AWS Direct Connect location over a standard 1 Gbps or 10 Gbps
3.1. Services 713
Boto3 Documentation, Release 1.1.4
Ethernet fiber-optic cable. One end is connected to the partner’s router, the other to an AWS Direct
Connect router.
For each end customer, the AWS Direct Connect partner provisions a connection on their interconnect
by calling AllocateConnectionOnInterconnect. The end customer can then connect to AWS resources by
creating a virtual interface on their connection, using the VLAN assigned to them by the AWS Direct
Connect partner.
Request Syntax
response = client.create_interconnect(
interconnectName='string',
bandwidth='string',
location='string'
)
Parameters
• interconnectName (string) – [REQUIRED]
The name of the interconnect.
Example: “1G Interconnect to AWS “
Default: None
• bandwidth (string) – [REQUIRED]
The port bandwidth
Example: 1Gbps
Default: None
Available values: 1Gbps,10Gbps
• location (string) – [REQUIRED]
Where the interconnect is located
Example: EqSV5
Default: None
Return type dict
Returns
Response Syntax
{
'interconnectId': 'string',
'interconnectName': 'string',
'interconnectState': 'requested'|'pending'|'available'|'down'|'deleting'|'dele
'region': 'string',
'location': 'string',
'bandwidth': 'string'
}
Response Structure
• (dict) –
An interconnect is a connection that can host other connections.
Like a standard AWS Direct Connect connection, an interconnect represents the
physical connection between an AWS Direct Connect partner’s network and a
specific Direct Connect location. An AWS Direct Connect partner who owns
an interconnect can provision hosted connections on the interconnect for their
714 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
end customers, thereby providing the end customers with connectivity to AWS
services.
The resources of the interconnect, including bandwidth and VLAN numbers, are
shared by all of the hosted connections on the interconnect, and the owner of the
interconnect determines how these resources are assigned.
– interconnectId (string) –
The ID of the interconnect.
Example: dxcon-abc123
– interconnectName (string) –
The name of the interconnect.
Example: “1G Interconnect to AWS “
– interconnectState (string) – State of the interconnect.
* Requested : The initial state of an interconnect. The interconnect
stays in the requested state until the Letter of Authorization (LOA)
is sent to the customer.
* Pending : The interconnect has been approved, and is being initial-
ized.
* Available : The network link is up, and the interconnect is ready for
use.
* Down : The network link is down.
* Deleted : The interconnect has been deleted.
– region (string) –
The AWS region where the connection is located.
Example: us-east-1
Default: None
– location (string) –
Where the connection is located.
Example: EqSV5
Default: None
– bandwidth (string) –
Bandwidth of the connection.
Example: 1Gbps
Default: None
create_private_virtual_interface(**kwargs)
Creates a new private virtual interface. A virtual interface is the VLAN that transports AWS Direct
Connect traffic. A private virtual interface supports sending traffic to a single virtual private cloud (VPC).
Request Syntax
response = client.create_private_virtual_interface(
connectionId='string',
newPrivateVirtualInterface={
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
3.1. Services 715
Boto3 Documentation, Release 1.1.4
'customerAddress': 'string',
'virtualGatewayId': 'string'
}
)
Parameters
• connectionId (string) – [REQUIRED]
ID of the connection.
Example: dxcon-fg5678gh
Default: None
• newPrivateVirtualInterface (dict) – [REQUIRED]
Detailed information for the private virtual interface to be created.
Default: None
– virtualInterfaceName (string) – [REQUIRED]
The name of the virtual interface assigned by the customer.
Example: “My VPC”
– vlan (integer) – [REQUIRED]
The VLAN ID.
Example: 101
– asn (integer) – [REQUIRED]
Autonomous system (AS) number for Border Gateway Protocol (BGP)
configuration.
Example: 65000
– authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
– amazonAddress (string) –
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
– customerAddress (string) –
IP address assigned to the customer interface.
Example: 192.168.1.2/30
– virtualGatewayId (string) – [REQUIRED]
The ID of the virtual private gateway to a VPC. This only applies to private
virtual interfaces.
Example: vgw-123er56
Return type dict
Returns
Response Syntax
{
'ownerAccount': 'string',
'virtualInterfaceId': 'string',
'location': 'string',
716 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'connectionId': 'string',
'virtualInterfaceType': 'string',
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
'customerAddress': 'string',
'virtualInterfaceState': 'confirming'|'verifying'|'pending'|'available'|'delet
'customerRouterConfig': 'string',
'virtualGatewayId': 'string',
'routeFilterPrefixes': [
{
'cidr': 'string'
},
]
}
Response Structure
• (dict) –
A virtual interface (VLAN) transmits the traffic between the AWS Direct Con-
nect location and the customer.
– ownerAccount (string) –
– virtualInterfaceId (string) –
ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
– location (string) –
Where the connection is located.
Example: EqSV5
Default: None
– connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
– virtualInterfaceType (string) –
The type of virtual interface.
Example: private (Amazon VPC) or public (Amazon S3, Amazon Dy-
namoDB, and so on.)
– virtualInterfaceName (string) –
The name of the virtual interface assigned by the customer.
Example: “My VPC”
– vlan (integer) –
The VLAN ID.
Example: 101
– asn (integer) –
3.1. Services 717
Boto3 Documentation, Release 1.1.4
Autonomous system (AS) number for Border Gateway Protocol (BGP)
configuration.
Example: 65000
– authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
– amazonAddress (string) –
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
– customerAddress (string) –
IP address assigned to the customer interface.
Example: 192.168.1.2/30
– virtualInterfaceState (string) – State of the virtual interface.
* Confirming : The creation of the virtual interface is pending confir-
mation from the virtual interface owner. If the owner of the virtual
interface is different from the owner of the connection on which it is
provisioned, then the virtual interface will remain in this state until
it is confirmed by the virtual interface owner.
* Verifying : This state only applies to public virtual interfaces. Each
public virtual interface needs validation before the virtual interface
can be created.
* Pending : A virtual interface is in this state from the time that it is
created until the virtual interface is ready to forward traffic.
* Available : A virtual interface that is able to forward traffic.
* Deleting : A virtual interface is in this state immediately after call-
ing DeleteVirtualInterface until it can no longer forward traffic.
* Deleted : A virtual interface that cannot forward traffic.
* Rejected : The virtual interface owner has declined creation of the
virtual interface. If a virtual interface in the ‘Confirming’ state is
deleted by the virtual interface owner, the virtual interface will enter
the ‘Rejected’ state.
– customerRouterConfig (string) –
Information for generating the customer router configuration.
– virtualGatewayId (string) –
The ID of the virtual private gateway to a VPC. This only applies to private
virtual interfaces.
Example: vgw-123er56
– routeFilterPrefixes (list) –
A list of routes to be advertised to the AWS network in this region (public
virtual interface) or your VPC (private virtual interface).
* (dict) –
A route filter prefix that the customer can advertise through Border
Gateway Protocol (BGP) over a public virtual interface.
· cidr (string) –
CIDR notation for the advertised route. Multiple routes are
separated by commas.
Example: 10.10.10.0/24,10.10.11.0/24
718 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
create_public_virtual_interface(**kwargs)
Creates a new public virtual interface. A virtual interface is the VLAN that transports AWS Direct Connect
traffic. A public virtual interface supports sending traffic to public services of AWS such as Amazon
Simple Storage Service (Amazon S3).
Request Syntax
response = client.create_public_virtual_interface(
connectionId='string',
newPublicVirtualInterface={
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
'customerAddress': 'string',
'routeFilterPrefixes': [
{
'cidr': 'string'
},
]
}
)
Parameters
• connectionId (string) – [REQUIRED]
ID of the connection.
Example: dxcon-fg5678gh
Default: None
• newPublicVirtualInterface (dict) – [REQUIRED]
Detailed information for the public virtual interface to be created.
Default: None
– virtualInterfaceName (string) – [REQUIRED]
The name of the virtual interface assigned by the customer.
Example: “My VPC”
– vlan (integer) – [REQUIRED]
The VLAN ID.
Example: 101
– asn (integer) – [REQUIRED]
Autonomous system (AS) number for Border Gateway Protocol (BGP)
configuration.
Example: 65000
– authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
– amazonAddress (string) – [REQUIRED]
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
3.1. Services 719
Boto3 Documentation, Release 1.1.4
– customerAddress (string) – [REQUIRED]
IP address assigned to the customer interface.
Example: 192.168.1.2/30
– routeFilterPrefixes (list) – [REQUIRED]
A list of routes to be advertised to the AWS network in this region (public
virtual interface) or your VPC (private virtual interface).
* (dict) –
A route filter prefix that the customer can advertise through Border
Gateway Protocol (BGP) over a public virtual interface.
· cidr (string) –
CIDR notation for the advertised route. Multiple routes are
separated by commas.
Example: 10.10.10.0/24,10.10.11.0/24
Return type dict
Returns
Response Syntax
{
'ownerAccount': 'string',
'virtualInterfaceId': 'string',
'location': 'string',
'connectionId': 'string',
'virtualInterfaceType': 'string',
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
'customerAddress': 'string',
'virtualInterfaceState': 'confirming'|'verifying'|'pending'|'available'|'delet
'customerRouterConfig': 'string',
'virtualGatewayId': 'string',
'routeFilterPrefixes': [
{
'cidr': 'string'
},
]
}
Response Structure
• (dict) –
A virtual interface (VLAN) transmits the traffic between the AWS Direct Con-
nect location and the customer.
– ownerAccount (string) –
– virtualInterfaceId (string) –
ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
– location (string) –
Where the connection is located.
720 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Example: EqSV5
Default: None
– connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
– virtualInterfaceType (string) –
The type of virtual interface.
Example: private (Amazon VPC) or public (Amazon S3, Amazon Dy-
namoDB, and so on.)
– virtualInterfaceName (string) –
The name of the virtual interface assigned by the customer.
Example: “My VPC”
– vlan (integer) –
The VLAN ID.
Example: 101
– asn (integer) –
Autonomous system (AS) number for Border Gateway Protocol (BGP)
configuration.
Example: 65000
– authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
– amazonAddress (string) –
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
– customerAddress (string) –
IP address assigned to the customer interface.
Example: 192.168.1.2/30
– virtualInterfaceState (string) – State of the virtual interface.
* Confirming : The creation of the virtual interface is pending confir-
mation from the virtual interface owner. If the owner of the virtual
interface is different from the owner of the connection on which it is
provisioned, then the virtual interface will remain in this state until
it is confirmed by the virtual interface owner.
* Verifying : This state only applies to public virtual interfaces. Each
public virtual interface needs validation before the virtual interface
can be created.
* Pending : A virtual interface is in this state from the time that it is
created until the virtual interface is ready to forward traffic.
* Available : A virtual interface that is able to forward traffic.
* Deleting : A virtual interface is in this state immediately after call-
ing DeleteVirtualInterface until it can no longer forward traffic.
* Deleted : A virtual interface that cannot forward traffic.
3.1. Services 721
Boto3 Documentation, Release 1.1.4
* Rejected : The virtual interface owner has declined creation of the
virtual interface. If a virtual interface in the ‘Confirming’ state is
deleted by the virtual interface owner, the virtual interface will enter
the ‘Rejected’ state.
– customerRouterConfig (string) –
Information for generating the customer router configuration.
– virtualGatewayId (string) –
The ID of the virtual private gateway to a VPC. This only applies to private
virtual interfaces.
Example: vgw-123er56
– routeFilterPrefixes (list) –
A list of routes to be advertised to the AWS network in this region (public
virtual interface) or your VPC (private virtual interface).
* (dict) –
A route filter prefix that the customer can advertise through Border
Gateway Protocol (BGP) over a public virtual interface.
· cidr (string) –
CIDR notation for the advertised route. Multiple routes are
separated by commas.
Example: 10.10.10.0/24,10.10.11.0/24
delete_connection(**kwargs)
Deletes the connection.
Deleting a connection only stops the AWS Direct Connect port hour and data transfer charges. You need
to cancel separately with the providers any services or charges for cross-connects or network circuits that
connect you to the AWS Direct Connect location.
Request Syntax
response = client.delete_connection(
connectionId='string'
)
Parameters connectionId (string) – [REQUIRED]
ID of the connection.
Example: dxcon-fg5678gh
Default: None
Return type dict
Returns
Response Syntax
{
'ownerAccount': 'string',
'connectionId': 'string',
'connectionName': 'string',
'connectionState': 'ordering'|'requested'|'pending'|'available'|'down'|'deleti
'region': 'string',
'location': 'string',
'bandwidth': 'string',
'vlan': 123,
722 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'partnerName': 'string'
}
Response Structure
• (dict) –
A connection represents the physical network connection between the AWS Di-
rect Connect location and the customer.
– ownerAccount (string) –
– connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
– connectionName (string) –
The name of the connection.
Example: “My Connection to AWS “
Default: None
– connectionState (string) – State of the connection.
* Ordering : The initial state of a hosted connection provisioned on
an interconnect. The connection stays in the ordering state until the
owner of the hosted connection confirms or declines the connection
order.
* Requested : The initial state of a standard connection. The con-
nection stays in the requested state until the Letter of Authorization
(LOA) is sent to the customer.
* Pending : The connection has been approved, and is being initial-
ized.
* Available : The network link is up, and the connection is ready for
use.
* Down : The network link is down.
* Deleted : The connection has been deleted.
* Rejected : A hosted connection in the ‘Ordering’ state will enter
the ‘Rejected’ state if it is deleted by the end customer.
– region (string) –
The AWS region where the connection is located.
Example: us-east-1
Default: None
– location (string) –
Where the connection is located.
Example: EqSV5
Default: None
– bandwidth (string) –
Bandwidth of the connection.
Example: 1Gbps (for regular connections), or 500Mbps (for hosted con-
nections)
Default: None
3.1. Services 723
Boto3 Documentation, Release 1.1.4
– vlan (integer) –
The VLAN ID.
Example: 101
– partnerName (string) –
delete_interconnect(**kwargs)
Deletes the specified interconnect.
Request Syntax
response = client.delete_interconnect(
interconnectId='string'
)
Parameters interconnectId (string) – [REQUIRED]
The ID of the interconnect.
Example: dxcon-abc123
Return type dict
Returns
Response Syntax
{
'interconnectState': 'requested'|'pending'|'available'|'down'|'deleting'|'dele
}
Response Structure
• (dict) –
The response received when DeleteInterconnect is called.
– interconnectState (string) – State of the interconnect.
* Requested : The initial state of an interconnect. The interconnect
stays in the requested state until the Letter of Authorization (LOA)
is sent to the customer.
* Pending : The interconnect has been approved, and is being initial-
ized.
* Available : The network link is up, and the interconnect is ready for
use.
* Down : The network link is down.
* Deleted : The interconnect has been deleted.
delete_virtual_interface(**kwargs)
Deletes a virtual interface.
Request Syntax
response = client.delete_virtual_interface(
virtualInterfaceId='string'
)
Parameters virtualInterfaceId (string) – [REQUIRED]
ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
724 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'virtualInterfaceState': 'confirming'|'verifying'|'pending'|'available'|'delet
}
Response Structure
• (dict) –
The response received when DeleteVirtualInterface is called.
– virtualInterfaceState (string) – State of the virtual interface.
* Confirming : The creation of the virtual interface is pending confir-
mation from the virtual interface owner. If the owner of the virtual
interface is different from the owner of the connection on which it is
provisioned, then the virtual interface will remain in this state until
it is confirmed by the virtual interface owner.
* Verifying : This state only applies to public virtual interfaces. Each
public virtual interface needs validation before the virtual interface
can be created.
* Pending : A virtual interface is in this state from the time that it is
created until the virtual interface is ready to forward traffic.
* Available : A virtual interface that is able to forward traffic.
* Deleting : A virtual interface is in this state immediately after call-
ing DeleteVirtualInterface until it can no longer forward traffic.
* Deleted : A virtual interface that cannot forward traffic.
* Rejected : The virtual interface owner has declined creation of the
virtual interface. If a virtual interface in the ‘Confirming’ state is
deleted by the virtual interface owner, the virtual interface will enter
the ‘Rejected’ state.
describe_connections(**kwargs)
Displays all connections in this region.
If a connection ID is provided, the call returns only that particular connection.
Request Syntax
response = client.describe_connections(
connectionId='string'
)
Parameters connectionId (string) – ID of the connection.
Example: dxcon-fg5678gh
Default: None
Return type dict
Returns
Response Syntax
{
'connections': [
{
'ownerAccount': 'string',
'connectionId': 'string',
3.1. Services 725
Boto3 Documentation, Release 1.1.4
'connectionName': 'string',
'connectionState': 'ordering'|'requested'|'pending'|'available'|'down'
'region': 'string',
'location': 'string',
'bandwidth': 'string',
'vlan': 123,
'partnerName': 'string'
},
]
}
Response Structure
• (dict) –
A structure containing a list of connections.
– connections (list) –
A list of connections.
* (dict) –
A connection represents the physical network connection between
the AWS Direct Connect location and the customer.
· ownerAccount (string) –
· connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
· connectionName (string) –
The name of the connection.
Example: “My Connection to AWS “
Default: None
· connectionState (string) – State of the connection.
· Ordering : The initial state of a hosted connection provi-
sioned on an interconnect. The connection stays in the order-
ing state until the owner of the hosted connection confirms or
declines the connection order.
· Requested : The initial state of a standard connection. The
connection stays in the requested state until the Letter of Au-
thorization (LOA) is sent to the customer.
· Pending : The connection has been approved, and is being
initialized.
· Available : The network link is up, and the connection is
ready for use.
· Down : The network link is down.
· Deleted : The connection has been deleted.
· Rejected : A hosted connection in the ‘Ordering’ state will
enter the ‘Rejected’ state if it is deleted by the end customer.
· region (string) –
The AWS region where the connection is located.
Example: us-east-1
Default: None
726 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· location (string) –
Where the connection is located.
Example: EqSV5
Default: None
· bandwidth (string) –
Bandwidth of the connection.
Example: 1Gbps (for regular connections), or 500Mbps (for
hosted connections)
Default: None
· vlan (integer) –
The VLAN ID.
Example: 101
· partnerName (string) –
describe_connections_on_interconnect(**kwargs)
Return a list of connections that have been provisioned on the given interconnect.
Request Syntax
response = client.describe_connections_on_interconnect(
interconnectId='string'
)
Parameters interconnectId (string) – [REQUIRED]
ID of the interconnect on which a list of connection is provisioned.
Example: dxcon-abc123
Default: None
Return type dict
Returns
Response Syntax
{
'connections': [
{
'ownerAccount': 'string',
'connectionId': 'string',
'connectionName': 'string',
'connectionState': 'ordering'|'requested'|'pending'|'available'|'down'
'region': 'string',
'location': 'string',
'bandwidth': 'string',
'vlan': 123,
'partnerName': 'string'
},
]
}
Response Structure
• (dict) –
A structure containing a list of connections.
3.1. Services 727
Boto3 Documentation, Release 1.1.4
– connections (list) –
A list of connections.
* (dict) –
A connection represents the physical network connection between
the AWS Direct Connect location and the customer.
· ownerAccount (string) –
· connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
· connectionName (string) –
The name of the connection.
Example: “My Connection to AWS “
Default: None
· connectionState (string) – State of the connection.
· Ordering : The initial state of a hosted connection provi-
sioned on an interconnect. The connection stays in the order-
ing state until the owner of the hosted connection confirms or
declines the connection order.
· Requested : The initial state of a standard connection. The
connection stays in the requested state until the Letter of Au-
thorization (LOA) is sent to the customer.
· Pending : The connection has been approved, and is being
initialized.
· Available : The network link is up, and the connection is
ready for use.
· Down : The network link is down.
· Deleted : The connection has been deleted.
· Rejected : A hosted connection in the ‘Ordering’ state will
enter the ‘Rejected’ state if it is deleted by the end customer.
· region (string) –
The AWS region where the connection is located.
Example: us-east-1
Default: None
· location (string) –
Where the connection is located.
Example: EqSV5
Default: None
· bandwidth (string) –
Bandwidth of the connection.
Example: 1Gbps (for regular connections), or 500Mbps (for
hosted connections)
Default: None
· vlan (integer) –
The VLAN ID.
728 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Example: 101
· partnerName (string) –
describe_interconnects(**kwargs)
Returns a list of interconnects owned by the AWS account.
If an interconnect ID is provided, it will only return this particular interconnect.
Request Syntax
response = client.describe_interconnects(
interconnectId='string'
)
Parameters interconnectId (string) – The ID of the interconnect.
Example: dxcon-abc123
Return type dict
Returns
Response Syntax
{
'interconnects': [
{
'interconnectId': 'string',
'interconnectName': 'string',
'interconnectState': 'requested'|'pending'|'available'|'down'|'deletin
'region': 'string',
'location': 'string',
'bandwidth': 'string'
},
]
}
Response Structure
• (dict) –
A structure containing a list of interconnects.
– interconnects (list) –
A list of interconnects.
* (dict) –
An interconnect is a connection that can host other connections.
Like a standard AWS Direct Connect connection, an interconnect
represents the physical connection between an AWS Direct Con-
nect partner’s network and a specific Direct Connect location. An
AWS Direct Connect partner who owns an interconnect can provi-
sion hosted connections on the interconnect for their end customers,
thereby providing the end customers with connectivity to AWS ser-
vices.
The resources of the interconnect, including bandwidth and VLAN
numbers, are shared by all of the hosted connections on the inter-
connect, and the owner of the interconnect determines how these
resources are assigned.
· interconnectId (string) –
The ID of the interconnect.
3.1. Services 729
Boto3 Documentation, Release 1.1.4
Example: dxcon-abc123
· interconnectName (string) –
The name of the interconnect.
Example: “1G Interconnect to AWS “
· interconnectState (string) – State of the interconnect.
· Requested : The initial state of an interconnect. The inter-
connect stays in the requested state until the Letter of Autho-
rization (LOA) is sent to the customer.
· Pending : The interconnect has been approved, and is being
initialized.
· Available : The network link is up, and the interconnect is
ready for use.
· Down : The network link is down.
· Deleted : The interconnect has been deleted.
· region (string) –
The AWS region where the connection is located.
Example: us-east-1
Default: None
· location (string) –
Where the connection is located.
Example: EqSV5
Default: None
· bandwidth (string) –
Bandwidth of the connection.
Example: 1Gbps
Default: None
describe_locations()
Returns the list of AWS Direct Connect locations in the current AWS region. These are the locations that
may be selected when calling CreateConnection or CreateInterconnect.
Request Syntax
response = client.describe_locations()
Return type dict
Returns
Response Syntax
{
'locations': [
{
'locationCode': 'string',
'locationName': 'string'
},
]
}
Response Structure
• (dict) –
730 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– locations (list) –
* (dict) –
An AWS Direct Connect location where connections and intercon-
nects can be requested.
· locationCode (string) –
The code used to indicate the AWS Direct Connect location.
· locationName (string) –
The name of the AWS Direct Connect location. The name
includes the colocation partner name and the physical site of
the lit building.
describe_virtual_gateways()
Returns a list of virtual private gateways owned by the AWS account.
You can create one or more AWS Direct Connect private virtual interfaces linking to a virtual private
gateway. A virtual private gateway can be managed via Amazon Virtual Private Cloud (VPC) console or
the EC2 CreateVpnGateway action.
Request Syntax
response = client.describe_virtual_gateways()
Return type dict
Returns
Response Syntax
{
'virtualGateways': [
{
'virtualGatewayId': 'string',
'virtualGatewayState': 'string'
},
]
}
Response Structure
• (dict) –
A structure containing a list of virtual private gateways.
– virtualGateways (list) –
A list of virtual private gateways.
* (dict) –
You can create one or more AWS Direct Connect private virtual
interfaces linking to your virtual private gateway.
Virtual private gateways can be managed using the Amazon Virtual
Private Cloud (Amazon VPC) console or the Amazon EC2 Creat-
eVpnGateway action .
· virtualGatewayId (string) –
The ID of the virtual private gateway to a VPC. This only
applies to private virtual interfaces.
Example: vgw-123er56
3.1. Services 731
Boto3 Documentation, Release 1.1.4
· virtualGatewayState (string) – State of the virtual private
gateway.
· Pending : This is the initial state after calling CreateVpn-
Gateway .
· Available : Ready for use by a private virtual interface.
· Deleting : This is the initial state after calling DeleteVpn-
Gateway .
· Deleted : In this state, a private virtual interface is unable to
send traffic over this gateway.
describe_virtual_interfaces(**kwargs)
Displays all virtual interfaces for an AWS account. Virtual interfaces deleted fewer than 15 minutes
before DescribeVirtualInterfaces is called are also returned. If a connection ID is included then only
virtual interfaces associated with this connection will be returned. If a virtual interface ID is included
then only a single virtual interface will be returned.
A virtual interface (VLAN) transmits the traffic between the AWS Direct Connect location and the cus-
tomer.
If a connection ID is provided, only virtual interfaces provisioned on the specified connection will be
returned. If a virtual interface ID is provided, only this particular virtual interface will be returned.
Request Syntax
response = client.describe_virtual_interfaces(
connectionId='string',
virtualInterfaceId='string'
)
Parameters
• connectionId (string) – ID of the connection.
Example: dxcon-fg5678gh
Default: None
• virtualInterfaceId (string) – ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
Return type dict
Returns
Response Syntax
{
'virtualInterfaces': [
{
'ownerAccount': 'string',
'virtualInterfaceId': 'string',
'location': 'string',
'connectionId': 'string',
'virtualInterfaceType': 'string',
'virtualInterfaceName': 'string',
'vlan': 123,
'asn': 123,
'authKey': 'string',
'amazonAddress': 'string',
'customerAddress': 'string',
'virtualInterfaceState': 'confirming'|'verifying'|'pending'|'available
732 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'customerRouterConfig': 'string',
'virtualGatewayId': 'string',
'routeFilterPrefixes': [
{
'cidr': 'string'
},
]
},
]
}
Response Structure
• (dict) –
A structure containing a list of virtual interfaces.
– virtualInterfaces (list) –
A list of virtual interfaces.
* (dict) –
A virtual interface (VLAN) transmits the traffic between the AWS
Direct Connect location and the customer.
· ownerAccount (string) –
· virtualInterfaceId (string) –
ID of the virtual interface.
Example: dxvif-123dfg56
Default: None
· location (string) –
Where the connection is located.
Example: EqSV5
Default: None
· connectionId (string) –
ID of the connection.
Example: dxcon-fg5678gh
Default: None
· virtualInterfaceType (string) –
The type of virtual interface.
Example: private (Amazon VPC) or public (Amazon S3,
Amazon DynamoDB, and so on.)
· virtualInterfaceName (string) –
The name of the virtual interface assigned by the customer.
Example: “My VPC”
· vlan (integer) –
The VLAN ID.
Example: 101
· asn (integer) –
Autonomous system (AS) number for Border Gateway Proto-
col (BGP) configuration.
3.1. Services 733
Boto3 Documentation, Release 1.1.4
Example: 65000
· authKey (string) –
Authentication key for BGP configuration.
Example: asdf34example
· amazonAddress (string) –
IP address assigned to the Amazon interface.
Example: 192.168.1.1/30
· customerAddress (string) –
IP address assigned to the customer interface.
Example: 192.168.1.2/30
· virtualInterfaceState (string) – State of the virtual interface.
· Confirming : The creation of the virtual interface is pending
confirmation from the virtual interface owner. If the owner of
the virtual interface is different from the owner of the connec-
tion on which it is provisioned, then the virtual interface will
remain in this state until it is confirmed by the virtual interface
owner.
· Verifying : This state only applies to public virtual interfaces.
Each public virtual interface needs validation before the vir-
tual interface can be created.
· Pending : A virtual interface is in this state from the time
that it is created until the virtual interface is ready to forward
traffic.
· Available : A virtual interface that is able to forward traffic.
· Deleting : A virtual interface is in this state immediately after
calling DeleteVirtualInterface until it can no longer forward
traffic.
· Deleted : A virtual interface that cannot forward traffic.
· Rejected : The virtual interface owner has declined creation
of the virtual interface. If a virtual interface in the ‘Confirm-
ing’ state is deleted by the virtual interface owner, the virtual
interface will enter the ‘Rejected’ state.
· customerRouterConfig (string) –
Information for generating the customer router configuration.
· virtualGatewayId (string) –
The ID of the virtual private gateway to a VPC. This only
applies to private virtual interfaces.
Example: vgw-123er56
· routeFilterPrefixes (list) –
A list of routes to be advertised to the AWS network in this
region (public virtual interface) or your VPC (private virtual
interface).
· (dict) –
A route filter prefix that the customer can advertise through
Border Gateway Protocol (BGP) over a public virtual inter-
face.
· cidr (string) –
734 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
CIDR notation for the advertised route. Multiple routes are
separated by commas.
Example: 10.10.10.0/24,10.10.11.0/24
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
DirectoryService
Table of Contents
• DirectoryService
– Client
Client
class DirectoryService.Client
A low-level client representing AWS Directory Service:
import boto3
client = boto3.client('ds')
These are the available methods:
•can_paginate()
•connect_directory()
•create_alias()
•create_computer()
•create_directory()
•create_snapshot()
3.1. Services 735
Boto3 Documentation, Release 1.1.4
•delete_directory()
•delete_snapshot()
•describe_directories()
•describe_snapshots()
•disable_radius()
•disable_sso()
•enable_radius()
•enable_sso()
•generate_presigned_url()
•get_directory_limits()
•get_paginator()
•get_snapshot_limits()
•get_waiter()
•restore_from_snapshot()
•update_radius()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
connect_directory(**kwargs)
Creates an AD Connector to connect an on-premises directory.
Request Syntax
response = client.connect_directory(
Name='string',
ShortName='string',
Password='string',
Description='string',
Size='Small'|'Large',
ConnectSettings={
'VpcId': 'string',
'SubnetIds': [
'string',
],
'CustomerDnsIps': [
'string',
],
'CustomerUserName': 'string'
}
)
Parameters
• Name (string) – [REQUIRED]
The fully-qualified name of the on-premises directory, such as
corp.example.com .
• ShortName (string) – The NetBIOS name of the on-premises directory, such as
CORP .
• Password (string) – [REQUIRED]
The password for the on-premises user account.
736 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• Description (string) – A textual description for the directory.
• Size (string) – [REQUIRED]
The size of the directory.
• ConnectSettings (dict) – [REQUIRED]
A DirectoryConnectSettings object that contains additional information for the
operation.
– VpcId (string) – [REQUIRED]
The identifier of the VPC that the AD Connector is created in.
– SubnetIds (list) – [REQUIRED]
A list of subnet identifiers in the VPC that the AD Connector is created in.
* (string) –
– CustomerDnsIps (list) – [REQUIRED]
A list of one or more IP addresses of DNS servers or domain controllers
in the on-premises directory.
* (string) –
– CustomerUserName (string) – [REQUIRED]
The username of an account in the on-premises directory that is used to
connect to the directory. This account must have the following privileges:
* Read users and groups
* Create computer objects
* Join computers to the domain
Return type dict
Returns
Response Syntax
{
'DirectoryId': 'string'
}
Response Structure
• (dict) –
Contains the results of the ConnectDirectory operation.
– DirectoryId (string) –
The identifier of the new directory.
create_alias(**kwargs)
Creates an alias for a directory and assigns the alias to the directory. The alias is used to construct the
access URL for the directory, such as http://alias.awsapps.com .
Warning: After an alias has been created, it cannot be deleted or reused, so this operation should
only be used when absolutely necessary.
Request Syntax
response = client.create_alias(
DirectoryId='string',
Alias='string'
)
Parameters
3.1. Services 737
Boto3 Documentation, Release 1.1.4
• DirectoryId (string) – [REQUIRED]
The identifier of the directory to create the alias for.
• Alias (string) – [REQUIRED]
The requested alias.
The alias must be unique amongst all aliases in AWS. This operation will throw
an EntityAlreadyExistsException if this alias already exists.
Return type dict
Returns
Response Syntax
{
'DirectoryId': 'string',
'Alias': 'string'
}
Response Structure
• (dict) –
Contains the results of the CreateAlias operation.
– DirectoryId (string) –
The identifier of the directory.
– Alias (string) –
The alias for the directory.
create_computer(**kwargs)
Creates a computer account in the specified directory, and joins the computer to the directory.
Request Syntax
response = client.create_computer(
DirectoryId='string',
ComputerName='string',
Password='string',
OrganizationalUnitDistinguishedName='string',
ComputerAttributes=[
{
'Name': 'string',
'Value': 'string'
},
]
)
Parameters
• DirectoryId (string) – [REQUIRED]
The identifier of the directory to create the computer account in.
• ComputerName (string) – [REQUIRED]
The name of the computer account.
• Password (string) – [REQUIRED]
A one-time password that is used to join the computer to the directory. You
should generate a random, strong password to use for this parameter.
• OrganizationalUnitDistinguishedName (string) – The fully-qualified distin-
guished name of the organizational unit to place the computer account in.
738 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• ComputerAttributes (list) – An array of Attribute objects that contain any
LDAP attributes to apply to the computer account.
– (dict) –
Represents a named directory attribute.
* Name (string) –
The name of the attribute.
* Value (string) –
The value of the attribute.
Return type dict
Returns
Response Syntax
{
'Computer': {
'ComputerId': 'string',
'ComputerName': 'string',
'ComputerAttributes': [
{
'Name': 'string',
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
Contains the results for the CreateComputer operation.
– Computer (dict) –
A Computer object the represents the computer account.
* ComputerId (string) –
The identifier of the computer.
* ComputerName (string) –
The computer name.
* ComputerAttributes (list) –
An array of Attribute objects that contain the LDAP attributes that
belong to the computer account.
· (dict) –
Represents a named directory attribute.
· Name (string) –
The name of the attribute.
· Value (string) –
The value of the attribute.
create_directory(**kwargs)
Creates a Simple AD directory.
Request Syntax
3.1. Services 739
Boto3 Documentation, Release 1.1.4
response = client.create_directory(
Name='string',
ShortName='string',
Password='string',
Description='string',
Size='Small'|'Large',
VpcSettings={
'VpcId': 'string',
'SubnetIds': [
'string',
]
}
)
Parameters
• Name (string) – [REQUIRED]
The fully qualified name for the directory, such as corp.example.com .
• ShortName (string) – The short name of the directory, such as CORP .
• Password (string) – [REQUIRED]
The password for the directory administrator. The directory creation process
creates a directory administrator account with the username Administrator
and this password.
• Description (string) – A textual description for the directory.
• Size (string) – [REQUIRED]
The size of the directory.
• VpcSettings (dict) – A DirectoryVpcSettings object that contains additional in-
formation for the operation.
– VpcId (string) – [REQUIRED]
The identifier of the VPC to create the Simple AD directory in.
– SubnetIds (list) – [REQUIRED]
The identifiers of the subnets for the directory servers. The two subnets
must be in different Availability Zones. AWS Directory Service creates a
directory server and a DNS server in each of these subnets.
* (string) –
Return type dict
Returns
Response Syntax
{
'DirectoryId': 'string'
}
Response Structure
• (dict) –
Contains the results of the CreateDirectory operation.
– DirectoryId (string) –
The identifier of the directory that was created.
create_snapshot(**kwargs)
Creates a snapshot of an existing directory.
You cannot take snapshots of extended or connected directories.
740 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.create_snapshot(
DirectoryId='string',
Name='string'
)
Parameters
• DirectoryId (string) – [REQUIRED]
The identifier of the directory to take a snapshot of.
• Name (string) – The descriptive name to apply to the snapshot.
Return type dict
Returns
Response Syntax
{
'SnapshotId': 'string'
}
Response Structure
• (dict) –
Contains the results of the CreateSnapshot operation.
– SnapshotId (string) –
The identifier of the snapshot that was created.
delete_directory(**kwargs)
Deletes an AWS Directory Service directory.
Request Syntax
response = client.delete_directory(
DirectoryId='string'
)
Parameters DirectoryId (string) – [REQUIRED]
The identifier of the directory to delete.
Return type dict
Returns
Response Syntax
{
'DirectoryId': 'string'
}
Response Structure
• (dict) –
Contains the results of the DeleteDirectory operation.
– DirectoryId (string) –
The directory identifier.
3.1. Services 741
Boto3 Documentation, Release 1.1.4
delete_snapshot(**kwargs)
Deletes a directory snapshot.
Request Syntax
response = client.delete_snapshot(
SnapshotId='string'
)
Parameters SnapshotId (string) – [REQUIRED]
The identifier of the directory snapshot to be deleted.
Return type dict
Returns
Response Syntax
{
'SnapshotId': 'string'
}
Response Structure
• (dict) –
Contains the results of the DeleteSnapshot operation.
– SnapshotId (string) –
The identifier of the directory snapshot that was deleted.
describe_directories(**kwargs)
Obtains information about the directories that belong to this account.
You can retrieve information about specific directories by passing the directory identifiers in the Directo-
ryIds parameter. Otherwise, all directories that belong to the current account are returned.
This operation supports pagination with the use of the NextToken request and response parameters. If
more results are available, the DescribeDirectoriesResult.NextToken member contains a token that you
pass in the next call to DescribeDirectories to retrieve the next set of items.
You can also specify a maximum number of return results with the Limit parameter.
Request Syntax
response = client.describe_directories(
DirectoryIds=[
'string',
],
NextToken='string',
Limit=123
)
Parameters
• DirectoryIds (list) – A list of identifiers of the directories to obtain the informa-
tion for. If this member is null, all directories that belong to the current account
are returned.
An empty list results in an InvalidParameterException being thrown.
– (string) –
• NextToken (string) – The DescribeDirectoriesResult.NextToken value from a
previous call to DescribeDirectories . Pass null if this is the first call.
742 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• Limit (integer) – The maximum number of items to return. If this value is zero,
the maximum number of items is specified by the limitations of the operation.
Return type dict
Returns
Response Syntax
{
'DirectoryDescriptions': [
{
'DirectoryId': 'string',
'Name': 'string',
'ShortName': 'string',
'Size': 'Small'|'Large',
'Alias': 'string',
'AccessUrl': 'string',
'Description': 'string',
'DnsIpAddrs': [
'string',
],
'Stage': 'Requested'|'Creating'|'Created'|'Active'|'Inoperable'|'Impai
'LaunchTime': datetime(2015, 1, 1),
'StageLastUpdatedDateTime': datetime(2015, 1, 1),
'Type': 'SimpleAD'|'ADConnector',
'VpcSettings': {
'VpcId': 'string',
'SubnetIds': [
'string',
],
'SecurityGroupId': 'string',
'AvailabilityZones': [
'string',
]
},
'ConnectSettings': {
'VpcId': 'string',
'SubnetIds': [
'string',
],
'CustomerUserName': 'string',
'SecurityGroupId': 'string',
'AvailabilityZones': [
'string',
],
'ConnectIps': [
'string',
]
},
'RadiusSettings': {
'RadiusServers': [
'string',
],
'RadiusPort': 123,
'RadiusTimeout': 123,
'RadiusRetries': 123,
'SharedSecret': 'string',
'AuthenticationProtocol': 'PAP'|'CHAP'|'MS-CHAPv1'|'MS-CHAPv2',
'DisplayLabel': 'string',
3.1. Services 743
Boto3 Documentation, Release 1.1.4
'UseSameUsername': True|False
},
'RadiusStatus': 'Creating'|'Completed'|'Failed',
'StageReason': 'string',
'SsoEnabled': True|False
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the results of the DescribeDirectories operation.
– DirectoryDescriptions (list) –
The list of DirectoryDescription objects that were retrieved.
It is possible that this list contains less than the number of items specified
in the Limit member of the request. This occurs if there are less than
the requested number of items left to retrieve, or if the limitations of the
operation have been exceeded.
* (dict) –
Contains information about an AWS Directory Service directory.
· DirectoryId (string) –
The directory identifier.
· Name (string) –
The fully-qualified name of the directory.
· ShortName (string) –
The short name of the directory.
· Size (string) –
The directory size.
· Alias (string) –
The alias for the directory.
· AccessUrl (string) –
The access URL for the directory, such as
http://alias.awsapps.com .
· Description (string) –
The textual description for the directory.
· DnsIpAddrs (list) –
The IP addresses of the DNS servers for the directory. For a
Simple AD directory, these are the IP addresses of the Simple
AD directory servers. For an AD Connector directory, these
are the IP addresses of the DNS servers or domain controllers
in the on-premises directory that the AD Connector is con-
nected to.
· (string) –
· Stage (string) –
The current stage of the directory.
· LaunchTime (datetime) –
744 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Specifies when the directory was created.
· StageLastUpdatedDateTime (datetime) –
The date and time that the stage was last updated.
· Type (string) –
The directory size.
· VpcSettings (dict) –
A DirectoryVpcSettingsDescription object that contains addi-
tional information about a Simple AD directory. This member
is only present if the directory is a Simple AD directory.
· VpcId (string) –
The identifier of the VPC that the directory is in.
· SubnetIds (list) –
The identifiers of the subnets for the directory servers.
· (string) –
· SecurityGroupId (string) –
The security group identifier for the directory.
· AvailabilityZones (list) –
The list of Availability Zones that the directory is in.
· (string) –
· ConnectSettings (dict) –
A DirectoryConnectSettingsDescription object that contains
additional information about an AD Connector directory.
This member is only present if the directory is an AD Con-
nector directory.
· VpcId (string) –
The identifier of the VPC that the AD Connector is in.
· SubnetIds (list) –
A list of subnet identifiers in the VPC that the AD connector
is in.
· (string) –
· CustomerUserName (string) –
The username of the service account in the on-premises di-
rectory.
· SecurityGroupId (string) –
The security group identifier for the AD Connector directory.
· AvailabilityZones (list) –
A list of the Availability Zones that the directory is in.
· (string) –
· ConnectIps (list) –
The IP addresses of the AD Connector servers.
· (string) –
· RadiusSettings (dict) –
A RadiusSettings object that contains information about the
RADIUS server configured for this directory.
· RadiusServers (list) –
3.1. Services 745
Boto3 Documentation, Release 1.1.4
An array of strings that contains the IP addresses of the RA-
DIUS server endpoints, or the IP addresses of your RADIUS
server load balancer.
· (string) –
· RadiusPort (integer) –
The port that your RADIUS server is using for communica-
tions. Your on-premises network must allow inbound traffic
over this port from the AWS Directory Service servers.
· RadiusTimeout (integer) –
The amount of time, in seconds, to wait for the RADIUS
server to respond.
· RadiusRetries (integer) –
The maximum number of times that communication with the
RADIUS server is attempted.
· SharedSecret (string) –
The shared secret code that was specified when your RADIUS
endpoints were created.
· AuthenticationProtocol (string) –
The protocol specified for your RADIUS endpoints.
· DisplayLabel (string) –
Not currently used.
· UseSameUsername (boolean) –
Not currently used.
· RadiusStatus (string) –
The status of the RADIUS MFA server connection.
· StageReason (string) –
Additional information about the directory stage.
· SsoEnabled (boolean) –
Indicates if single-sign on is enabled for the directory. For
more information, see EnableSso and DisableSso .
– NextToken (string) –
If not null, more results are available. Pass this value for the NextToken
parameter in a subsequent call to DescribeDirectories to retrieve the next
set of items.
describe_snapshots(**kwargs)
Obtains information about the directory snapshots that belong to this account.
This operation supports pagination with the use of the NextToken request and response parameters. If
more results are available, the DescribeSnapshots.NextToken member contains a token that you pass in
the next call to DescribeSnapshots to retrieve the next set of items.
You can also specify a maximum number of return results with the Limit parameter.
Request Syntax
response = client.describe_snapshots(
DirectoryId='string',
SnapshotIds=[
'string',
746 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
NextToken='string',
Limit=123
)
Parameters
• DirectoryId (string) – The identifier of the directory to retrieve snapshot infor-
mation for.
• SnapshotIds (list) – A list of identifiers of the snapshots to obtain the informa-
tion for. If this member is null or empty, all snapshots are returned using the
Limit and NextToken members.
– (string) –
• NextToken (string) – The DescribeSnapshotsResult.NextToken value from a pre-
vious call to DescribeSnapshots . Pass null if this is the first call.
• Limit (integer) – The maximum number of objects to return.
Return type dict
Returns
Response Syntax
{
'Snapshots': [
{
'DirectoryId': 'string',
'SnapshotId': 'string',
'Type': 'Auto'|'Manual',
'Name': 'string',
'Status': 'Creating'|'Completed'|'Failed',
'StartTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the results of the DescribeSnapshots operation.
– Snapshots (list) –
The list of Snapshot objects that were retrieved.
It is possible that this list contains less than the number of items specified
in the Limit member of the request. This occurs if there are less than
the requested number of items left to retrieve, or if the limitations of the
operation have been exceeded.
* (dict) –
Describes a directory snapshot.
· DirectoryId (string) –
The directory identifier.
· SnapshotId (string) –
The snapshot identifier.
· Type (string) –
The snapshot type.
3.1. Services 747
Boto3 Documentation, Release 1.1.4
· Name (string) –
The descriptive name of the snapshot.
· Status (string) –
The snapshot status.
· StartTime (datetime) –
The date and time that the snapshot was taken.
– NextToken (string) –
If not null, more results are available. Pass this value in the NextToken
member of a subsequent call to DescribeSnapshots .
disable_radius(**kwargs)
Disables multi-factor authentication (MFA) with Remote Authentication Dial In User Service (RADIUS)
for an AD Connector directory.
Request Syntax
response = client.disable_radius(
DirectoryId='string'
)
Parameters DirectoryId (string) – [REQUIRED]
The identifier of the directory to disable MFA for.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the results of the DisableRadius operation.
disable_sso(**kwargs)
Disables single-sign on for a directory.
Request Syntax
response = client.disable_sso(
DirectoryId='string',
UserName='string',
Password='string'
)
Parameters
• DirectoryId (string) – [REQUIRED]
The identifier of the directory to disable single-sign on for.
• UserName (string) – The username of an alternate account to use to disable
single-sign on. This is only used for AD Connector directories. This account
must have privileges to remove a service principle name.
If the AD Connector service account does not have privileges to remove a service
principle name, you can specify an alternate account with the UserName and
Password parameters. These credentials are only used to disable single sign-on
748 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
and are not stored by the service. The AD Connector service account is not
changed.
• Password (string) – The password of an alternate account to use to disable
single-sign on. This is only used for AD Connector directories. See the User-
Name parameter for more information.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the results of the DisableSso operation.
enable_radius(**kwargs)
Enables multi-factor authentication (MFA) with Remote Authentication Dial In User Service (RADIUS)
for an AD Connector directory.
Request Syntax
response = client.enable_radius(
DirectoryId='string',
RadiusSettings={
'RadiusServers': [
'string',
],
'RadiusPort': 123,
'RadiusTimeout': 123,
'RadiusRetries': 123,
'SharedSecret': 'string',
'AuthenticationProtocol': 'PAP'|'CHAP'|'MS-CHAPv1'|'MS-CHAPv2',
'DisplayLabel': 'string',
'UseSameUsername': True|False
}
)
Parameters
• DirectoryId (string) – [REQUIRED]
The identifier of the directory to enable MFA for.
• RadiusSettings (dict) – [REQUIRED]
A RadiusSettings object that contains information about the RADIUS server.
– RadiusServers (list) –
An array of strings that contains the IP addresses of the RADIUS server
endpoints, or the IP addresses of your RADIUS server load balancer.
* (string) –
– RadiusPort (integer) –
The port that your RADIUS server is using for communications. Your on-
premises network must allow inbound traffic over this port from the AWS
Directory Service servers.
– RadiusTimeout (integer) –
The amount of time, in seconds, to wait for the RADIUS server to respond.
3.1. Services 749
Boto3 Documentation, Release 1.1.4
– RadiusRetries (integer) –
The maximum number of times that communication with the RADIUS
server is attempted.
– SharedSecret (string) –
The shared secret code that was specified when your RADIUS endpoints
were created.
– AuthenticationProtocol (string) –
The protocol specified for your RADIUS endpoints.
– DisplayLabel (string) –
Not currently used.
– UseSameUsername (boolean) –
Not currently used.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the results of the EnableRadius operation.
enable_sso(**kwargs)
Enables single-sign on for a directory.
Request Syntax
response = client.enable_sso(
DirectoryId='string',
UserName='string',
Password='string'
)
Parameters
• DirectoryId (string) – [REQUIRED]
The identifier of the directory to enable single-sign on for.
• UserName (string) – The username of an alternate account to use to enable
single-sign on. This is only used for AD Connector directories. This account
must have privileges to add a service principle name.
If the AD Connector service account does not have privileges to add a service
principle name, you can specify an alternate account with the UserName and
Password parameters. These credentials are only used to enable single sign-on
and are not stored by the service. The AD Connector service account is not
changed.
• Password (string) – The password of an alternate account to use to enable single-
sign on. This is only used for AD Connector directories. See the UserName
parameter for more information.
Return type dict
Returns
Response Syntax
750 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{}
Response Structure
• (dict) –
Contains the results of the EnableSso operation.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_directory_limits()
Obtains directory limit information for the current region.
Request Syntax
response = client.get_directory_limits()
Return type dict
Returns
Response Syntax
{
'DirectoryLimits': {
'CloudOnlyDirectoriesLimit': 123,
'CloudOnlyDirectoriesCurrentCount': 123,
'CloudOnlyDirectoriesLimitReached': True|False,
'ConnectedDirectoriesLimit': 123,
'ConnectedDirectoriesCurrentCount': 123,
'ConnectedDirectoriesLimitReached': True|False
}
}
Response Structure
• (dict) –
Contains the results of the GetDirectoryLimits operation.
– DirectoryLimits (dict) –
A DirectoryLimits object that contains the directory limits for the current
region.
* CloudOnlyDirectoriesLimit (integer) –
The maximum number of cloud directories allowed in the region.
* CloudOnlyDirectoriesCurrentCount (integer) –
The current number of cloud directories in the region.
* CloudOnlyDirectoriesLimitReached (boolean) –
Indicates if the cloud directory limit has been reached.
3.1. Services 751
Boto3 Documentation, Release 1.1.4
* ConnectedDirectoriesLimit (integer) –
The maximum number of connected directories allowed in the re-
gion.
* ConnectedDirectoriesCurrentCount (integer) –
The current number of connected directories in the region.
* ConnectedDirectoriesLimitReached (boolean) –
Indicates if the connected directory limit has been reached.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_snapshot_limits(**kwargs)
Obtains the manual snapshot limits for a directory.
Request Syntax
response = client.get_snapshot_limits(
DirectoryId='string'
)
Parameters DirectoryId (string) – [REQUIRED]
Contains the identifier of the directory to obtain the limits for.
Return type dict
Returns
Response Syntax
{
'SnapshotLimits': {
'ManualSnapshotsLimit': 123,
'ManualSnapshotsCurrentCount': 123,
'ManualSnapshotsLimitReached': True|False
}
}
Response Structure
• (dict) –
Contains the results of the GetSnapshotLimits operation.
– SnapshotLimits (dict) –
A SnapshotLimits object that contains the manual snapshot limits for the
specified directory.
* ManualSnapshotsLimit (integer) –
The maximum number of manual snapshots allowed.
752 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* ManualSnapshotsCurrentCount (integer) –
The current number of manual snapshots of the directory.
* ManualSnapshotsLimitReached (boolean) –
Indicates if the manual snapshot limit has been reached.
get_waiter(waiter_name)
restore_from_snapshot(**kwargs)
Restores a directory using an existing directory snapshot.
When you restore a directory from a snapshot, any changes made to the directory after the snapshot date
are overwritten.
This action returns as soon as the restore operation is initiated. You can monitor the progress of the
restore operation by calling the DescribeDirectories operation with the directory identifier. When the
DirectoryDescription.Stage value changes to Active , the restore operation is complete.
Request Syntax
response = client.restore_from_snapshot(
SnapshotId='string'
)
Parameters SnapshotId (string) – [REQUIRED]
The identifier of the snapshot to restore from.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the results of the RestoreFromSnapshot operation.
update_radius(**kwargs)
Updates the Remote Authentication Dial In User Service (RADIUS) server information for an AD Con-
nector directory.
Request Syntax
response = client.update_radius(
DirectoryId='string',
RadiusSettings={
'RadiusServers': [
'string',
],
'RadiusPort': 123,
'RadiusTimeout': 123,
'RadiusRetries': 123,
'SharedSecret': 'string',
'AuthenticationProtocol': 'PAP'|'CHAP'|'MS-CHAPv1'|'MS-CHAPv2',
'DisplayLabel': 'string',
'UseSameUsername': True|False
}
)
3.1. Services 753
Boto3 Documentation, Release 1.1.4
Parameters
• DirectoryId (string) – [REQUIRED]
The identifier of the directory to update the RADIUS server information for.
• RadiusSettings (dict) – [REQUIRED]
A RadiusSettings object that contains information about the RADIUS server.
– RadiusServers (list) –
An array of strings that contains the IP addresses of the RADIUS server
endpoints, or the IP addresses of your RADIUS server load balancer.
* (string) –
– RadiusPort (integer) –
The port that your RADIUS server is using for communications. Your on-
premises network must allow inbound traffic over this port from the AWS
Directory Service servers.
– RadiusTimeout (integer) –
The amount of time, in seconds, to wait for the RADIUS server to respond.
– RadiusRetries (integer) –
The maximum number of times that communication with the RADIUS
server is attempted.
– SharedSecret (string) –
The shared secret code that was specified when your RADIUS endpoints
were created.
– AuthenticationProtocol (string) –
The protocol specified for your RADIUS endpoints.
– DisplayLabel (string) –
Not currently used.
– UseSameUsername (boolean) –
Not currently used.
Return type dict
Returns
Response Syntax
{}
Response Structure
• (dict) –
Contains the results of the UpdateRadius operation.
DynamoDB
754 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Table of Contents
• DynamoDB
– Client
– Paginators
– Waiters
– Service Resource
– Table
Client
class DynamoDB.Client
A low-level client representing Amazon DynamoDB:
import boto3
client = boto3.client('dynamodb')
These are the available methods:
•batch_get_item()
•batch_write_item()
•can_paginate()
•create_table()
•delete_item()
•delete_table()
•describe_table()
•generate_presigned_url()
•get_item()
•get_paginator()
•get_waiter()
•list_tables()
•put_item()
•query()
•scan()
•update_item()
•update_table()
batch_get_item(**kwargs)
The BatchGetItem operation returns the attributes of one or more items from one or more tables. You
identify requested items by primary key.
A single operation can retrieve up to 16 MB of data, which can contain as many as 100 items.
BatchGetItem will return a partial result if the response size limit is exceeded, the table’s provisioned
throughput is exceeded, or an internal processing failure occurs. If a partial result is returned, the opera-
tion returns a value for UnprocessedKeys . You can use this value to retry the operation starting with the
next item to get.
Warning: If you request more than 100 items BatchGetItem will return a ValidationException with
the message “Too many items requested for the BatchGetItem call”.
For example, if you ask to retrieve 100 items, but each individual item is 300 KB in size, the system
returns 52 items (so as not to exceed the 16 MB limit). It also returns an appropriate UnprocessedKeys
value so you can get the next page of results. If desired, your application can include its own logic to
assemble the pages of results into one data set.
3.1. Services 755
Boto3 Documentation, Release 1.1.4
If none of the items can be processed due to insufficient provisioned throughput on all of the tables in the
request, then BatchGetItem will return a ProvisionedThroughputExceededException . If at least one of
the items is successfully processed, then BatchGetItem completes successfully, while returning the keys
of the unread items in UnprocessedKeys .
Warning: If DynamoDB returns any unprocessed items, you should retry the batch operation on
those items. However, we strongly recommend that you use an exponential backoff algorithm . If
you retry the batch operation immediately, the underlying read or write requests can still fail due to
throttling on the individual tables. If you delay the batch operation using exponential backoff, the
individual requests in the batch are much more likely to succeed.
For more information, see Batch Operations and Error Handling in the Amazon DynamoDB Developer
Guide .
By default, BatchGetItem performs eventually consistent reads on every table in the request. If you want
strongly consistent reads instead, you can set ConsistentRead to true for any or all tables.
In order to minimize response latency, BatchGetItem retrieves items in parallel.
When designing your application, keep in mind that DynamoDB does not return attributes in any particular
order. To help parse the response by item, include the primary key values for the items in your request in
the AttributesToGet parameter.
If a requested item does not exist, it is not returned in the result. Requests for nonexistent items consume
the minimum read capacity units according to the type of read. For more information, see Capacity Units
Calculations in the Amazon DynamoDB Developer Guide .
Request Syntax
response = client.batch_get_item(
RequestItems={
'string': {
'Keys': [
{
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
],
'AttributesToGet': [
756 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string',
],
'ConsistentRead': True|False,
'ProjectionExpression': 'string',
'ExpressionAttributeNames': {
'string': 'string'
}
}
},
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE'
)
Parameters
• RequestItems (dict) – [REQUIRED]
A map of one or more table names and, for each table, a map that describes one
or more items to retrieve from that table. Each table name can be used only once
per BatchGetItem request.
Each element in the map of items to retrieve consists of the following:
– ConsistentRead - If true , a strongly consistent read is used; if false
(the default), an eventually consistent read is used.
– ExpressionAttributeNames - One or more substitution tokens for attribute
names in the ProjectionExpression parameter. The following are some use
cases for using ExpressionAttributeNames : * To access an attribute whose
name conflicts with a DynamoDB reserved word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– Keys - An array of primary key attribute values that define specific items in
the table. For each primary key, you must provide all of the key attributes.
For example, with a hash type primary key, you only need to provide the
hash attribute. For a hash-and-range type primary key, you must provide
both the hash attribute and the range attribute.
– ProjectionExpression - A string that identifies one or more attributes to re-
trieve from the table. These attributes can include scalars, sets, or elements
of a JSON document. The attributes in the expression must be separated
by commas. If no attribute names are specified, then all attributes will be
returned. If any of the requested attributes are not found, they will not
3.1. Services 757
Boto3 Documentation, Release 1.1.4
appear in the result. For more information, see Accessing Item Attributes
in the Amazon DynamoDB Developer Guide .
– AttributesToGet - .. warning:: This is a legacy parameter, for backward
compatibility. New applications should use ProjectionExpression instead.
Do not combine legacy parameters and expression parameters in a single
API call; otherwise, DynamoDB will return a ValidationException excep-
tion. This parameter allows you to retrieve attributes of type List or Map;
however, it cannot retrieve individual elements within a List or a Map. The
names of one or more attributes to retrieve. If no attribute names are pro-
vided, then all attributes will be returned. If any of the requested attributes
are not found, they will not appear in the result. Note that AttributesToGet
has no effect on provisioned throughput consumption. DynamoDB deter-
mines capacity units consumed based on item size, not on the amount of
data that is returned to an application.
– (string) –
* (dict) –
Represents a set of primary keys and, for each key, the attributes to
retrieve from the table.
For each primary key, you must provide all of the key attributes. For
example, with a hash type primary key, you only need to provide
the hash attribute. For a hash-and-range type primary key, you must
provide both the hash attribute and the range attribute.
· Keys (list) – [REQUIRED]
The primary key attribute values that define the items and the
attributes associated with the items.
· (dict) –
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
758 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· AttributesToGet (list) –
One or more attributes to retrieve from the table or index. If
no attribute names are specified then all attributes will be re-
turned. If any of the specified attributes are not found, they
will not appear in the result.
· (string) –
· ConsistentRead (boolean) –
The consistency of a read operation. If set to true , then
a strongly consistent read is used; otherwise, an eventually
consistent read is used.
· ProjectionExpression (string) –
A string that identifies one or more attributes to retrieve from
the table. These attributes can include scalars, sets, or ele-
ments of a JSON document. The attributes in the Projection-
Expression must be separated by commas.
If no attribute names are specified, then all attributes will be
returned. If any of the requested attributes are not found, they
will not appear in the result.
For more information, see Accessing Item Attributes in the
Amazon DynamoDB Developer Guide .
3.1. Services 759
Boto3 Documentation, Release 1.1.4
Note: ProjectionExpression replaces the legacy At-
tributesToGet parameter.
· ExpressionAttributeNames (dict) –
One or more substitution tokens for attribute names in an ex-
pression. The following are some use cases for using Expres-
sionAttributeNames :
· To access an attribute whose name conflicts with a Dy-
namoDB reserved word.
· To create a placeholder for repeating occurrences of an at-
tribute name in an expression.
· To prevent special characters in an attribute name from being
misinterpreted in an expression.
Use the # character in an expression to dereference an at-
tribute name. For example, consider the following attribute
name:
· Percentile
The name of this attribute conflicts with a reserved word, so
it cannot be used directly in an expression. (For the complete
list of reserved words, see Reserved Words in the Amazon
DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
· {"#P":"Percentile"}
You could then use this substitution in an expression, as in
this example:
· #P = :val
Note: Tokens that begin with the : character are expression
attribute values , which are placeholders for the actual value
at runtime.
For more information on expression attribute names, see Ac-
cessing Item Attributes in the Amazon DynamoDB Developer
Guide .
· (string) –
· (string) –
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
Return type dict
Returns
Response Syntax
760 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Responses': {
'string': [
{
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
]
},
'UnprocessedKeys': {
'string': {
'Keys': [
{
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
],
'AttributesToGet': [
'string',
3.1. Services 761
Boto3 Documentation, Release 1.1.4
],
'ConsistentRead': True|False,
'ProjectionExpression': 'string',
'ExpressionAttributeNames': {
'string': 'string'
}
}
},
'ConsumedCapacity': [
{
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
]
}
Response Structure
• (dict) –
Represents the output of a BatchGetItem operation.
– Responses (dict) –
A map of table name to a list of items. Each object in Responses consists
of a table name, along with a map of attribute data consisting of the data
type and attribute value.
* (string) –
· (list) –
· (dict) –
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
762 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– UnprocessedKeys (dict) –
A map of tables and their respective keys that were not processed with
the current response. The UnprocessedKeys value is in the same form
as RequestItems , so the value can be provided directly to a subsequent
BatchGetItem operation. For more information, see RequestItems in the
Request Parameters section.
Each element consists of:
* Keys - An array of primary key attribute values that define specific
items in the table.
* AttributesToGet - One or more attributes to be retrieved from the
table or index. By default, all attributes are returned. If a requested
attribute is not found, it does not appear in the result.
3.1. Services 763
Boto3 Documentation, Release 1.1.4
* ConsistentRead - The consistency of a read operation. If set to
true , then a strongly consistent read is used; otherwise, an even-
tually consistent read is used.
If there are no unprocessed keys remaining, the response contains an
empty UnprocessedKeys map.
* (string) –
· (dict) –
Represents a set of primary keys and, for each key, the at-
tributes to retrieve from the table.
For each primary key, you must provide all of the key at-
tributes. For example, with a hash type primary key, you only
need to provide the hash attribute. For a hash-and-range type
primary key, you must provide both the hash attribute and the
range attribute.
· Keys (list) –
The primary key attribute values that define the items and the
attributes associated with the items.
· (dict) –
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
764 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· AttributesToGet (list) –
One or more attributes to retrieve from the table or index. If
no attribute names are specified then all attributes will be re-
turned. If any of the specified attributes are not found, they
will not appear in the result.
· (string) –
· ConsistentRead (boolean) –
The consistency of a read operation. If set to true , then
a strongly consistent read is used; otherwise, an eventually
consistent read is used.
· ProjectionExpression (string) –
A string that identifies one or more attributes to retrieve from
the table. These attributes can include scalars, sets, or ele-
ments of a JSON document. The attributes in the Projection-
Expression must be separated by commas.
If no attribute names are specified, then all attributes will be
returned. If any of the requested attributes are not found, they
will not appear in the result.
For more information, see Accessing Item Attributes in the
Amazon DynamoDB Developer Guide .
Note: ProjectionExpression replaces the legacy At-
tributesToGet parameter.
· ExpressionAttributeNames (dict) –
One or more substitution tokens for attribute names in an ex-
pression. The following are some use cases for using Expres-
3.1. Services 765
Boto3 Documentation, Release 1.1.4
sionAttributeNames :
· To access an attribute whose name conflicts with a Dy-
namoDB reserved word.
· To create a placeholder for repeating occurrences of an at-
tribute name in an expression.
· To prevent special characters in an attribute name from being
misinterpreted in an expression.
Use the # character in an expression to dereference an at-
tribute name. For example, consider the following attribute
name:
· Percentile
The name of this attribute conflicts with a reserved word, so
it cannot be used directly in an expression. (For the complete
list of reserved words, see Reserved Words in the Amazon
DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
· {"#P":"Percentile"}
You could then use this substitution in an expression, as in
this example:
· #P = :val
Note: Tokens that begin with the : character are expression
attribute values , which are placeholders for the actual value
at runtime.
For more information on expression attribute names, see Ac-
cessing Item Attributes in the Amazon DynamoDB Developer
Guide .
· (string) –
· (string) –
– ConsumedCapacity (list) –
The read capacity units consumed by the operation.
Each element consists of:
* TableName - The table that consumed the provisioned throughput.
* CapacityUnits - The total number of capacity units consumed.
* (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
· TableName (string) –
The name of the table that was affected by the operation.
· CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
· Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
766 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The total number of capacity units consumed on a table or an
index.
· LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
· GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
batch_write_item(**kwargs)
The BatchWriteItem operation puts or deletes multiple items in one or more tables. A single call to
BatchWriteItem can write up to 16 MB of data, which can comprise as many as 25 put or delete requests.
Individual items to be written can be as large as 400 KB.
Note: BatchWriteItem cannot update items. To update items, use the UpdateItem API.
The individual PutItem and DeleteItem operations specified in BatchWriteItem are atomic; however Batch-
WriteItem as a whole is not. If any requested operations fail because the table’s provisioned throughput
is exceeded or an internal processing failure occurs, the failed operations are returned in the Unpro-
cessedItems response parameter. You can investigate and optionally resend the requests. Typically, you
would call BatchWriteItem in a loop. Each iteration would check for unprocessed items and submit a new
BatchWriteItem request with those unprocessed items until all items have been processed.
Note that if none of the items can be processed due to insufficient provisioned throughput on all of the
tables in the request, then BatchWriteItem will return a ProvisionedThroughputExceededException .
Warning: If DynamoDB returns any unprocessed items, you should retry the batch operation on
those items. However, we strongly recommend that you use an exponential backoff algorithm . If
you retry the batch operation immediately, the underlying read or write requests can still fail due to
throttling on the individual tables. If you delay the batch operation using exponential backoff, the
individual requests in the batch are much more likely to succeed.
For more information, see Batch Operations and Error Handling in the Amazon DynamoDB Developer
Guide .
With BatchWriteItem , you can efficiently write or delete large amounts of data, such as from Amazon
Elastic MapReduce (EMR), or copy data from another database into DynamoDB. In order to improve
performance with these large-scale operations, BatchWriteItem does not behave in the same way as indi-
3.1. Services 767
Boto3 Documentation, Release 1.1.4
vidual PutItem and DeleteItem calls would. For example, you cannot specify conditions on individual put
and delete requests, and BatchWriteItem does not return deleted items in the response.
If you use a programming language that supports concurrency, you can use threads to write items in
parallel. Your application must include the necessary logic to manage the threads. With languages that
don’t support threading, you must update or delete the specified items one at a time. In both situations,
BatchWriteItem provides an alternative where the API performs the specified put and delete operations in
parallel, giving you the power of the thread pool approach without having to introduce complexity into
your application.
Parallel processing reduces latency, but each specified put and delete request consumes the same number
of write capacity units whether it is processed in parallel or not. Delete operations on nonexistent items
consume one write capacity unit.
If one or more of the following is true, DynamoDB rejects the entire batch write operation:
•One or more tables specified in the BatchWriteItem request does not exist.
•Primary key attributes specified on an item in the request do not match those in the corresponding
table’s primary key schema.
•You try to perform multiple operations on the same item in the same BatchWriteItem request. For
example, you cannot put and delete the same item in the same BatchWriteItem request.
•There are more than 25 requests in the batch.
•Any individual item in a batch exceeds 400 KB.
•The total request size exceeds 16 MB.
Request Syntax
response = client.batch_write_item(
RequestItems={
'string': [
{
'PutRequest': {
'Item': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
}
},
'DeleteRequest': {
'Key': {
'string': {
768 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
}
}
},
]
},
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ReturnItemCollectionMetrics='SIZE'|'NONE'
)
Parameters
• RequestItems (dict) – [REQUIRED]
A map of one or more table names and, for each table, a list of operations to be
performed (DeleteRequest or PutRequest ). Each element in the map consists of
the following:
– DeleteRequest - Perform a DeleteItem operation on the specified item. The
item to be deleted is identified by a Key subelement: * Key - A map of
primary key attribute values that uniquely identify the ! item. Each entry
in this map consists of an attribute name and an attribute value. For each
primary key, you must provide all of the key attributes. For example, with
a hash type primary key, you only need to provide the hash attribute. For a
hash-and-range type primary key, you must provide both the hash attribute
and the range attribute.
– PutRequest - Perform a PutItem operation on the specified item. The item
to be put is identified by an Item subelement: * Item - A map of attributes
and their values. Each entry in this map consists of an attribute name and
an attribute value. Attribute values must not be null; string and binary type
attributes must have lengths greater than zero; and set type attributes must
not be empty. Requests that contain empty values will be rejected with a
ValidationException exception. If you specify any attributes that are part
of an index key, then the data types for those attributes must match those
of the schema in the table’s attribute definition.
– (string) –
* (list) –
· (dict) –
3.1. Services 769
Boto3 Documentation, Release 1.1.4
Represents an operation to perform - either DeleteItem or
PutItem . You can only request one of these operations, not
both, in a single WriteRequest . If you do need to perform
both of these operations, you will need to provide two sepa-
rate WriteRequest objects.
· PutRequest (dict) –
A request to perform a PutItem operation.
· Item (dict) – [REQUIRED]
A map of attribute name to attribute values, representing the
primary key of an item to be processed by PutItem . All of
the table’s primary key attributes must be specified, and their
data types must match those of the table’s key schema. If any
attributes are present in the item which are part of an index
key schema for the table, their types must match the index
key schema.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
770 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· DeleteRequest (dict) –
A request to perform a DeleteItem operation.
· Key (dict) – [REQUIRED]
A map of attribute name to attribute values, representing the
primary key of the item to delete. All of the table’s primary
key attributes must be specified, and their data types must
match those of the table’s key schema.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
3.1. Services 771
Boto3 Documentation, Release 1.1.4
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ReturnItemCollectionMetrics (string) – Determines whether item collection
metrics are returned. If set to SIZE , the response includes statistics about item
collections, if any, that were modified during the operation are returned in the
response. If set to NONE (the default), no statistics are returned.
Return type dict
Returns
Response Syntax
{
'UnprocessedItems': {
'string': [
772 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'PutRequest': {
'Item': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
}
},
'DeleteRequest': {
'Key': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
}
}
},
]
},
'ItemCollectionMetrics': {
'string': [
3.1. Services 773
Boto3 Documentation, Release 1.1.4
{
'ItemCollectionKey': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'SizeEstimateRangeGB': [
123.0,
]
},
]
},
'ConsumedCapacity': [
{
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
]
}
Response Structure
• (dict) –
Represents the output of a BatchWriteItem operation.
– UnprocessedItems (dict) –
A map of tables and requests against those tables that were not processed.
774 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The UnprocessedItems value is in the same form as RequestItems , so you
can provide this value directly to a subsequent BatchGetItem operation.
For more information, see RequestItems in the Request Parameters section.
Each UnprocessedItems entry consists of a table name and, for that table,
a list of operations to perform (DeleteRequest or PutRequest ).
* DeleteRequest - Perform a DeleteItem operation on the specified
item. The item to be deleted is identified by a Key subelement: *
Key - A map of primary key attribute values that uniquely identify
the item. Each entry in this map consists of an attribute name and
an attribute value.
* PutRequest - Perform a PutItem operation on the specified item. The
item to be put is identified by an Item subelement: * Item - A map
of attributes and their values. Each entry in this map consists of
an attribute name and an attribute value. Attribute values must not
be null; string and binary type attributes must have lengths greater
than zero; and set type attributes must not be empty. Requests that
contain empty values will be rejected with a ValidationException
exception. If you specify any attributes that are part of an index
key, then the data types for those attributes must match those of the
schema in the table’s attribute definition.
If there are no unprocessed items remaining, the response contains an
empty UnprocessedItems map.
* (string) –
· (list) –
· (dict) –
Represents an operation to perform - either DeleteItem or
PutItem . You can only request one of these operations, not
both, in a single WriteRequest . If you do need to perform
both of these operations, you will need to provide two sepa-
rate WriteRequest objects.
· PutRequest (dict) –
A request to perform a PutItem operation.
· Item (dict) –
A map of attribute name to attribute values, representing the
primary key of an item to be processed by PutItem . All of
the table’s primary key attributes must be specified, and their
data types must match those of the table’s key schema. If any
attributes are present in the item which are part of an index
key schema for the table, their types must match the index
key schema.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
3.1. Services 775
Boto3 Documentation, Release 1.1.4
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· DeleteRequest (dict) –
A request to perform a DeleteItem operation.
· Key (dict) –
A map of attribute name to attribute values, representing the
primary key of the item to delete. All of the table’s primary
key attributes must be specified, and their data types must
match those of the table’s key schema.
776 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
3.1. Services 777
Boto3 Documentation, Release 1.1.4
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– ItemCollectionMetrics (dict) –
A list of tables that were processed by BatchWriteItem and, for each table,
information about any item collections that were affected by individual
DeleteItem or PutItem operations.
Each entry consists of the following subelements:
* ItemCollectionKey - The hash key value of the item collection. This
is the same as the hash key of the item.
* SizeEstimateRange - An estimate of item collection size, expressed
in GB. This is a two-element array containing a lower bound and
an upper bound for the estimate. The estimate includes the size of
all the items in the table, plus the size of all attributes projected into
all of the local secondary indexes on the table. Use this estimate
to measure whether a local secondary index is approaching its size
limit. The estimate is subject to change over time; therefore, do not
rely on the precision or accuracy of the estimate.
* (string) –
· (list) –
· (dict) –
Information about item collections, if any, that were affected
by the operation. ItemCollectionMetrics is only returned if
the request asked for it. If the table does not have any lo-
cal secondary indexes, this information is not returned in the
response.
· ItemCollectionKey (dict) –
The hash key value of the item collection. This value is the
same as the hash key of the item.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
778 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· SizeEstimateRangeGB (list) –
An estimate of item collection size, in gigabytes. This value
is a two-element array containing a lower bound and an upper
bound for the estimate. The estimate includes the size of all
the items in the table, plus the size of all attributes projected
into all of the local secondary indexes on that table. Use this
estimate to measure whether a local secondary index is ap-
proaching its size limit.
The estimate is subject to change over time; therefore, do not
rely on the precision or accuracy of the estimate.
· (float) –
– ConsumedCapacity (list) –
The capacity units consumed by the operation.
Each element consists of:
* TableName - The table that consumed the provisioned throughput.
* CapacityUnits - The total number of capacity units consumed.
3.1. Services 779
Boto3 Documentation, Release 1.1.4
* (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
· TableName (string) –
The name of the table that was affected by the operation.
· CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
· Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
· LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
· GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
780 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
create_table(**kwargs)
The CreateTable operation adds a new table to your account. In an AWS account, table names must be
unique within each region. That is, you can have two tables with same name if you create the tables in
different regions.
CreateTable is an asynchronous operation. Upon receiving a CreateTable request, DynamoDB immedi-
ately returns a response with a TableStatus of CREATING . After the table is created, DynamoDB sets the
TableStatus to ACTIVE . You can perform read and write operations only on an ACTIVE table.
You can optionally define secondary indexes on the new table, as part of the CreateTable operation. If you
want to create multiple tables with secondary indexes on them, you must create the tables sequentially.
Only one table with secondary indexes can be in the CREATING state at any given time.
You can use the DescribeTable API to check the table status.
Request Syntax
response = client.create_table(
AttributeDefinitions=[
{
'AttributeName': 'string',
'AttributeType': 'S'|'N'|'B'
},
],
TableName='string',
KeySchema=[
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
LocalSecondaryIndexes=[
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
}
},
],
GlobalSecondaryIndexes=[
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
3.1. Services 781
Boto3 Documentation, Release 1.1.4
'NonKeyAttributes': [
'string',
]
},
'ProvisionedThroughput': {
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
}
},
],
ProvisionedThroughput={
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
StreamSpecification={
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_ONLY'
}
)
Parameters
• AttributeDefinitions (list) – [REQUIRED]
An array of attributes that describe the key schema for the table and indexes.
– (dict) –
Represents an attribute for describing the key schema for the table and
indexes.
* AttributeName (string) – [REQUIRED]
A name for the attribute.
* AttributeType (string) – [REQUIRED]
The data type for the attribute.
• TableName (string) – [REQUIRED]
The name of the table to create.
• KeySchema (list) – [REQUIRED]
Specifies the attributes that make up the primary key for a table or an index. The
attributes in KeySchema must also be defined in the AttributeDefinitions array.
For more information, see Data Model in the Amazon DynamoDB Developer
Guide .
Each KeySchemaElement in the array is composed of:
– AttributeName - The name of this key attribute.
– KeyType - Determines whether the key attribute is HASH or RANGE .
For a primary key that consists of a hash attribute, you must provide exactly one
element with a KeyType of HASH .
For a primary key that consists of hash and range attributes, you must provide
exactly two elements, in this order: The first element must have a KeyType of
HASH , and the second element must have a KeyType of RANGE .
For more information, see Specifying the Primary Key in the Amazon Dy-
namoDB Developer Guide .
– (dict) –
Represents a single element of a key schema. A key schema specifies the
attributes that make up the primary key of a table, or the key attributes of
782 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
an index.
A KeySchemaElement represents exactly one attribute of the primary key.
For example, a hash type primary key would be represented by one
KeySchemaElement . A hash-and-range type primary key would require
one KeySchemaElement for the hash attribute, and another KeySchemaEle-
ment for the range attribute.
* AttributeName (string) – [REQUIRED]
The name of a key attribute.
* KeyType (string) – [REQUIRED]
The attribute data, consisting of the data type and the attribute value
itself.
• LocalSecondaryIndexes (list) – One or more local secondary indexes (the max-
imum is five) to be created on the table. Each index is scoped to a given hash
key value. There is a 10 GB size limit per hash key; otherwise, the size of a local
secondary index is unconstrained.
Each local secondary index in the array includes the following:
– IndexName - The name of the local secondary index. Must be unique only
for this table.
– KeySchema - Specifies the key schema for the local secondary index. The
key schema must begin with the same hash key attribute as the table.
– Projection - Specifies attributes that are copied (projected) from the table
into the index. These are in addition to the primary key attributes and
index key attributes, which are automatically projected. Each attribute
specification is composed of: * ProjectionType - One of the following:
* KEYS_ONLY - Only the index and primary keys are projected into the
index.
– INCLUDE - Only the specified table attributes are projected into the index.
The list of projected attributes are in NonKeyAttributes .
– ALL - All of the table attributes are projected into the index.
– NonKeyAttributes - A list of one or more non-key attribute names that are
projected into the secondary index. The total count of attributes provided
in NonKeyAttributes , summed across all of the secondary indexes, must
not exceed 20. If you project the same attribute into two different indexes,
this counts as two distinct attributes when determining the total.
– (dict) –
Represents the properties of a local secondary index.
* IndexName (string) – [REQUIRED]
The name of the local secondary index. The name must be unique
among all other indexes on this table.
* KeySchema (list) – [REQUIRED]
The complete key schema for the local secondary index, consisting
of one or more pairs of attribute names and key types (HASH or
RANGE ).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
3.1. Services 783
Boto3 Documentation, Release 1.1.4
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) – [REQUIRED]
The name of a key attribute.
· KeyType (string) – [REQUIRED]
The attribute data, consisting of the data type and the attribute
value itself.
* Projection (dict) – [REQUIRED]
Represents attributes that are copied (projected) from the table into
an index. These are in addition to the primary key attributes and
index key attributes, which are automatically projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
• GlobalSecondaryIndexes (list) – One or more global secondary indexes (the
maximum is five) to be created on the table. Each global secondary index in the
array includes the following:
– IndexName - The name of the global secondary index. Must be unique
only for this table.
– KeySchema - Specifies the key schema for the global secondary index.
– Projection - Specifies attributes that are copied (projected) from the table
into the index. These are in addition to the primary key attributes and
index key attributes, which are automatically projected. Each attribute
specification is composed of: * ProjectionType - One of the following:
* KEYS_ONLY - Only the index and primary keys are projected into the
index.
– INCLUDE - Only the specified table attributes are projected into the index.
The list of projected attributes are in NonKeyAttributes .
– ALL - All of the table attributes are projected into the index.
– NonKeyAttributes - A list of one or more non-key attribute names that are
projected into the secondary index. The total count of attributes provided
in NonKeyAttributes , summed across all of the secondary indexes, must
not exceed 20. If you project the same attribute into two different indexes,
this counts as two distinct attributes when determining the total.
784 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– ProvisionedThroughput - The provisioned throughput settings for the
global secondary index, consisting of read and write capacity units.
– (dict) –
Represents the properties of a global secondary index.
* IndexName (string) – [REQUIRED]
The name of the global secondary index. The name must be unique
among all other indexes on this table.
* KeySchema (list) – [REQUIRED]
The complete key schema for a global secondary index, which con-
sists of one or more pairs of attribute names and key types (HASH
or RANGE ).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) – [REQUIRED]
The name of a key attribute.
· KeyType (string) – [REQUIRED]
The attribute data, consisting of the data type and the attribute
value itself.
* Projection (dict) – [REQUIRED]
Represents attributes that are copied (projected) from the table into
an index. These are in addition to the primary key attributes and
index key attributes, which are automatically projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
3.1. Services 785
Boto3 Documentation, Release 1.1.4
* ProvisionedThroughput (dict) – [REQUIRED]
Represents the provisioned throughput settings for a specified ta-
ble or index. The settings can be modified using the UpdateTable
operation.
For current minimum and maximum provisioned throughput values,
see Limits in the Amazon DynamoDB Developer Guide .
· ReadCapacityUnits (integer) – [REQUIRED]
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. For more information, see Specifying Read and Write Re-
quirements in the Amazon DynamoDB Developer Guide .
· WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException . For more infor-
mation, see Specifying Read and Write Requirements in the
Amazon DynamoDB Developer Guide .
• ProvisionedThroughput (dict) – [REQUIRED]
Represents the provisioned throughput settings for a specified table or index.
The settings can be modified using the UpdateTable operation.
For current minimum and maximum provisioned throughput values, see Limits
in the Amazon DynamoDB Developer Guide .
– ReadCapacityUnits (integer) – [REQUIRED]
The maximum number of strongly consistent reads consumed per second
before DynamoDB returns a ThrottlingException . For more information,
see Specifying Read and Write Requirements in the Amazon DynamoDB
Developer Guide .
– WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per second before DynamoDB
returns a ThrottlingException . For more information, see Specifying Read
and Write Requirements in the Amazon DynamoDB Developer Guide .
• StreamSpecification (dict) – The settings for DynamoDB Streams on the table.
These settings consist of:
– StreamEnabled - Indicates whether Streams is to be enabled (true) or dis-
abled (false).
– StreamViewType - When an item in the table is modified, StreamViewType
determines what information is written to the table’s stream. Valid values
for StreamViewType are: * KEYS_ONLY - Only the key attributes of the
modified item are written to the stream.
– NEW_IMAGE - The entire item, as it appears after it was modified, is
written to the stream.
– OLD_IMAGE - The entire item, as it appeared before it was modified, is
written to the stream.
– NEW_AND_OLD_IMAGES - Both the new and the old item images of the
item are written to the stream.
– StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled (true) or disabled (false)
on the table.
– StreamViewType (string) –
786 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The DynamoDB Streams settings for the table. These settings consist of:
* StreamEnabled - Indicates whether DynamoDB Streams is enabled
(true) or disabled (false) on the table.
* StreamViewType - When an item in the table is modified,
StreamViewType determines what information is written to the
stream for this table. Valid values for StreamViewType are: *
KEYS_ONLY - Only the key attributes of the modified item are writ-
ten to the stream.
* NEW_IMAGE - The entire item, as it appears after it was modified,
is written to the stream.
* OLD_IMAGE - The entire item, as it appeared before it was modi-
fied, is written to the stream.
* NEW_AND_OLD_IMAGES - Both the new and the old item images
of the item are written to the stream.
Return type dict
Returns
Response Syntax
{
'TableDescription': {
'AttributeDefinitions': [
{
'AttributeName': 'string',
'AttributeType': 'S'|'N'|'B'
},
],
'TableName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'TableStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'CreationDateTime': datetime(2015, 1, 1),
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'TableSizeBytes': 123,
'ItemCount': 123,
'TableArn': 'string',
'LocalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
3.1. Services 787
Boto3 Documentation, Release 1.1.4
'NonKeyAttributes': [
'string',
]
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
},
],
'GlobalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'Backfilling': True|False,
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
},
],
'StreamSpecification': {
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_O
},
'LatestStreamLabel': 'string',
'LatestStreamArn': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a CreateTable operation.
– TableDescription (dict) –
Represents the properties of a table.
* AttributeDefinitions (list) –
An array of AttributeDefinition objects. Each of these objects de-
scribes one attribute in the table and index key schema.
788 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Each AttributeDefinition object in this array is composed of:
· AttributeName - The name of the attribute.
· AttributeType - The data type for the attribute.
· (dict) –
Represents an attribute for describing the key schema for the
table and indexes.
· AttributeName (string) –
A name for the attribute.
· AttributeType (string) –
The data type for the attribute.
* TableName (string) –
The name of the table.
* KeySchema (list) –
The primary key structure for the table. Each KeySchemaElement
consists of:
· AttributeName - The name of the attribute.
· KeyType - The key type for the attribute. Can be either HASH
or RANGE .
For more information about primary keys, see Primary Key in the
Amazon DynamoDB Developer Guide .
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
* TableStatus (string) –
The current state of the table:
· CREATING - The table is being created.
· UPDATING - The table is being updated.
· DELETING - The table is being deleted.
· ACTIVE - The table is ready for use.
* CreationDateTime (datetime) –
The date and time when the table was created, in UNIX epoch time
format.
* ProvisionedThroughput (dict) –
The provisioned throughput settings for the table, consisting of read
3.1. Services 789
Boto3 Documentation, Release 1.1.4
and write capacity units, along with data about increases and de-
creases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput increase
for this table.
· LastDecreaseDateTime (datetime) –
The date and time of the last provisioned throughput decrease
for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for this ta-
ble during this UTC calendar day. For current maximums on
provisioned throughput decreases, see Limits in the Amazon
DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. Eventually consistent reads require less effort than strongly
consistent reads, so a setting of 50 ReadCapacityUnits per
second provides 100 eventually consistent ReadCapacityU-
nits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException .
* TableSizeBytes (integer) –
The total size of the specified table, in bytes. DynamoDB updates
this value approximately every six hours. Recent changes might not
be reflected in this value.
* ItemCount (integer) –
The number of items in the specified table. DynamoDB updates this
value approximately every six hours. Recent changes might not be
reflected in this value.
* TableArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies the ta-
ble.
* LocalSecondaryIndexes (list) –
Represents one or more local secondary indexes on the table. Each
index is scoped to a given hash key value. Tables with one or more
local secondary indexes are subject to an item collection size limit,
where the amount of data within a given item collection cannot ex-
ceed 10 GB. Each element is composed of:
· IndexName - The name of the local secondary index.
· KeySchema - Specifies the complete index key schema. The
attribute names in the key schema must be between 1 and 255
characters (inclusive). The key schema must begin with the
same hash key attribute as the table.
· Projection - Specifies attributes that are copied (projected)
from the table into the index. These are in addition to the pri-
mary key attributes and index key attributes, which are auto-
matically projected. Each attribute specification is composed
790 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
of: * ProjectionType - One of the following: * KEYS_ONLY -
Only the index and primary keys are projected into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes - A list of one or more non-key attribute
names that are projected into the secondary index. The total
count of attributes provided in NonKeyAttributes , summed
across all of the secondary indexes, must not exceed 20. If
you project the same attribute into two different indexes, this
counts as two distinct attributes when determining the total.
· IndexSizeBytes - Represents the total size of the index, in
bytes. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
· ItemCount - Represents the number of items in the index. Dy-
namoDB updates this value approximately every six hours.
Recent changes might not be reflected in this value.
If the table is in the DELETING state, no information about indexes
will be returned.
· (dict) –
Represents the properties of a local secondary index.
· IndexName (string) –
Represents the name of the local secondary index.
· KeySchema (list) –
The complete index key schema, which consists of one or
more pairs of attribute names and key types (HASH or RANGE
).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
· ProjectionType (string) –
3.1. Services 791
Boto3 Documentation, Release 1.1.4
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· ItemCount (integer) –
The number of items in the specified index. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the index.
* GlobalSecondaryIndexes (list) –
The global secondary indexes, if any, on the table. Each index is
scoped to a given hash key value. Each element is composed of:
· Backfilling - If true, then the index is currently in the back-
filling phase. Backfilling occurs only when a new global sec-
ondary index is added to the table; it is the process by which
DynamoDB populates the new index with data from the table.
(This attribute does not appear for indexes that were created
during a CreateTable operation.)
· IndexName - The name of the global secondary index.
· IndexSizeBytes - The total size of the global secondary index,
in bytes. DynamoDB updates this value approximately every
six hours. Recent changes might not be reflected in this value.
· IndexStatus - The current status of the global secondary index:
* CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· ItemCount - The number of items in the global secondary in-
dex. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
· KeySchema - Specifies the complete index key schema. The
attribute names in the key schema must be between 1 and 255
characters (inclusive). The key schema must begin with the
792 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
same hash key attribute as the table.
· Projection - Specifies attributes that are copied (projected)
from the table into the index. These are in addition to the pri-
mary key attributes and index key attributes, which are auto-
matically projected. Each attribute specification is composed
of: * ProjectionType - One of the following: * KEYS_ONLY -
Only the index and primary keys are projected into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes - A list of one or more non-key attribute
names that are projected into the secondary index. The total
count of attributes provided in NonKeyAttributes , summed
across all of the secondary indexes, must not exceed 20. If
you project the same attribute into two different indexes, this
counts as two distinct attributes when determining the total.
· ProvisionedThroughput - The provisioned throughput settings
for the global secondary index, consisting of read and write
capacity units, along with data about increases and decreases.
If the table is in the DELETING state, no information about indexes
will be returned.
· (dict) –
Represents the properties of a global secondary index.
· IndexName (string) –
The name of the global secondary index.
· KeySchema (list) –
The complete key schema for the global secondary index,
consisting of one or more pairs of attribute names and key
types (HASH or RANGE ).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
3.1. Services 793
Boto3 Documentation, Release 1.1.4
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
· IndexStatus (string) –
The current state of the global secondary index:
· CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· Backfilling (boolean) –
Indicates whether the index is currently backfilling. Backfill-
ing is the process of reading items from the table and deter-
mining whether they can be added to the index. (Not all items
will qualify: For example, a hash key attribute cannot have
any duplicates.) If an item can be added to the index, Dy-
namoDB will do so. After all items have been processed, the
backfilling operation is complete and Backfilling is false.
Note: For indexes that were created during a CreateTable
operation, the Backfilling attribute does not appear in the De-
scribeTable output.
· ProvisionedThroughput (dict) –
Represents the provisioned throughput settings for the table,
consisting of read and write capacity units, along with data
about increases and decreases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput increase
for this table.
· LastDecreaseDateTime (datetime) –
The date and time of the last provisioned throughput decrease
for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for this ta-
ble during this UTC calendar day. For current maximums on
794 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
provisioned throughput decreases, see Limits in the Amazon
DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. Eventually consistent reads require less effort than strongly
consistent reads, so a setting of 50 ReadCapacityUnits per
second provides 100 eventually consistent ReadCapacityU-
nits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException .
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· ItemCount (integer) –
The number of items in the specified index. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the index.
* StreamSpecification (dict) –
The current DynamoDB Streams configuration for the table.
· StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled (true) or
disabled (false) on the table.
· StreamViewType (string) –
The DynamoDB Streams settings for the table. These settings
consist of:
· StreamEnabled - Indicates whether DynamoDB Streams is
enabled (true) or disabled (false) on the table.
· StreamViewType - When an item in the table is modified,
StreamViewType determines what information is written to the
stream for this table. Valid values for StreamViewType are: *
KEYS_ONLY - Only the key attributes of the modified item
are written to the stream.
· NEW_IMAGE - The entire item, as it appears after it was
modified, is written to the stream.
· OLD_IMAGE - The entire item, as it appeared before it was
modified, is written to the stream.
· NEW_AND_OLD_IMAGES - Both the new and the old item
images of the item are written to the stream.
* LatestStreamLabel (string) –
A timestamp, in ISO 8601 format, for this stream.
Note that LatestStreamLabel is not a unique identifier for the stream,
because it is possible that a stream from another table might have the
3.1. Services 795
Boto3 Documentation, Release 1.1.4
same timestamp. However, the combination of the following three
elements is guaranteed to be unique:
· the AWS customer ID.
· the table name.
· the StreamLabel .
* LatestStreamArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies the lat-
est stream for this table.
delete_item(**kwargs)
Deletes a single item in a table by primary key. You can perform a conditional delete operation that deletes
the item if it exists, or if it has an expected attribute value.
In addition to deleting an item, you can also return the item’s attribute values in the same operation, using
the ReturnValues parameter.
Unless you specify conditions, the DeleteItem is an idempotent operation; running it multiple times on
the same item or attribute does not result in an error response.
Conditional deletes are useful for deleting items only if specific conditions are met. If those conditions
are met, DynamoDB performs the delete. Otherwise, the item is not deleted.
Request Syntax
response = client.delete_item(
TableName='string',
Key={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
Expected={
'string': {
'Value': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
796 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
'Exists': True|False,
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
]
}
},
ConditionalOperator='AND'|'OR',
ReturnValues='NONE'|'ALL_OLD'|'UPDATED_OLD'|'ALL_NEW'|'UPDATED_NEW',
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ReturnItemCollectionMetrics='SIZE'|'NONE',
ConditionExpression='string',
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
3.1. Services 797
Boto3 Documentation, Release 1.1.4
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
}
)
Parameters
• TableName (string) – [REQUIRED]
The name of the table from which to delete the item.
• Key (dict) – [REQUIRED]
A map of attribute names to AttributeValue objects, representing the primary key
of the item to delete.
For the primary key, you must provide all of the attributes. For example, with a
hash type primary key, you only need to provide the hash attribute. For a hash-
and-range type primary key, you must provide both the hash attribute and the
range attribute.
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
798 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Warning: This is a legacy parameter, for backward compatibility. New ap-
plications should use ConditionExpression instead. Do not combine legacy
• Expected (dict) –
parameters and expression parameters in a single API call; otherwise, Dy-
namoDB will return a ValidationException exception.
A map of attribute/condition pairs. Expected provides a conditional block for the
DeleteItem operation.
Each element of Expected consists of an attribute name, a comparison operator,
and one or more values. DynamoDB compares the attribute with the value(s)
you supplied, using the comparison operator. For each Expected element, the
result of the evaluation is either true or false.
If you specify more than one element in the Expected map, then by default all of
the conditions must evaluate to true. In other words, the conditions are ANDed
together. (You can use the ConditionalOperator parameter to OR the conditions
instead. If you do this, then at least one of the conditions must evaluate to true,
rather than all of them.)
If the Expected map evaluates to true, then the conditional operation succeeds;
otherwise, it fails.
3.1. Services 799
Boto3 Documentation, Release 1.1.4
Expected contains the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the Com-
parisonOperator being used. For type Number, value comparisons are
numeric. String value comparisons for greater than, equals, or less
than are based on ASCII character code values. For example, a is
greater than A , and a is greater than B . For a list of code values,
see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters . For
type Binary, DynamoDB treats each byte of the binary data as unsigned
when it compares binary values.
– ComparisonOperator - A comparator for evaluating attributes in the
AttributeValueList . When performing the comparison, DynamoDB
uses strongly consistent reads. The following comparison operators
are available: EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH |
IN | BETWEEN The following are descriptions of each comparison
operator. * EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one AttributeValue element
of type String, Number, Binary, String Set, Number Set, or Binary Set.
If an item contains an AttributeValue element of a different type than
the one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
– NE : Not equal. NE is supported for all datatypes, including lists and
maps. AttributeValueList can contain only one AttributeValue of type
String, Number, Binary, String Set, Number Set, or Binary Set. If an item
contains an AttributeValue of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not equal {"NS":["6",
"2", "1"]} .
– LE : Less than or equal. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– LT : Less than. AttributeValueList can contain only one AttributeValue of
type String, Number, or Binary (not a set type). If an item contains an
AttributeValue element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type than
the one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
– GT : Greater than. AttributeValueList can contain only one AttributeValue
element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
800 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– NOT_NULL : The attribute exists. NOT_NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for the
existence of an attribute, not its data type. If the data type of attribute “a ”
is null, and you evaluate it using NOT_NULL , the result is a Boolean true
. This result is because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
– NULL : The attribute does not exist. NULL is supported for all datatypes,
including lists and maps. .. note::This operator tests for the nonexistence
of an attribute, not its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean false . This is
because the attribute “a ” exists; its data type is not relevant to the NULL
comparison operator.
– CONTAINS : Checks for a subsequence, or value in a set. AttributeVal-
ueList can contain only one AttributeValue element of type String, Num-
ber, or Binary (not a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring match. If the target
attribute of the comparison is of type Binary, then the operator looks for
a subsequence of the target that matches the input. If the target attribute
of the comparison is a set (“SS ”, “NS ”, or “BS ”), then the operator
evaluates to true if it finds an exact match with any member of the set.
CONTAINS is supported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a list.
– NOT_CONTAINS : Checks for absence of a subsequence, or absence of
a value in a set. AttributeValueList can contain only one AttributeValue
element of type String, Number, or Binary (not a set type). If the target
attribute of the comparison is a String, then the operator checks for the
absence of a substring match. If the target attribute of the comparison is
Binary, then the operator checks for the absence of a subsequence of the
target that matches the input. If the target attribute of the comparison is a
set (“SS ”, “NS ”, or “BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set. NOT_CONTAINS is
supported for lists: When evaluating “a NOT CONTAINS b ”, “a ” can
be a list; however, “b ” cannot be a set, a map, or a list.
– BEGINS_WITH : Checks for a prefix. AttributeValueList can contain only
one AttributeValue of type String or Binary (not a Number or a set type).
The target attribute of the comparison must be of type String or Binary
(not a Number or a set type).
– IN : Checks for matching elements within two sets. AttributeValueList can
contain one or more AttributeValue elements of type String, Number, or
Binary (not a set type). These attributes are compared against an existing
set type attribute of an item. If any elements of the input set are present in
the item attribute, the expression evaluates to true.
– BETWEEN : Greater than or equal to the first value, and less than or equal
to the second value. AttributeValueList must contain two AttributeValue el-
ements of the same type, either String, Number, or Binary (not a set type).
A target attribute matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If an item con-
tains an AttributeValue element of a different type than the one provided
in the request, the value does not match. For example, {"S":"6"} does
not compare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see Legacy
Conditional Parameters in the Amazon DynamoDB Developer Guide .
3.1. Services 801
Boto3 Documentation, Release 1.1.4
For backward compatibility with previous DynamoDB releases, the following
parameters can be used instead of AttributeValueList and ComparisonOperator :
– Value - A value for DynamoDB to compare with an attribute.
– Exists - A Boolean value that causes DynamoDB to evaluate the value
before attempting the conditional operation: * If Exists is true , Dy-
namoDB will check to see if that attribute value already exists in the table.
If it is found, then the condition evaluates to true; otherwise the condition
evaluate to false.
– If Exists is false , DynamoDB assumes that the attribute value does not
exist in the table. If in fact the value does not exist, then the assumption is
valid and the condition evaluates to true. If the value is found, despite the
assumption that it does not exist, the condition evaluates to false.
Note that the default value for Exists is true .
The Value and Exists parameters are incompatible with AttributeValueList and
ComparisonOperator . Note that if you use both sets of parameters at once,
DynamoDB will return a ValidationException exception.
Note: This parameter does not support attributes of type List or Map.
– (string) –
* (dict) –
Represents a condition to be compared with an attribute value. This
condition can be used with DeleteItem , PutItem or UpdateItem op-
erations; if the comparison evaluates to true, the operation succeeds;
if not, the operation fails. You can use ExpectedAttributeValue in
one of two different ways:
· Use AttributeValueList to specify one or more values to com-
pare against an attribute. Use ComparisonOperator to specify
how you want to perform the comparison. If the comparison
evaluates to true, then the conditional operation succeeds.
· Use Value to specify a value that DynamoDB will compare
against an attribute. If the values match, then ExpectedAt-
tributeValue evaluates to true and the conditional operation
succeeds. Optionally, you can also set Exists to false, indi-
cating that you do not expect to find the attribute value in the
table. In this case, the conditional operation succeeds only if
the comparison evaluates to false.
Value and Exists are incompatible with AttributeValueList and Com-
parisonOperator . Note that if you use both sets of parameters at
once, DynamoDB will return a ValidationException exception.
· Value (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
802 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· Exists (boolean) –
Causes DynamoDB to evaluate the value before attempting a
conditional operation:
· If Exists is true , DynamoDB will check to see if that at-
tribute value already exists in the table. If it is found, then the
operation succeeds. If it is not found, the operation fails with
a ConditionalCheckFailedException .
· If Exists is false , DynamoDB assumes that the attribute
value does not exist in the table. If in fact the value does not
exist, then the assumption is valid and the operation succeeds.
3.1. Services 803
Boto3 Documentation, Release 1.1.4
If the value is found, despite the assumption that it does not
exist, the operation fails with a ConditionalCheckFailedEx-
ception .
The default setting for Exists is true . If you supply a Value
all by itself, DynamoDB assumes the attribute exists: You
don’t have to set Exists to true , because it is implied.
DynamoDB returns a ValidationException if:
· Exists is true but there is no Value to check. (You expect a
value to exist, but don’t specify what that value is.)
· Exists is false but you also provide a Value . (You cannot
expect an attribute to have a value, while also expecting it not
to exist.)
· ComparisonOperator (string) –
A comparator for evaluating attributes in the AttributeVal-
ueList . For example, equals, greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
804 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
3.1. Services 805
Boto3 Documentation, Release 1.1.4
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
The number of values in the list depends on the Comparison-
Operator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
For information on specifying data types in JSON, see JSON
Data Format in the Amazon DynamoDB Developer Guide .
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
806 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Warning: This is a legacy parameter, for backward compatibility
plications should use ConditionExpression instead. Do not comb
• ConditionalOperator (string) –
parameters and expression parameters in a single API call; other
namoDB will return a ValidationException exception.
A logical operator to apply to the conditions in the Expected map:
– AND - If all of the conditions evaluate to true, then the entire map evaluates
to true.
– OR - If at least one of the conditions evaluate to true, then the entire map
evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
3.1. Services 807
Boto3 Documentation, Release 1.1.4
Note: This parameter does not support attributes of type List or Map.
• ReturnValues (string) – Use ReturnValues if you want to get the item attributes
as they appeared before they were deleted. For DeleteItem , the valid values are:
– NONE - If ReturnValues is not specified, or if its value is NONE , then
nothing is returned. (This setting is the default for ReturnValues .)
– ALL_OLD - The content of the old item is returned.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ReturnItemCollectionMetrics (string) – Determines whether item collection
metrics are returned. If set to SIZE , the response includes statistics about item
collections, if any, that were modified during the operation are returned in the
response. If set to NONE (the default), no statistics are returned.
• ConditionExpression (string) – A condition that must be satisfied in order for a
conditional DeleteItem to succeed.
An expression can contain any of the following:
– Functions: attribute_exists | attribute_not_exists
| attribute_type | contains | begins_with | size
These function names are case-sensitive.
– Comparison operators: = | | | | = | = | BETWEEN | IN
– Logical operators: AND | OR | NOT
For more information on condition expressions, see Specifying Conditions in the
Amazon DynamoDB Developer Guide .
Note: ConditionExpression replaces the legacy ConditionalOperator and Ex-
pected parameters.
• ExpressionAttributeNames (dict) – One or more substitution tokens for at-
tribute names in an expression. The following are some use cases for using
ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB reserved
word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
808 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be substituted
in an expression.
Use the : (colon) character in an expression to dereference an attribute value.
For example, suppose that you wanted to check whether the value of the Prod-
uctStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Conditions
in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
3.1. Services 809
Boto3 Documentation, Release 1.1.4
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Return type dict
Returns
Response Syntax
{
'Attributes': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
810 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'BOOL': True|False
}
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
'ItemCollectionMetrics': {
'ItemCollectionKey': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'SizeEstimateRangeGB': [
123.0,
]
}
}
Response Structure
• (dict) –
Represents the output of a DeleteItem operation.
– Attributes (dict) –
A map of attribute names to AttributeValue objects, representing the item
as it appeared before the DeleteItem operation. This map appears in the
3.1. Services 811
Boto3 Documentation, Release 1.1.4
response only if ReturnValues was specified as ALL_OLD in the request.
* (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
812 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned includes
the total provisioned throughput consumed, along with statistics for the ta-
ble and any indexes involved in the operation. ConsumedCapacity is only
returned if the request asked for it. For more information, see Provisioned
Throughput in the Amazon DynamoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the operation.
* Table (dict) –
The amount of throughput consumed on the table affected by the
operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
– ItemCollectionMetrics (dict) –
Information about item collections, if any, that were affected by the oper-
ation. ItemCollectionMetrics is only returned if the request asked for it.
If the table does not have any local secondary indexes, this information is
not returned in the response.
Each ItemCollectionMetrics element consists of:
3.1. Services 813
Boto3 Documentation, Release 1.1.4
* ItemCollectionKey - The hash key value of the item collection. This
is the same as the hash key of the item.
* SizeEstimateRange - An estimate of item collection size, in giga-
bytes. This value is a two-element array containing a lower bound
and an upper bound for the estimate. The estimate includes the size
of all the items in the table, plus the size of all attributes projected
into all of the local secondary indexes on that table. Use this esti-
mate to measure whether a local secondary index is approaching its
size limit. The estimate is subject to change over time; therefore, do
not rely on the precision or accuracy of the estimate.
* ItemCollectionKey (dict) –
The hash key value of the item collection. This value is the same as
the hash key of the item.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
814 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
* SizeEstimateRangeGB (list) –
An estimate of item collection size, in gigabytes. This value is a
two-element array containing a lower bound and an upper bound
for the estimate. The estimate includes the size of all the items in
the table, plus the size of all attributes projected into all of the lo-
cal secondary indexes on that table. Use this estimate to measure
whether a local secondary index is approaching its size limit.
The estimate is subject to change over time; therefore, do not rely
on the precision or accuracy of the estimate.
· (float) –
delete_table(**kwargs)
The DeleteTable operation deletes a table and all of its items. After a DeleteTable request, the specified ta-
ble is in the DELETING state until DynamoDB completes the deletion. If the table is in the ACTIVE state,
you can delete it. If a table is in CREATING or UPDATING states, then DynamoDB returns a ResourceI-
nUseException . If the specified table does not exist, DynamoDB returns a ResourceNotFoundException
. If table is already in the DELETING state, no error is returned.
Note: DynamoDB might continue to accept data read and write operations, such as GetItem and PutItem
, on a table in the DELETING state until the table deletion is complete.
When you delete a table, any indexes on that table are also deleted.
If you have DynamoDB Streams enabled on the table, then the corresponding stream on that table goes
into the DISABLED state, and the stream is automatically deleted after 24 hours.
Use the DescribeTable API to check the status of the table.
Request Syntax
response = client.delete_table(
TableName='string'
)
Parameters TableName (string) – [REQUIRED]
The name of the table to delete.
3.1. Services 815
Boto3 Documentation, Release 1.1.4
Return type dict
Returns
Response Syntax
{
'TableDescription': {
'AttributeDefinitions': [
{
'AttributeName': 'string',
'AttributeType': 'S'|'N'|'B'
},
],
'TableName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'TableStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'CreationDateTime': datetime(2015, 1, 1),
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'TableSizeBytes': 123,
'ItemCount': 123,
'TableArn': 'string',
'LocalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
},
],
'GlobalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
816 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'Backfilling': True|False,
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
},
],
'StreamSpecification': {
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_O
},
'LatestStreamLabel': 'string',
'LatestStreamArn': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a DeleteTable operation.
– TableDescription (dict) –
Represents the properties of a table.
* AttributeDefinitions (list) –
An array of AttributeDefinition objects. Each of these objects de-
scribes one attribute in the table and index key schema.
Each AttributeDefinition object in this array is composed of:
· AttributeName - The name of the attribute.
· AttributeType - The data type for the attribute.
· (dict) –
Represents an attribute for describing the key schema for the
table and indexes.
· AttributeName (string) –
A name for the attribute.
· AttributeType (string) –
The data type for the attribute.
* TableName (string) –
The name of the table.
3.1. Services 817
Boto3 Documentation, Release 1.1.4
* KeySchema (list) –
The primary key structure for the table. Each KeySchemaElement
consists of:
· AttributeName - The name of the attribute.
· KeyType - The key type for the attribute. Can be either HASH
or RANGE .
For more information about primary keys, see Primary Key in the
Amazon DynamoDB Developer Guide .
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
* TableStatus (string) –
The current state of the table:
· CREATING - The table is being created.
· UPDATING - The table is being updated.
· DELETING - The table is being deleted.
· ACTIVE - The table is ready for use.
* CreationDateTime (datetime) –
The date and time when the table was created, in UNIX epoch time
format.
* ProvisionedThroughput (dict) –
The provisioned throughput settings for the table, consisting of read
and write capacity units, along with data about increases and de-
creases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput increase
for this table.
· LastDecreaseDateTime (datetime) –
The date and time of the last provisioned throughput decrease
for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for this ta-
ble during this UTC calendar day. For current maximums on
provisioned throughput decreases, see Limits in the Amazon
DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
818 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. Eventually consistent reads require less effort than strongly
consistent reads, so a setting of 50 ReadCapacityUnits per
second provides 100 eventually consistent ReadCapacityU-
nits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException .
* TableSizeBytes (integer) –
The total size of the specified table, in bytes. DynamoDB updates
this value approximately every six hours. Recent changes might not
be reflected in this value.
* ItemCount (integer) –
The number of items in the specified table. DynamoDB updates this
value approximately every six hours. Recent changes might not be
reflected in this value.
* TableArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies the ta-
ble.
* LocalSecondaryIndexes (list) –
Represents one or more local secondary indexes on the table. Each
index is scoped to a given hash key value. Tables with one or more
local secondary indexes are subject to an item collection size limit,
where the amount of data within a given item collection cannot ex-
ceed 10 GB. Each element is composed of:
· IndexName - The name of the local secondary index.
· KeySchema - Specifies the complete index key schema. The
attribute names in the key schema must be between 1 and 255
characters (inclusive). The key schema must begin with the
same hash key attribute as the table.
· Projection - Specifies attributes that are copied (projected)
from the table into the index. These are in addition to the pri-
mary key attributes and index key attributes, which are auto-
matically projected. Each attribute specification is composed
of: * ProjectionType - One of the following: * KEYS_ONLY -
Only the index and primary keys are projected into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes - A list of one or more non-key attribute
names that are projected into the secondary index. The total
count of attributes provided in NonKeyAttributes , summed
across all of the secondary indexes, must not exceed 20. If
you project the same attribute into two different indexes, this
counts as two distinct attributes when determining the total.
· IndexSizeBytes - Represents the total size of the index, in
bytes. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
· ItemCount - Represents the number of items in the index. Dy-
3.1. Services 819
Boto3 Documentation, Release 1.1.4
namoDB updates this value approximately every six hours.
Recent changes might not be reflected in this value.
If the table is in the DELETING state, no information about indexes
will be returned.
· (dict) –
Represents the properties of a local secondary index.
· IndexName (string) –
Represents the name of the local secondary index.
· KeySchema (list) –
The complete index key schema, which consists of one or
more pairs of attribute names and key types (HASH or RANGE
).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
820 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (string) –
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· ItemCount (integer) –
The number of items in the specified index. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the index.
* GlobalSecondaryIndexes (list) –
The global secondary indexes, if any, on the table. Each index is
scoped to a given hash key value. Each element is composed of:
· Backfilling - If true, then the index is currently in the back-
filling phase. Backfilling occurs only when a new global sec-
ondary index is added to the table; it is the process by which
DynamoDB populates the new index with data from the table.
(This attribute does not appear for indexes that were created
during a CreateTable operation.)
· IndexName - The name of the global secondary index.
· IndexSizeBytes - The total size of the global secondary index,
in bytes. DynamoDB updates this value approximately every
six hours. Recent changes might not be reflected in this value.
· IndexStatus - The current status of the global secondary index:
* CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· ItemCount - The number of items in the global secondary in-
dex. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
· KeySchema - Specifies the complete index key schema. The
attribute names in the key schema must be between 1 and 255
characters (inclusive). The key schema must begin with the
same hash key attribute as the table.
· Projection - Specifies attributes that are copied (projected)
from the table into the index. These are in addition to the pri-
mary key attributes and index key attributes, which are auto-
matically projected. Each attribute specification is composed
of: * ProjectionType - One of the following: * KEYS_ONLY -
Only the index and primary keys are projected into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes - A list of one or more non-key attribute
names that are projected into the secondary index. The total
count of attributes provided in NonKeyAttributes , summed
across all of the secondary indexes, must not exceed 20. If
you project the same attribute into two different indexes, this
3.1. Services 821
Boto3 Documentation, Release 1.1.4
counts as two distinct attributes when determining the total.
· ProvisionedThroughput - The provisioned throughput settings
for the global secondary index, consisting of read and write
capacity units, along with data about increases and decreases.
If the table is in the DELETING state, no information about indexes
will be returned.
· (dict) –
Represents the properties of a global secondary index.
· IndexName (string) –
The name of the global secondary index.
· KeySchema (list) –
The complete key schema for the global secondary index,
consisting of one or more pairs of attribute names and key
types (HASH or RANGE ).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
822 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
· IndexStatus (string) –
The current state of the global secondary index:
· CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· Backfilling (boolean) –
Indicates whether the index is currently backfilling. Backfill-
ing is the process of reading items from the table and deter-
mining whether they can be added to the index. (Not all items
will qualify: For example, a hash key attribute cannot have
any duplicates.) If an item can be added to the index, Dy-
namoDB will do so. After all items have been processed, the
backfilling operation is complete and Backfilling is false.
Note: For indexes that were created during a CreateTable
operation, the Backfilling attribute does not appear in the De-
scribeTable output.
· ProvisionedThroughput (dict) –
Represents the provisioned throughput settings for the table,
consisting of read and write capacity units, along with data
about increases and decreases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput increase
for this table.
· LastDecreaseDateTime (datetime) –
The date and time of the last provisioned throughput decrease
for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for this ta-
ble during this UTC calendar day. For current maximums on
provisioned throughput decreases, see Limits in the Amazon
DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. Eventually consistent reads require less effort than strongly
consistent reads, so a setting of 50 ReadCapacityUnits per
second provides 100 eventually consistent ReadCapacityU-
nits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException .
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. DynamoDB
updates this value approximately every six hours. Recent
3.1. Services 823
Boto3 Documentation, Release 1.1.4
changes might not be reflected in this value.
· ItemCount (integer) –
The number of items in the specified index. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the index.
* StreamSpecification (dict) –
The current DynamoDB Streams configuration for the table.
· StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled (true) or
disabled (false) on the table.
· StreamViewType (string) –
The DynamoDB Streams settings for the table. These settings
consist of:
· StreamEnabled - Indicates whether DynamoDB Streams is
enabled (true) or disabled (false) on the table.
· StreamViewType - When an item in the table is modified,
StreamViewType determines what information is written to the
stream for this table. Valid values for StreamViewType are: *
KEYS_ONLY - Only the key attributes of the modified item
are written to the stream.
· NEW_IMAGE - The entire item, as it appears after it was
modified, is written to the stream.
· OLD_IMAGE - The entire item, as it appeared before it was
modified, is written to the stream.
· NEW_AND_OLD_IMAGES - Both the new and the old item
images of the item are written to the stream.
* LatestStreamLabel (string) –
A timestamp, in ISO 8601 format, for this stream.
Note that LatestStreamLabel is not a unique identifier for the stream,
because it is possible that a stream from another table might have the
same timestamp. However, the combination of the following three
elements is guaranteed to be unique:
· the AWS customer ID.
· the table name.
· the StreamLabel .
* LatestStreamArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies the lat-
est stream for this table.
describe_table(**kwargs)
Returns information about the table, including the current status of the table, when it was created, the
primary key schema, and any indexes on the table.
Note: If you issue a DescribeTable request immediately after a CreateTable request, DynamoDB might
return a ResourceNotFoundException. This is because DescribeTable uses an eventually consistent query,
and the metadata for your table might not be available at that moment. Wait for a few seconds, and then
try the DescribeTable request again.
824 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.describe_table(
TableName='string'
)
Parameters TableName (string) – [REQUIRED]
The name of the table to describe.
Return type dict
Returns
Response Syntax
{
'Table': {
'AttributeDefinitions': [
{
'AttributeName': 'string',
'AttributeType': 'S'|'N'|'B'
},
],
'TableName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'TableStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'CreationDateTime': datetime(2015, 1, 1),
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'TableSizeBytes': 123,
'ItemCount': 123,
'TableArn': 'string',
'LocalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
3.1. Services 825
Boto3 Documentation, Release 1.1.4
},
],
'GlobalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'Backfilling': True|False,
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
},
],
'StreamSpecification': {
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_O
},
'LatestStreamLabel': 'string',
'LatestStreamArn': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a DescribeTable operation.
– Table (dict) –
Represents the properties of a table.
* AttributeDefinitions (list) –
An array of AttributeDefinition objects. Each of these objects de-
scribes one attribute in the table and index key schema.
Each AttributeDefinition object in this array is composed of:
· AttributeName - The name of the attribute.
· AttributeType - The data type for the attribute.
· (dict) –
Represents an attribute for describing the key schema for the
table and indexes.
826 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· AttributeName (string) –
A name for the attribute.
· AttributeType (string) –
The data type for the attribute.
* TableName (string) –
The name of the table.
* KeySchema (list) –
The primary key structure for the table. Each KeySchemaElement
consists of:
· AttributeName - The name of the attribute.
· KeyType - The key type for the attribute. Can be either HASH
or RANGE .
For more information about primary keys, see Primary Key in the
Amazon DynamoDB Developer Guide .
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
* TableStatus (string) –
The current state of the table:
· CREATING - The table is being created.
· UPDATING - The table is being updated.
· DELETING - The table is being deleted.
· ACTIVE - The table is ready for use.
* CreationDateTime (datetime) –
The date and time when the table was created, in UNIX epoch time
format.
* ProvisionedThroughput (dict) –
The provisioned throughput settings for the table, consisting of read
and write capacity units, along with data about increases and de-
creases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput increase
for this table.
· LastDecreaseDateTime (datetime) –
3.1. Services 827
Boto3 Documentation, Release 1.1.4
The date and time of the last provisioned throughput decrease
for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for this ta-
ble during this UTC calendar day. For current maximums on
provisioned throughput decreases, see Limits in the Amazon
DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. Eventually consistent reads require less effort than strongly
consistent reads, so a setting of 50 ReadCapacityUnits per
second provides 100 eventually consistent ReadCapacityU-
nits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException .
* TableSizeBytes (integer) –
The total size of the specified table, in bytes. DynamoDB updates
this value approximately every six hours. Recent changes might not
be reflected in this value.
* ItemCount (integer) –
The number of items in the specified table. DynamoDB updates this
value approximately every six hours. Recent changes might not be
reflected in this value.
* TableArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies the ta-
ble.
* LocalSecondaryIndexes (list) –
Represents one or more local secondary indexes on the table. Each
index is scoped to a given hash key value. Tables with one or more
local secondary indexes are subject to an item collection size limit,
where the amount of data within a given item collection cannot ex-
ceed 10 GB. Each element is composed of:
· IndexName - The name of the local secondary index.
· KeySchema - Specifies the complete index key schema. The
attribute names in the key schema must be between 1 and 255
characters (inclusive). The key schema must begin with the
same hash key attribute as the table.
· Projection - Specifies attributes that are copied (projected)
from the table into the index. These are in addition to the pri-
mary key attributes and index key attributes, which are auto-
matically projected. Each attribute specification is composed
of: * ProjectionType - One of the following: * KEYS_ONLY -
Only the index and primary keys are projected into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes - A list of one or more non-key attribute
828 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
names that are projected into the secondary index. The total
count of attributes provided in NonKeyAttributes , summed
across all of the secondary indexes, must not exceed 20. If
you project the same attribute into two different indexes, this
counts as two distinct attributes when determining the total.
· IndexSizeBytes - Represents the total size of the index, in
bytes. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
· ItemCount - Represents the number of items in the index. Dy-
namoDB updates this value approximately every six hours.
Recent changes might not be reflected in this value.
If the table is in the DELETING state, no information about indexes
will be returned.
· (dict) –
Represents the properties of a local secondary index.
· IndexName (string) –
Represents the name of the local secondary index.
· KeySchema (list) –
The complete index key schema, which consists of one or
more pairs of attribute names and key types (HASH or RANGE
).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
3.1. Services 829
Boto3 Documentation, Release 1.1.4
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· ItemCount (integer) –
The number of items in the specified index. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the index.
* GlobalSecondaryIndexes (list) –
The global secondary indexes, if any, on the table. Each index is
scoped to a given hash key value. Each element is composed of:
· Backfilling - If true, then the index is currently in the back-
filling phase. Backfilling occurs only when a new global sec-
ondary index is added to the table; it is the process by which
DynamoDB populates the new index with data from the table.
(This attribute does not appear for indexes that were created
during a CreateTable operation.)
· IndexName - The name of the global secondary index.
· IndexSizeBytes - The total size of the global secondary index,
in bytes. DynamoDB updates this value approximately every
six hours. Recent changes might not be reflected in this value.
· IndexStatus - The current status of the global secondary index:
* CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· ItemCount - The number of items in the global secondary in-
dex. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
· KeySchema - Specifies the complete index key schema. The
attribute names in the key schema must be between 1 and 255
characters (inclusive). The key schema must begin with the
same hash key attribute as the table.
· Projection - Specifies attributes that are copied (projected)
from the table into the index. These are in addition to the pri-
mary key attributes and index key attributes, which are auto-
matically projected. Each attribute specification is composed
of: * ProjectionType - One of the following: * KEYS_ONLY -
Only the index and primary keys are projected into the index.
830 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes - A list of one or more non-key attribute
names that are projected into the secondary index. The total
count of attributes provided in NonKeyAttributes , summed
across all of the secondary indexes, must not exceed 20. If
you project the same attribute into two different indexes, this
counts as two distinct attributes when determining the total.
· ProvisionedThroughput - The provisioned throughput settings
for the global secondary index, consisting of read and write
capacity units, along with data about increases and decreases.
If the table is in the DELETING state, no information about indexes
will be returned.
· (dict) –
Represents the properties of a global secondary index.
· IndexName (string) –
The name of the global secondary index.
· KeySchema (list) –
The complete key schema for the global secondary index,
consisting of one or more pairs of attribute names and key
types (HASH or RANGE ).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
3.1. Services 831
Boto3 Documentation, Release 1.1.4
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
· IndexStatus (string) –
The current state of the global secondary index:
· CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· Backfilling (boolean) –
Indicates whether the index is currently backfilling. Backfill-
ing is the process of reading items from the table and deter-
mining whether they can be added to the index. (Not all items
will qualify: For example, a hash key attribute cannot have
any duplicates.) If an item can be added to the index, Dy-
namoDB will do so. After all items have been processed, the
backfilling operation is complete and Backfilling is false.
Note: For indexes that were created during a CreateTable
operation, the Backfilling attribute does not appear in the De-
scribeTable output.
· ProvisionedThroughput (dict) –
Represents the provisioned throughput settings for the table,
consisting of read and write capacity units, along with data
about increases and decreases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput increase
for this table.
· LastDecreaseDateTime (datetime) –
The date and time of the last provisioned throughput decrease
for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for this ta-
ble during this UTC calendar day. For current maximums on
provisioned throughput decreases, see Limits in the Amazon
DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. Eventually consistent reads require less effort than strongly
consistent reads, so a setting of 50 ReadCapacityUnits per
832 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
second provides 100 eventually consistent ReadCapacityU-
nits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException .
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· ItemCount (integer) –
The number of items in the specified index. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the index.
* StreamSpecification (dict) –
The current DynamoDB Streams configuration for the table.
· StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled (true) or
disabled (false) on the table.
· StreamViewType (string) –
The DynamoDB Streams settings for the table. These settings
consist of:
· StreamEnabled - Indicates whether DynamoDB Streams is
enabled (true) or disabled (false) on the table.
· StreamViewType - When an item in the table is modified,
StreamViewType determines what information is written to the
stream for this table. Valid values for StreamViewType are: *
KEYS_ONLY - Only the key attributes of the modified item
are written to the stream.
· NEW_IMAGE - The entire item, as it appears after it was
modified, is written to the stream.
· OLD_IMAGE - The entire item, as it appeared before it was
modified, is written to the stream.
· NEW_AND_OLD_IMAGES - Both the new and the old item
images of the item are written to the stream.
* LatestStreamLabel (string) –
A timestamp, in ISO 8601 format, for this stream.
Note that LatestStreamLabel is not a unique identifier for the stream,
because it is possible that a stream from another table might have the
same timestamp. However, the combination of the following three
elements is guaranteed to be unique:
· the AWS customer ID.
· the table name.
· the StreamLabel .
* LatestStreamArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies the lat-
est stream for this table.
3.1. Services 833
Boto3 Documentation, Release 1.1.4
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_item(**kwargs)
The GetItem operation returns a set of attributes for the item with the given primary key. If there is no
matching item, GetItem does not return any data.
GetItem provides an eventually consistent read by default. If your application requires a strongly consis-
tent read, set ConsistentRead to true . Although a strongly consistent read might take more time than
an eventually consistent read, it always returns the last updated value.
Request Syntax
response = client.get_item(
TableName='string',
Key={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
AttributesToGet=[
'string',
],
ConsistentRead=True|False,
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ProjectionExpression='string',
ExpressionAttributeNames={
'string': 'string'
}
)
834 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• TableName (string) – [REQUIRED]
The name of the table containing the requested item.
• Key (dict) – [REQUIRED]
A map of attribute names to AttributeValue objects, representing the primary key
of the item to retrieve.
For the primary key, you must provide all of the attributes. For example, with a
hash type primary key, you only need to provide the hash attribute. For a hash-
and-range type primary key, you must provide both the hash attribute and the
range attribute.
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
3.1. Services 835
Boto3 Documentation, Release 1.1.4
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Warning: This is a legacy parameter, for backward compatibility. New a
plications should use ProjectionExpression instead. Do not combine lega
parameters and expression parameters in a single API call; otherwise, D
• AttributesToGet (list) –
namoDB will return a ValidationException exception.
This parameter allows you to retrieve attributes of type List or Map; howev
it cannot retrieve individual elements within a List or a Map.
The names of one or more attributes to retrieve. If no attribute names are pro-
vided, then all attributes will be returned. If any of the requested attributes are
not found, they will not appear in the result.
Note that AttributesToGet has no effect on provisioned throughput consumption.
DynamoDB determines capacity units consumed based on item size, not on the
amount of data that is returned to an application.
– (string) –
• ConsistentRead (boolean) – Determines the read consistency model: If set to
true , then the operation uses strongly consistent reads; otherwise, the opera-
tion uses eventually consistent reads.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ProjectionExpression (string) – A string that identifies one or more attributes to
retrieve from the table. These attributes can include scalars, sets, or elements of a
JSON document. The attributes in the expression must be separated by commas.
If no attribute names are specified, then all attributes will be returned. If any of
the requested attributes are not found, they will not appear in the result.
For more information, see Accessing Item Attributes in the Amazon DynamoDB
Developer Guide .
Note: ProjectionExpression replaces the legacy AttributesToGet parameter.
836 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• ExpressionAttributeNames (dict) – One or more substitution tokens for at-
tribute names in an expression. The following are some use cases for using
ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB reserved
word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
Return type dict
Returns
Response Syntax
{
'Item': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
3.1. Services 837
Boto3 Documentation, Release 1.1.4
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
}
}
Response Structure
• (dict) –
Represents the output of a GetItem operation.
– Item (dict) –
A map of attribute names to AttributeValue objects, as specified by At-
tributesToGet .
* (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
838 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned includes
the total provisioned throughput consumed, along with statistics for the ta-
ble and any indexes involved in the operation. ConsumedCapacity is only
returned if the request asked for it. For more information, see Provisioned
Throughput in the Amazon DynamoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the operation.
* Table (dict) –
The amount of throughput consumed on the table affected by the
operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index affected
by the operation.
· (string) –
· (dict) –
3.1. Services 839
Boto3 Documentation, Release 1.1.4
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_waiter(waiter_name)
list_tables(**kwargs)
Returns an array of table names associated with the current account and endpoint. The output from
ListTables is paginated, with each page returning a maximum of 100 table names.
Request Syntax
response = client.list_tables(
ExclusiveStartTableName='string',
Limit=123
)
Parameters
• ExclusiveStartTableName (string) – The first table name that this operation
will evaluate. Use the value that was returned for LastEvaluatedTableName in a
previous operation, so that you can obtain the next page of results.
• Limit (integer) – A maximum number of table names to return. If this parameter
is not specified, the limit is 100.
Return type dict
Returns
Response Syntax
{
'TableNames': [
'string',
840 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'LastEvaluatedTableName': 'string'
}
Response Structure
• (dict) –
Represents the output of a ListTables operation.
– TableNames (list) –
The names of the tables associated with the current account at the current
endpoint. The maximum size of this array is 100.
If LastEvaluatedTableName also appears in the output, you can use this
value as the ExclusiveStartTableName parameter in a subsequent ListTa-
bles request and obtain the next page of results.
* (string) –
– LastEvaluatedTableName (string) –
The name of the last table in the current page of results. Use this value as
the ExclusiveStartTableName in a new request to obtain the next page of
results, until all the table names are returned.
If you do not receive a LastEvaluatedTableName value in the response,
this means that there are no more table names to be retrieved.
put_item(**kwargs)
Creates a new item, or replaces an old item with a new item. If an item that has the same primary key
as the new item already exists in the specified table, the new item completely replaces the existing item.
You can perform a conditional put operation (add a new item if one with the specified primary key doesn’t
exist), or replace an existing item if it has certain attribute values.
In addition to putting an item, you can also return the item’s attribute values in the same operation, using
the ReturnValues parameter.
When you add an item, the primary key attribute(s) are the only required attributes. Attribute values
cannot be null. String and Binary type attributes must have lengths greater than zero. Set type attributes
cannot be empty. Requests with empty values will be rejected with a ValidationException exception.
You can request that PutItem return either a copy of the original item (before the update) or a copy of the
updated item (after the update). For more information, see the ReturnValues description below.
Note: To prevent a new item from replacing an existing item, use a conditional put operation with
ComparisonOperator set to NULL for the primary key attribute, or attributes.
For more information about using this API, see Working with Items in the Amazon DynamoDB Developer
Guide .
Request Syntax
response = client.put_item(
TableName='string',
Item={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
3.1. Services 841
Boto3 Documentation, Release 1.1.4
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
Expected={
'string': {
'Value': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
'Exists': True|False,
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
842 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
]
}
},
ReturnValues='NONE'|'ALL_OLD'|'UPDATED_OLD'|'ALL_NEW'|'UPDATED_NEW',
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ReturnItemCollectionMetrics='SIZE'|'NONE',
ConditionalOperator='AND'|'OR',
ConditionExpression='string',
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
}
)
Parameters
• TableName (string) – [REQUIRED]
The name of the table to contain the item.
• Item (dict) – [REQUIRED]
A map of attribute name/value pairs, one for each attribute. Only the primary
key attributes are required; you can optionally provide other attribute name-value
pairs for the item.
You must provide all of the attributes for the primary key. For example, with a
hash type primary key, you only need to provide the hash attribute. For a hash-
and-range type primary key, you must provide both the hash attribute and the
range attribute.
3.1. Services 843
Boto3 Documentation, Release 1.1.4
If you specify any attributes that are part of an index key, then the data types for
those attributes must match those of the schema in the table’s attribute definition.
For more information about primary keys, see Primary Key in the Amazon Dy-
namoDB Developer Guide .
Each element in the Item map is an AttributeValue object.
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
844 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Warning: This is a legacy parameter, for backward compatibility. New ap-
plications should use ConditionExpression instead. Do not combine legacy
• Expected (dict) –
parameters and expression parameters in a single API call; otherwise, Dy-
namoDB will return a ValidationException exception.
A map of attribute/condition pairs. Expected provides a conditional block for the
PutItem operation.
Note: This parameter does not support attributes of type List or Map.
Each element of Expected consists of an attribute name, a comparison operator,
and one or more values. DynamoDB compares the attribute with the value(s)
you supplied, using the comparison operator. For each Expected element, the
result of the evaluation is either true or false.
If you specify more than one element in the Expected map, then by default all of
the conditions must evaluate to true. In other words, the conditions are ANDed
together. (You can use the ConditionalOperator parameter to OR the conditions
instead. If you do this, then at least one of the conditions must evaluate to true,
rather than all of them.)
If the Expected map evaluates to true, then the conditional operation succeeds;
otherwise, it fails.
Expected contains the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the Com-
parisonOperator being used. For type Number, value comparisons are
numeric. String value comparisons for greater than, equals, or less
than are based on ASCII character code values. For example, a is
greater than A , and a is greater than B . For a list of code values,
see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters . For
type Binary, DynamoDB treats each byte of the binary data as unsigned
when it compares binary values.
– ComparisonOperator - A comparator for evaluating attributes in the
AttributeValueList . When performing the comparison, DynamoDB
uses strongly consistent reads. The following comparison operators
are available: EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH |
IN | BETWEEN The following are descriptions of each comparison
operator. * EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one AttributeValue element
of type String, Number, Binary, String Set, Number Set, or Binary Set.
If an item contains an AttributeValue element of a different type than
3.1. Services 845
Boto3 Documentation, Release 1.1.4
the one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
– NE : Not equal. NE is supported for all datatypes, including lists and
maps. AttributeValueList can contain only one AttributeValue of type
String, Number, Binary, String Set, Number Set, or Binary Set. If an item
contains an AttributeValue of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not equal {"NS":["6",
"2", "1"]} .
– LE : Less than or equal. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– LT : Less than. AttributeValueList can contain only one AttributeValue of
type String, Number, or Binary (not a set type). If an item contains an
AttributeValue element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type than
the one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
– GT : Greater than. AttributeValueList can contain only one AttributeValue
element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– NOT_NULL : The attribute exists. NOT_NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for the
existence of an attribute, not its data type. If the data type of attribute “a ”
is null, and you evaluate it using NOT_NULL , the result is a Boolean true
. This result is because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
– NULL : The attribute does not exist. NULL is supported for all datatypes,
including lists and maps. .. note::This operator tests for the nonexistence
of an attribute, not its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean false . This is
because the attribute “a ” exists; its data type is not relevant to the NULL
comparison operator.
– CONTAINS : Checks for a subsequence, or value in a set. AttributeVal-
ueList can contain only one AttributeValue element of type String, Num-
ber, or Binary (not a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring match. If the target
attribute of the comparison is of type Binary, then the operator looks for
a subsequence of the target that matches the input. If the target attribute
of the comparison is a set (“SS ”, “NS ”, or “BS ”), then the operator
evaluates to true if it finds an exact match with any member of the set.
846 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
CONTAINS is supported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a list.
– NOT_CONTAINS : Checks for absence of a subsequence, or absence of
a value in a set. AttributeValueList can contain only one AttributeValue
element of type String, Number, or Binary (not a set type). If the target
attribute of the comparison is a String, then the operator checks for the
absence of a substring match. If the target attribute of the comparison is
Binary, then the operator checks for the absence of a subsequence of the
target that matches the input. If the target attribute of the comparison is a
set (“SS ”, “NS ”, or “BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set. NOT_CONTAINS is
supported for lists: When evaluating “a NOT CONTAINS b ”, “a ” can
be a list; however, “b ” cannot be a set, a map, or a list.
– BEGINS_WITH : Checks for a prefix. AttributeValueList can contain only
one AttributeValue of type String or Binary (not a Number or a set type).
The target attribute of the comparison must be of type String or Binary
(not a Number or a set type).
– IN : Checks for matching elements within two sets. AttributeValueList can
contain one or more AttributeValue elements of type String, Number, or
Binary (not a set type). These attributes are compared against an existing
set type attribute of an item. If any elements of the input set are present in
the item attribute, the expression evaluates to true.
– BETWEEN : Greater than or equal to the first value, and less than or equal
to the second value. AttributeValueList must contain two AttributeValue el-
ements of the same type, either String, Number, or Binary (not a set type).
A target attribute matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If an item con-
tains an AttributeValue element of a different type than the one provided
in the request, the value does not match. For example, {"S":"6"} does
not compare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see Legacy
Conditional Parameters in the Amazon DynamoDB Developer Guide .
For backward compatibility with previous DynamoDB releases, the following
parameters can be used instead of AttributeValueList and ComparisonOperator :
– Value - A value for DynamoDB to compare with an attribute.
– Exists - A Boolean value that causes DynamoDB to evaluate the value
before attempting the conditional operation: * If Exists is true , Dy-
namoDB will check to see if that attribute value already exists in the table.
If it is found, then the condition evaluates to true; otherwise the condition
evaluate to false.
– If Exists is false , DynamoDB assumes that the attribute value does not
exist in the table. If in fact the value does not exist, then the assumption is
valid and the condition evaluates to true. If the value is found, despite the
assumption that it does not exist, the condition evaluates to false.
Note that the default value for Exists is true .
The Value and Exists parameters are incompatible with AttributeValueList and
ComparisonOperator . Note that if you use both sets of parameters at once,
DynamoDB will return a ValidationException exception.
– (string) –
* (dict) –
Represents a condition to be compared with an attribute value. This
3.1. Services 847
Boto3 Documentation, Release 1.1.4
condition can be used with DeleteItem , PutItem or UpdateItem op-
erations; if the comparison evaluates to true, the operation succeeds;
if not, the operation fails. You can use ExpectedAttributeValue in
one of two different ways:
· Use AttributeValueList to specify one or more values to com-
pare against an attribute. Use ComparisonOperator to specify
how you want to perform the comparison. If the comparison
evaluates to true, then the conditional operation succeeds.
· Use Value to specify a value that DynamoDB will compare
against an attribute. If the values match, then ExpectedAt-
tributeValue evaluates to true and the conditional operation
succeeds. Optionally, you can also set Exists to false, indi-
cating that you do not expect to find the attribute value in the
table. In this case, the conditional operation succeeds only if
the comparison evaluates to false.
Value and Exists are incompatible with AttributeValueList and Com-
parisonOperator . Note that if you use both sets of parameters at
once, DynamoDB will return a ValidationException exception.
· Value (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
848 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· Exists (boolean) –
Causes DynamoDB to evaluate the value before attempting a
conditional operation:
· If Exists is true , DynamoDB will check to see if that at-
tribute value already exists in the table. If it is found, then the
operation succeeds. If it is not found, the operation fails with
a ConditionalCheckFailedException .
· If Exists is false , DynamoDB assumes that the attribute
value does not exist in the table. If in fact the value does not
exist, then the assumption is valid and the operation succeeds.
If the value is found, despite the assumption that it does not
exist, the operation fails with a ConditionalCheckFailedEx-
ception .
The default setting for Exists is true . If you supply a Value
all by itself, DynamoDB assumes the attribute exists: You
don’t have to set Exists to true , because it is implied.
DynamoDB returns a ValidationException if:
· Exists is true but there is no Value to check. (You expect a
value to exist, but don’t specify what that value is.)
· Exists is false but you also provide a Value . (You cannot
expect an attribute to have a value, while also expecting it not
to exist.)
· ComparisonOperator (string) –
A comparator for evaluating attributes in the AttributeVal-
ueList . For example, equals, greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
3.1. Services 849
Boto3 Documentation, Release 1.1.4
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
850 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
3.1. Services 851
Boto3 Documentation, Release 1.1.4
The number of values in the list depends on the Comparison-
Operator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
For information on specifying data types in JSON, see JSON
Data Format in the Amazon DynamoDB Developer Guide .
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
852 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
• ReturnValues (string) – Use ReturnValues if you want to get the item attributes
as they appeared before they were updated with the PutItem request. For PutItem
, the valid values are:
– NONE - If ReturnValues is not specified, or if its value is NONE , then
nothing is returned. (This setting is the default for ReturnValues .)
– ALL_OLD - If PutItem overwrote an attribute name-value pair, then the
content of the old item is returned.
Note: Other “Valid Values” are not relevant to PutItem.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ReturnItemCollectionMetrics (string) – Determines whether item collection
metrics are returned. If set to SIZE , the response includes statistics about item
collections, if any, that were modified during the operation are returned in the
response. If set to NONE (the default), no statistics are returned.
Warning: This is a legacy parameter, for backward compatibility
plications should use ConditionExpression instead. Do not comb
• ConditionalOperator (string) –
parameters and expression parameters in a single API call; other
namoDB will return a ValidationException exception.
A logical operator to apply to the conditions in the Expected map:
– AND - If all of the conditions evaluate to true, then the entire map evaluates
to true.
– OR - If at least one of the conditions evaluate to true, then the entire map
evaluates to true.
3.1. Services 853
Boto3 Documentation, Release 1.1.4
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ConditionExpression (string) – A condition that must be satisfied in order for a
conditional PutItem operation to succeed.
An expression can contain any of the following:
– Functions: attribute_exists | attribute_not_exists
| attribute_type | contains | begins_with | size
These function names are case-sensitive.
– Comparison operators: = | | | | = | = | BETWEEN | IN
– Logical operators: AND | OR | NOT
For more information on condition expressions, see Specifying Conditions in the
Amazon DynamoDB Developer Guide .
Note: ConditionExpression replaces the legacy ConditionalOperator and Ex-
pected parameters.
• ExpressionAttributeNames (dict) – One or more substitution tokens for at-
tribute names in an expression. The following are some use cases for using
ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB reserved
word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be substituted
in an expression.
Use the : (colon) character in an expression to dereference an attribute value.
For example, suppose that you wanted to check whether the value of the Prod-
uctStatus attribute was one of the following:
Available | Backordered | Discontinued
854 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Conditions
in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
3.1. Services 855
Boto3 Documentation, Release 1.1.4
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Return type dict
Returns
Response Syntax
{
'Attributes': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
856 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
}
},
'ItemCollectionMetrics': {
'ItemCollectionKey': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'SizeEstimateRangeGB': [
123.0,
]
}
}
Response Structure
• (dict) –
Represents the output of a PutItem operation.
– Attributes (dict) –
The attribute values as they appeared before the PutItem operation, but
only if ReturnValues is specified as ALL_OLD in the request. Each element
consists of an attribute name and an attribute value.
* (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
3.1. Services 857
Boto3 Documentation, Release 1.1.4
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned includes
the total provisioned throughput consumed, along with statistics for the ta-
ble and any indexes involved in the operation. ConsumedCapacity is only
returned if the request asked for it. For more information, see Provisioned
Throughput in the Amazon DynamoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the operation.
858 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Table (dict) –
The amount of throughput consumed on the table affected by the
operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
– ItemCollectionMetrics (dict) –
Information about item collections, if any, that were affected by the oper-
ation. ItemCollectionMetrics is only returned if the request asked for it.
If the table does not have any local secondary indexes, this information is
not returned in the response.
Each ItemCollectionMetrics element consists of:
* ItemCollectionKey - The hash key value of the item collection. This
is the same as the hash key of the item.
* SizeEstimateRange - An estimate of item collection size, in giga-
bytes. This value is a two-element array containing a lower bound
and an upper bound for the estimate. The estimate includes the size
of all the items in the table, plus the size of all attributes projected
into all of the local secondary indexes on that table. Use this esti-
mate to measure whether a local secondary index is approaching its
size limit. The estimate is subject to change over time; therefore, do
not rely on the precision or accuracy of the estimate.
* ItemCollectionKey (dict) –
The hash key value of the item collection. This value is the same as
the hash key of the item.
· (string) –
· (dict) –
3.1. Services 859
Boto3 Documentation, Release 1.1.4
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
860 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A Boolean data type.
* SizeEstimateRangeGB (list) –
An estimate of item collection size, in gigabytes. This value is a
two-element array containing a lower bound and an upper bound
for the estimate. The estimate includes the size of all the items in
the table, plus the size of all attributes projected into all of the lo-
cal secondary indexes on that table. Use this estimate to measure
whether a local secondary index is approaching its size limit.
The estimate is subject to change over time; therefore, do not rely
on the precision or accuracy of the estimate.
· (float) –
query(**kwargs)
A Query operation uses the primary key of a table or a secondary index to directly access items from that
table or index.
Use the KeyConditionExpression parameter to provide a specific hash key value. The Query operation
will return all of the items from the table or index with that hash key value. You can optionally narrow
the scope of the Query operation by specifying a range key value and a comparison operator in KeyCondi-
tionExpression . You can use the ScanIndexForward parameter to get results in forward or reverse order,
by range key or by index key.
Queries that do not return results consume the minimum number of read capacity units for that type of
read operation.
If the total number of items meeting the query criteria exceeds the result set size limit of 1 MB, the query
stops and results are returned to the user with the LastEvaluatedKey element to continue the query in a
subsequent operation. Unlike a Scan operation, a Query operation never returns both an empty result set
and a LastEvaluatedKey value. LastEvaluatedKey is only provided if the results exceed 1 MB, or if you
have used the Limit parameter.
You can query a table, a local secondary index, or a global secondary index. For a query on a table or
on a local secondary index, you can set the ConsistentRead parameter to true and obtain a strongly
consistent result. Global secondary indexes support eventually consistent reads only, so do not specify
ConsistentRead when querying a global secondary index.
Request Syntax
response = client.query(
TableName='string',
IndexName='string',
Select='ALL_ATTRIBUTES'|'ALL_PROJECTED_ATTRIBUTES'|'SPECIFIC_ATTRIBUTES'|'COUNT',
AttributesToGet=[
'string',
],
Limit=123,
ConsistentRead=True|False,
KeyConditions={
'string': {
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
3.1. Services 861
Boto3 Documentation, Release 1.1.4
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
}
},
QueryFilter={
'string': {
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
}
},
ConditionalOperator='AND'|'OR',
ScanIndexForward=True|False,
ExclusiveStartKey={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
862 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ProjectionExpression='string',
FilterExpression='string',
KeyConditionExpression='string',
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
}
)
Parameters
• TableName (string) – [REQUIRED]
The name of the table containing the requested items.
• IndexName (string) – The name of an index to query. This index can be any
local secondary index or global secondary index on the table. Note that if you
use the IndexName parameter, you must also provide TableName.
• Select (string) – The attributes to be returned in the result. You can retrieve all
item attributes, specific item attributes, the count of matching items, or in the
3.1. Services 863
Boto3 Documentation, Release 1.1.4
case of an index, some or all of the attributes projected into the index.
– ALL_ATTRIBUTES - Returns all of the item attributes from the specified
table or index. If you query a local secondary index, then for each match-
ing item in the index DynamoDB will fetch the entire item from the parent
table. If the index is configured to project all item attributes, then all of
the data can be obtained from the local secondary index, and no fetching
is required.
– ALL_PROJECTED_ATTRIBUTES - Allowed only when querying an in-
dex. Retrieves all attributes that have been projected into the index. If the
index is configured to project all attributes, this return value is equivalent
to specifying ALL_ATTRIBUTES .
– COUNT - Returns the number of matching items, rather than the matching
items themselves.
– SPECIFIC_ATTRIBUTES - Returns only the attributes listed in At-
tributesToGet . This return value is equivalent to specifying AttributesTo-
Get without specifying any value for Select . If you query a local sec-
ondary index and request only attributes that are projected into that index,
the operation will read only the index and not the table. If any of the
requested attributes are not projected into the local secondary index, Dy-
namoDB will fetch each of these attributes from the parent table. This
extra fetching incurs additional throughput cost and latency. If you query
a global secondary index, you can only request attributes that are projected
into the index. Global secondary index queries cannot fetch attributes from
the parent table.
If neither Select nor AttributesToGet are specified, DynamoDB
defaults to ALL_ATTRIBUTES when accessing a table, and
ALL_PROJECTED_ATTRIBUTES when accessing an index. You cannot
use both Select and AttributesToGet together in a single request, unless the
value for Select is SPECIFIC_ATTRIBUTES . (This usage is equivalent to
specifying AttributesToGet without any value for Select .)
Note: If you use the ProjectionExpression parameter, then the value for Select
can only be SPECIFIC_ATTRIBUTES . Any other value for Select will return
an error.
Warning: This is a legacy parameter, for backward compatibility. New a
plications should use ProjectionExpression instead. Do not combine lega
parameters and expression parameters in a single API call; otherwise, D
• AttributesToGet (list) –
namoDB will return a ValidationException exception.
This parameter allows you to retrieve attributes of type List or Map; howev
it cannot retrieve individual elements within a List or a Map.
The names of one or more attributes to retrieve. If no attribute names are pro-
vided, then all attributes will be returned. If any of the requested attributes are
not found, they will not appear in the result.
Note that AttributesToGet has no effect on provisioned throughput consumption.
DynamoDB determines capacity units consumed based on item size, not on the
amount of data that is returned to an application.
You cannot use both AttributesToGet and Select together in a Query request,
unless the value for Select is SPECIFIC_ATTRIBUTES . (This usage is equiv-
alent to specifying AttributesToGet without any value for Select .)
If you query a local secondary index and request only attributes that are pro-
864 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
jected into that index, the operation will read only the index and not the table. If
any of the requested attributes are not projected into the local secondary index,
DynamoDB will fetch each of these attributes from the parent table. This extra
fetching incurs additional throughput cost and latency.
If you query a global secondary index, you can only request attributes that are
projected into the index. Global secondary index queries cannot fetch attributes
from the parent table.
– (string) –
• Limit (integer) – The maximum number of items to evaluate (not necessarily
the number of matching items). If DynamoDB processes the number of items
up to the limit while processing the results, it stops the operation and returns the
matching values up to that point, and a key in LastEvaluatedKey to apply in a
subsequent operation, so that you can pick up where you left off. Also, if the
processed data set size exceeds 1 MB before DynamoDB reaches this limit, it
stops the operation and returns the matching values up to the limit, and a key in
LastEvaluatedKey to apply in a subsequent operation to continue the operation.
For more information, see Query and Scan in the Amazon DynamoDB Developer
Guide .
• ConsistentRead (boolean) – Determines the read consistency model: If set to
true , then the operation uses strongly consistent reads; otherwise, the opera-
tion uses eventually consistent reads.
Strongly consistent reads are not supported on global secondary indexes. If you
query a global secondary index with ConsistentRead set to true , you will
receive a ValidationException .
Warning: This is a legacy parameter, for backward compatibility. New
applications should use KeyConditionExpression instead. Do not combin
• KeyConditions (dict) –
legacy parameters and expression parameters in a single API call; otherwis
DynamoDB will return a ValidationException exception.
The selection criteria for the query. For a query on a table, you can have con-
ditions only on the table primary key attributes. You must provide the hash key
attribute name and value as an EQ condition. You can optionally provide a sec-
ond condition, referring to the range key attribute.
Note: If you don’t provide a range key condition, all of the items that match the
hash key will be retrieved. If a FilterExpression or QueryFilter is present, it will
be applied after the items are retrieved.
For a query on an index, you can have conditions only on the index key attributes.
You must provide the index hash attribute name and value as an EQ condition.
You can optionally provide a second condition, referring to the index key range
attribute.
Each KeyConditions element consists of an attribute name to compare, along
with the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the Com-
parisonOperator being used. For type Number, value comparisons are
numeric. String value comparisons for greater than, equals, or less
than are based on ASCII character code values. For example, a is
greater than A , and a is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters . For Bi-
3.1. Services 865
Boto3 Documentation, Release 1.1.4
nary, DynamoDB treats each byte of the binary data as unsigned when it
compares binary values.
– ComparisonOperator - A comparator for evaluating attributes, for exam-
ple, equals, greater than, less than, and so on. For KeyConditions , only
the following comparison operators are supported: EQ | LE | LT |
GE | GT | BEGINS_WITH | BETWEEN The following are descrip-
tions of these comparison operators. * EQ : Equal. AttributeValueList can
contain only one AttributeValue of type String, Number, or Binary (not a
set type). If an item contains an AttributeValue element of a different type
than the one specified in the request, the value does not match. For exam-
ple, {"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does
not equal {"NS":["6", "2", "1"]} .
– LE : Less than or equal. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– LT : Less than. AttributeValueList can contain only one AttributeValue of
type String, Number, or Binary (not a set type). If an item contains an
AttributeValue element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type than
the one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
– GT : Greater than. AttributeValueList can contain only one AttributeValue
element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– BEGINS_WITH : Checks for a prefix. AttributeValueList can contain only
one AttributeValue of type String or Binary (not a Number or a set type).
The target attribute of the comparison must be of type String or Binary
(not a Number or a set type).
– BETWEEN : Greater than or equal to the first value, and less than or equal
to the second value. AttributeValueList must contain two AttributeValue el-
ements of the same type, either String, Number, or Binary (not a set type).
A target attribute matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If an item con-
tains an AttributeValue element of a different type than the one provided
in the request, the value does not match. For example, {"S":"6"} does
not compare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see Legacy
Conditional Parameters in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
866 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Represents the selection criteria for a Query or Scan operation:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an in-
dex. For KeyConditions , only the following comparison
operators are supported: EQ | LE | LT | GE | GT |
BEGINS_WITH | BETWEEN Condition is also used in a
QueryFilter , which evaluates the query results and returns
only the desired values.
· For a Scan operation, Condition is used in a ScanFilter ,
which evaluates the scan results and returns only the desired
values.
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
The number of values in the list depends on the Comparison-
Operator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
3.1. Services 867
Boto3 Documentation, Release 1.1.4
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example, equals,
greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
868 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
3.1. Services 869
Boto3 Documentation, Release 1.1.4
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
For usage examples of AttributeValueList and Comparison-
Operator , see Legacy Conditional Parameters in the Amazon
DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward compatibility. New
applications should use FilterExpression instead. Do not combine legacy
• QueryFilter (dict) –
parameters and expression parameters in a single API call; otherwise, Dy-
namoDB will return a ValidationException exception.
A condition that evaluates the query results after the items are read and returns
only the desired values.
This parameter does not support attributes of type List or Map.
Note: A QueryFilter is applied after the items have already been read; the
process of filtering does not consume any additional read capacity units.
870 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
If you provide more than one condition in the QueryFilter map, then by default
all of the conditions must evaluate to true. In other words, the conditions are
ANDed together. (You can use the ConditionalOperator parameter to OR the
conditions instead. If you do this, then at least one of the conditions must evalu-
ate to true, rather than all of them.)
Note that QueryFilter does not allow key attributes. You cannot define a filter
condition on a hash key or range key.
Each QueryFilter element consists of an attribute name to compare, along with
the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the oper-
ator specified in ComparisonOperator . For type Number, value com-
parisons are numeric. String value comparisons for greater than, equals,
or less than are based on ASCII character code values. For example, a
is greater than A , and a is greater than B . For a list of code values,
see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters . For
type Binary, DynamoDB treats each byte of the binary data as unsigned
when it compares binary values. For information on specifying data types
in JSON, see JSON Data Format in the Amazon DynamoDB Developer
Guide .
– ComparisonOperator - A comparator for evaluating attributes. For
example, equals, greater than, less than, etc. The following com-
parison operators are available: EQ | NE | LE | LT | GE |
GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN For complete descriptions of all
comparison operators, see the Condition data type.
– (string) –
* (dict) –
Represents the selection criteria for a Query or Scan operation:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an in-
dex. For KeyConditions , only the following comparison
operators are supported: EQ | LE | LT | GE | GT |
BEGINS_WITH | BETWEEN Condition is also used in a
QueryFilter , which evaluates the query results and returns
only the desired values.
· For a Scan operation, Condition is used in a ScanFilter ,
which evaluates the scan results and returns only the desired
values.
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
The number of values in the list depends on the Comparison-
Operator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
3.1. Services 871
Boto3 Documentation, Release 1.1.4
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
872 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example, equals,
greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
3.1. Services 873
Boto3 Documentation, Release 1.1.4
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
874 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
For usage examples of AttributeValueList and Comparison-
Operator , see Legacy Conditional Parameters in the Amazon
DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward compatibi
applications should use FilterExpression instead. Do not comb
• ConditionalOperator (string) –
parameters and expression parameters in a single API call; other
namoDB will return a ValidationException exception.
A logical operator to apply to the conditions in a QueryFilter map:
– AND - If all of the conditions evaluate to true, then the entire map evaluates
to true.
– OR - If at least one of the conditions evaluate to true, then the entire map
evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ScanIndexForward (boolean) – Specifies the order in which to return the query
results - either ascending (true ) or descending (false ).
Items with the same hash key are stored in sorted order by range key .If the range
key data type is Number, the results are stored in numeric order. For type String,
the results are returned in order of ASCII character code values. For type Binary,
DynamoDB treats each byte of the binary data as unsigned.
If ScanIndexForward is true , DynamoDB returns the results in order, by range
key. This is the default behavior.
If ScanIndexForward is false , DynamoDB sorts the results in descending
order by range key, and then returns the results to the client.
• ExclusiveStartKey (dict) – The primary key of the first item that this opera-
tion will evaluate. Use the value that was returned for LastEvaluatedKey in the
previous operation.
The data type for ExclusiveStartKey must be String, Number or Binary. No set
data types are allowed.
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
3.1. Services 875
Boto3 Documentation, Release 1.1.4
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
876 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ProjectionExpression (string) – A string that identifies one or more attributes to
retrieve from the table. These attributes can include scalars, sets, or elements of a
JSON document. The attributes in the expression must be separated by commas.
If no attribute names are specified, then all attributes will be returned. If any of
the requested attributes are not found, they will not appear in the result.
For more information, see Accessing Item Attributes in the Amazon DynamoDB
Developer Guide .
Note: ProjectionExpression replaces the legacy AttributesToGet parameter.
• FilterExpression (string) – A string that contains conditions that DynamoDB
applies after the Query operation, but before the data is returned to you. Items
that do not satisfy the FilterExpression criteria are not returned.
Note: A FilterExpression is applied after the items have already been read; the
process of filtering does not consume any additional read capacity units.
For more information, see Filter Expressions in the Amazon DynamoDB Devel-
oper Guide .
Note: FilterExpression replaces the legacy QueryFilter and ConditionalOpera-
tor parameters.
• KeyConditionExpression (string) – The condition that specifies the key
value(s) for items to be retrieved by the Query action.
The condition must perform an equality test on a single hash key value. The
condition can also perform one of several comparison tests on a single range key
value. Query can use KeyConditionExpression to retrieve one item with a given
hash and range key value, or several items that have the same hash key value but
different range key values.
The hash key equality test is required, and must be specified in the following
format:
hashAttributeName = :hashval
If you also want to provide a range key condition, it must be combined using
AND with the hash key condition. Following is an example, using the = compar-
ison operator for the range key:
hashAttributeName = :hashval AND
rangeAttributeName = :rangeval
Valid comparisons for the range key condition are as follows:
– rangeAttributeName = :rangeval - true if the range key is equal
to :rangeval .
– rangeAttributeName ** :rangeval - true if the range key is less
than :rangeval .
3.1. Services 877
Boto3 Documentation, Release 1.1.4
– rangeAttributeName = :rangeval - true if the range key is less
than or equal to :rangeval .
– rangeAttributeName ** :rangeval - true if the range key is
greater than :rangeval .
– rangeAttributeName = :rangeval - true if the range key is
greater than or equal to :rangeval .
– rangeAttributeName BETWEEN :rangeval1 AND
:rangeval2 - true if the range key is greater than or equal to
:rangeval1 , and less than or equal to :rangeval2 .
– begins_with ( rangeAttributeName , :rangeval ) - true if the
range key begins with a particular operand. (You cannot use this func-
tion with a range key that is of type Number.) Note that the function name
begins_with is case-sensitive.
Use the ExpressionAttributeValues parameter to replace tokens such as
:hashval and :rangeval with actual values at runtime.
You can optionally use the ExpressionAttributeNames parameter to replace the
names of the hash and range attributes with placeholder tokens. This option
might be necessary if an attribute name conflicts with a DynamoDB reserved
word. For example, the following KeyConditionExpression parameter causes an
error because Size is a reserved word:
– Size = :myval
To work around this, define a placeholder (such a #S ) to represent the attribute
name Size . KeyConditionExpression then is as follows:
– #S = :myval
For a list of reserved words, see Reserved Words in the Amazon DynamoDB
Developer Guide .
For more information on ExpressionAttributeNames and ExpressionAttributeVal-
ues , see Using Placeholders for Attribute Names and Values in the Amazon Dy-
namoDB Developer Guide .
Note: KeyConditionExpression replaces the legacy KeyConditions parameter.
• ExpressionAttributeNames (dict) – One or more substitution tokens for at-
tribute names in an expression. The following are some use cases for using
ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB reserved
word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
878 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be substituted
in an expression.
Use the : (colon) character in an expression to dereference an attribute value.
For example, suppose that you wanted to check whether the value of the Prod-
uctStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Conditions
in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
3.1. Services 879
Boto3 Documentation, Release 1.1.4
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Return type dict
Returns
Response Syntax
{
'Items': [
{
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
880 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'Count': 123,
'ScannedCount': 123,
'LastEvaluatedKey': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
}
}
Response Structure
• (dict) –
Represents the output of a Query operation.
– Items (list) –
An array of item attributes that match the query criteria. Each element in
this array consists of an attribute name and the value for that attribute.
* (dict) –
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
3.1. Services 881
Boto3 Documentation, Release 1.1.4
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
882 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– Count (integer) –
The number of items in the response.
If you used a QueryFilter in the request, then Count is the number of items
returned after the filter was applied, and ScannedCount is the number of
matching items beforethe filter was applied.
If you did not use a filter in the request, then Count and ScannedCount are
the same.
– ScannedCount (integer) –
The number of items evaluated, before any QueryFilter is applied. A high
ScannedCount value with few, or no, Count results indicates an inefficient
Query operation. For more information, see Count and ScannedCount in
the Amazon DynamoDB Developer Guide .
If you did not use a filter in the request, then ScannedCount is the same as
Count .
– LastEvaluatedKey (dict) –
The primary key of the item where the operation stopped, inclusive of the
previous result set. Use this value to start a new operation, excluding this
value in the new request.
If LastEvaluatedKey is empty, then the “last page” of results has been
processed and there is no more data to be retrieved.
If LastEvaluatedKey is not empty, it does not necessarily mean that there is
more data in the result set. The only way to know when you have reached
the end of the result set is when LastEvaluatedKey is empty.
* (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
3.1. Services 883
Boto3 Documentation, Release 1.1.4
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned includes
the total provisioned throughput consumed, along with statistics for the ta-
ble and any indexes involved in the operation. ConsumedCapacity is only
returned if the request asked for it. For more information, see Provisioned
Throughput in the Amazon DynamoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the operation.
* Table (dict) –
The amount of throughput consumed on the table affected by the
operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index affected
by the operation.
· (string) –
884 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
scan(**kwargs)
The Scan operation returns one or more items and item attributes by accessing every item in a table or a
secondary index. To have DynamoDB return fewer items, you can provide a ScanFilter operation.
If the total number of scanned items exceeds the maximum data set size limit of 1 MB, the scan stops
and results are returned to the user as a LastEvaluatedKey value to continue the scan in a subsequent
operation. The results also include the number of items exceeding the limit. A scan can result in no table
data meeting the filter criteria.
By default, Scan operations proceed sequentially; however, for faster performance on a large table or
secondary index, applications can request a parallel Scan operation by providing the Segment and To-
talSegments parameters. For more information, see Parallel Scan in the Amazon DynamoDB Developer
Guide .
By default, Scan uses eventually consistent reads when acessing the data in the table or local secondary
index. However, you can use strongly consistent reads instead by setting the ConsistentRead parameter to
true .
Request Syntax
response = client.scan(
TableName='string',
IndexName='string',
AttributesToGet=[
'string',
],
Limit=123,
Select='ALL_ATTRIBUTES'|'ALL_PROJECTED_ATTRIBUTES'|'SPECIFIC_ATTRIBUTES'|'COUNT',
ScanFilter={
'string': {
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
3.1. Services 885
Boto3 Documentation, Release 1.1.4
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
}
},
ConditionalOperator='AND'|'OR',
ExclusiveStartKey={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
TotalSegments=123,
Segment=123,
ProjectionExpression='string',
FilterExpression='string',
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
886 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
ConsistentRead=True|False
)
Parameters
• TableName (string) – [REQUIRED]
The name of the table containing the requested items; or, if you provide
IndexName , the name of the table to which that index belongs.
• IndexName (string) – The name of a secondary index to scan. This index can
be any local secondary index or global secondary index. Note that if you use the
IndexName parameter, you must also provide TableName .
Warning: This is a legacy parameter, for backward compatibility. New a
plications should use ProjectionExpression instead. Do not combine lega
parameters and expression parameters in a single API call; otherwise, D
• AttributesToGet (list) –
namoDB will return a ValidationException exception.
This parameter allows you to retrieve attributes of type List or Map; howev
it cannot retrieve individual elements within a List or a Map.
The names of one or more attributes to retrieve. If no attribute names are pro-
vided, then all attributes will be returned. If any of the requested attributes are
not found, they will not appear in the result.
Note that AttributesToGet has no effect on provisioned throughput consumption.
DynamoDB determines capacity units consumed based on item size, not on the
amount of data that is returned to an application.
– (string) –
• Limit (integer) – The maximum number of items to evaluate (not necessarily
the number of matching items). If DynamoDB processes the number of items
up to the limit while processing the results, it stops the operation and returns the
matching values up to that point, and a key in LastEvaluatedKey to apply in a
subsequent operation, so that you can pick up where you left off. Also, if the
processed data set size exceeds 1 MB before DynamoDB reaches this limit, it
stops the operation and returns the matching values up to the limit, and a key in
LastEvaluatedKey to apply in a subsequent operation to continue the operation.
For more information, see Query and Scan in the Amazon DynamoDB Developer
Guide .
• Select (string) – The attributes to be returned in the result. You can retrieve all
item attributes, specific item attributes, or the count of matching items.
3.1. Services 887
Boto3 Documentation, Release 1.1.4
– ALL_ATTRIBUTES - Returns all of the item attributes.
– COUNT - Returns the number of matching items, rather than the matching
items themselves.
– SPECIFIC_ATTRIBUTES - Returns only the attributes listed in At-
tributesToGet . This return value is equivalent to specifying AttributesTo-
Get without specifying any value for Select .
If neither Select nor AttributesToGet are specified, DynamoDB defaults to
ALL_ATTRIBUTES . You cannot use both AttributesToGet and Select together
in a single request, unless the value for Select is SPECIFIC_ATTRIBUTES
. (This usage is equivalent to specifying AttributesToGet without any value for
Select .)
Warning: This is a legacy parameter, for backward compatibility. New
applications should use FilterExpression instead. Do not combine legacy
• ScanFilter (dict) –
parameters and expression parameters in a single API call; otherwise, Dy-
namoDB will return a ValidationException exception.
A condition that evaluates the scan results and returns only the desired values.
Note: This parameter does not support attributes of type List or Map.
If you specify more than one condition in the ScanFilter map, then by default all
of the conditions must evaluate to true. In other words, the conditions are ANDed
together. (You can use the ConditionalOperator parameter to OR the conditions
instead. If you do this, then at least one of the conditions must evaluate to true,
rather than all of them.)
Each ScanFilter element consists of an attribute name to compare, along with
the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the oper-
ator specified in ComparisonOperator . For type Number, value com-
parisons are numeric. String value comparisons for greater than, equals,
or less than are based on ASCII character code values. For example,
a is greater than A , and a is greater than B . For a list of code val-
ues, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters .
For Binary, DynamoDB treats each byte of the binary data as unsigned
when it compares binary values. For information on specifying data types
in JSON, see JSON Data Format in the Amazon DynamoDB Developer
Guide .
– ComparisonOperator - A comparator for evaluating attributes. For
example, equals, greater than, less than, etc. The following com-
parison operators are available: EQ | NE | LE | LT | GE |
GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN For complete descriptions of all
comparison operators, see Condition .
– (string) –
* (dict) –
Represents the selection criteria for a Query or Scan operation:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an in-
dex. For KeyConditions , only the following comparison
operators are supported: EQ | LE | LT | GE | GT |
BEGINS_WITH | BETWEEN Condition is also used in a
888 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
QueryFilter , which evaluates the query results and returns
only the desired values.
· For a Scan operation, Condition is used in a ScanFilter ,
which evaluates the scan results and returns only the desired
values.
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
The number of values in the list depends on the Comparison-
Operator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
3.1. Services 889
Boto3 Documentation, Release 1.1.4
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example, equals,
greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
890 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
3.1. Services 891
Boto3 Documentation, Release 1.1.4
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
For usage examples of AttributeValueList and Comparison-
Operator , see Legacy Conditional Parameters in the Amazon
DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward compatibi
applications should use FilterExpression instead. Do not comb
• ConditionalOperator (string) –
parameters and expression parameters in a single API call; other
namoDB will return a ValidationException exception.
A logical operator to apply to the conditions in a ScanFilter map:
– AND - If all of the conditions evaluate to true, then the entire map evaluates
to true.
– OR - If at least one of the conditions evaluate to true, then the entire map
evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ExclusiveStartKey (dict) – The primary key of the first item that this opera-
tion will evaluate. Use the value that was returned for LastEvaluatedKey in the
previous operation.
892 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The data type for ExclusiveStartKey must be String, Number or Binary. No set
data types are allowed.
In a parallel scan, a Scan request that includes ExclusiveStartKey must spec-
ify the same segment whose previous Scan returned the corresponding value of
LastEvaluatedKey .
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
3.1. Services 893
Boto3 Documentation, Release 1.1.4
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• TotalSegments (integer) – For a parallel Scan request, TotalSegments represents
the total number of segments into which the Scan operation will be divided. The
value of TotalSegments corresponds to the number of application workers that
will perform the parallel scan. For example, if you want to use four application
threads to scan a table or an index, specify a TotalSegments value of 4.
The value for TotalSegments must be greater than or equal to 1, and less than or
equal to 1000000. If you specify a TotalSegments value of 1, the Scan operation
will be sequential rather than parallel.
If you specify TotalSegments , you must also specify Segment .
• Segment (integer) – For a parallel Scan request, Segment identifies an individual
segment to be scanned by an application worker.
Segment IDs are zero-based, so the first segment is always 0. For example, if
you want to use four application threads to scan a table or an index, then the first
thread specifies a Segment value of 0, the second thread specifies 1, and so on.
The value of LastEvaluatedKey returned from a parallel Scan request must be
used as ExclusiveStartKey with the same segment ID in a subsequent Scan oper-
ation.
The value for Segment must be greater than or equal to 0, and less than the value
provided for TotalSegments .
If you provide Segment , you must also provide TotalSegments .
• ProjectionExpression (string) – A string that identifies one or more attributes
to retrieve from the specified table or index. These attributes can include scalars,
sets, or elements of a JSON document. The attributes in the expression must be
separated by commas.
If no attribute names are specified, then all attributes will be returned. If any of
the requested attributes are not found, they will not appear in the result.
For more information, see Accessing Item Attributes in the Amazon DynamoDB
Developer Guide .
894 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Note: ProjectionExpression replaces the legacy AttributesToGet parameter.
• FilterExpression (string) – A string that contains conditions that DynamoDB
applies after the Scan operation, but before the data is returned to you. Items that
do not satisfy the FilterExpression criteria are not returned.
Note: A FilterExpression is applied after the items have already been read; the
process of filtering does not consume any additional read capacity units.
For more information, see Filter Expressions in the Amazon DynamoDB Devel-
oper Guide .
Note: FilterExpression replaces the legacy ScanFilter and ConditionalOperator
parameters.
• ExpressionAttributeNames (dict) – One or more substitution tokens for at-
tribute names in an expression. The following are some use cases for using
ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB reserved
word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be substituted
in an expression.
Use the : (colon) character in an expression to dereference an attribute value.
For example, suppose that you wanted to check whether the value of the Prod-
uctStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
3.1. Services 895
Boto3 Documentation, Release 1.1.4
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Conditions
in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
896 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
• ConsistentRead (boolean) – A Boolean value that determines the read consis-
tency model during the scan:
– If ConsistentRead is false , then Scan will use eventually consistent
reads. The data returned from Scan might not contain the results of other
recently completed write operations (PutItem, UpdateItem or DeleteItem).
The Scan response might include some stale data.
– If ConsistentRead is true , then Scan will use strongly consistent reads.
All of the write operations that completed before the Scan began are guar-
anteed to be contained in the Scan response.
The default setting for ConsistentRead is false , meaning that eventually con-
sistent reads will be used.
Strongly consistent reads are not supported on global secondary indexes. If you
scan a global secondary index with ConsistentRead set to true, you will receive
a ValidationException .
Return type dict
Returns
Response Syntax
{
'Items': [
{
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
],
'Count': 123,
'ScannedCount': 123,
'LastEvaluatedKey': {
3.1. Services 897
Boto3 Documentation, Release 1.1.4
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
}
}
Response Structure
• (dict) –
Represents the output of a Scan operation.
– Items (list) –
An array of item attributes that match the scan criteria. Each element in
this array consists of an attribute name and the value for that attribute.
* (dict) –
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
898 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– Count (integer) –
The number of items in the response.
3.1. Services 899
Boto3 Documentation, Release 1.1.4
If you set ScanFilter in the request, then Count is the number of items
returned after the filter was applied, and ScannedCount is the number of
matching items before the filter was applied.
If you did not use a filter in the request, then Count is the same as Scanned-
Count .
– ScannedCount (integer) –
The number of items evaluated, before any ScanFilter is applied. A high
ScannedCount value with few, or no, Count results indicates an inefficient
Scan operation. For more information, see Count and ScannedCount in
the Amazon DynamoDB Developer Guide .
If you did not use a filter in the request, then ScannedCount is the same as
Count .
– LastEvaluatedKey (dict) –
The primary key of the item where the operation stopped, inclusive of the
previous result set. Use this value to start a new operation, excluding this
value in the new request.
If LastEvaluatedKey is empty, then the “last page” of results has been
processed and there is no more data to be retrieved.
If LastEvaluatedKey is not empty, it does not necessarily mean that there is
more data in the result set. The only way to know when you have reached
the end of the result set is when LastEvaluatedKey is empty.
* (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
900 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned includes
the total provisioned throughput consumed, along with statistics for the ta-
ble and any indexes involved in the operation. ConsumedCapacity is only
returned if the request asked for it. For more information, see Provisioned
Throughput in the Amazon DynamoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the operation.
* Table (dict) –
The amount of throughput consumed on the table affected by the
operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
3.1. Services 901
Boto3 Documentation, Release 1.1.4
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
update_item(**kwargs)
Edits an existing item’s attributes, or adds a new item to the table if it does not already exist. You can
put, delete, or add attribute values. You can also perform a conditional update on an existing item (insert
a new attribute name-value pair if it doesn’t exist, or replace an existing name-value pair if it has certain
expected attribute values). If conditions are specified and the item does not exist, then the operation fails
and a new item is not created.
You can also return the item’s attribute values in the same UpdateItem operation using the ReturnValues
parameter.
Request Syntax
response = client.update_item(
TableName='string',
Key={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
AttributeUpdates={
'string': {
'Value': {
'S': 'string',
902 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
'Action': 'ADD'|'PUT'|'DELETE'
}
},
Expected={
'string': {
'Value': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
'Exists': True|False,
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
3.1. Services 903
Boto3 Documentation, Release 1.1.4
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
]
}
},
ConditionalOperator='AND'|'OR',
ReturnValues='NONE'|'ALL_OLD'|'UPDATED_OLD'|'ALL_NEW'|'UPDATED_NEW',
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ReturnItemCollectionMetrics='SIZE'|'NONE',
UpdateExpression='string',
ConditionExpression='string',
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
}
)
Parameters
• TableName (string) – [REQUIRED]
The name of the table containing the item to update.
• Key (dict) – [REQUIRED]
The primary key of the item to be updated. Each element consists of an attribute
904 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
name and a value for that attribute.
For the primary key, you must provide all of the attributes. For example, with a
hash type primary key, you only need to provide the hash attribute. For a hash-
and-range type primary key, you must provide both the hash attribute and the
range attribute.
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
3.1. Services 905
Boto3 Documentation, Release 1.1.4
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Warning: This is a legacy parameter, for backward compatibility. N
applications should use UpdateExpression instead. Do not combine leg
parameters and expression parameters in a single API call; otherwise,
• AttributeUpdates (dict) –
namoDB will return a ValidationException exception.
This parameter can be used for modifying top-level attributes; howeve
does not support individual list or map elements.
The names of attributes to be modified, the action to perform on each, and the
new value for each. If you are updating an attribute that is an index key attribute
for any indexes on that table, the attribute type must match the index key type de-
fined in the AttributesDefinition of the table description. You can use UpdateItem
to update any nonkey attributes.
Attribute values cannot be null. String and Binary type attributes must have
lengths greater than zero. Set type attributes must not be empty. Requests with
empty values will be rejected with a ValidationException exception.
Each AttributeUpdates element consists of an attribute name to modify, along
with the following:
– Value - The new value, if applicable, for this attribute.
– Action - A value that specifies how to perform the update. This action is
only valid for an existing attribute whose data type is Number or is a set; do
not use ADD for other data types. If an item with the specified primary key
is found in the table, the following values perform the following actions:
* PUT - Adds the specified attribute to the item. If the attribute already
exists, it is replaced by the new value.
– DELETE - Removes the attribute and its value, if no value is specified for
DELETE . The data type of the specified value must match the existing
value’s data type. If a set of values is specified, then those values are
subtracted from the old set. For example, if the attribute value was the
set [a,b,c] and the DELETE action specifies [a,c] , then the final
attribute value is [b] . Specifying an empty set is an error.
– ADD - Adds the specified value to the item, if the attribute does not already
exist. If the attribute does exist, then the behavior of ADD depends on the
data type of the attribute: * If the existing attribute is a number, and if
Value is also a number, then Value is mathematically added to the existing
attribute. If Value is a negative number, then it is subtracted from the
existing attribute. .. note:: If you use ADD to increment or decrement a
number value for an item that doesn’t exist before the update, DynamoDB
uses 0 as the initial value. Similarly, if you use ADD for an existing item
to increment or decrement an attribute value that doesn’t exist before the
update, DynamoDB uses 0 as the initial value. For example, suppose that
the item you want to update doesn’t have an attribute named itemcount ,
but you decide to ADD the number 3 to this attribute anyway. DynamoDB
906 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
will create the itemcount attribute, set its initial value to 0 , and finally add
3 to it. The result will be a new itemcount attribute, with a value of 3 .
– If the existing data type is a set, and if Value is also a set, then Value is
appended to the existing set. For example, if the attribute value is the set
[1,2] , and the ADD action specified [3] , then the final attribute value is
[1,2,3] . An error occurs if an ADD action is specified for a set attribute
and the attribute type specified does not match the existing set type. Both
sets must have the same primitive data type. For example, if the existing
data type is a set of strings, Value must also be a set of strings.
If no item with the specified key is found in the table, the following values per-
form the following actions:
– PUT - Causes DynamoDB to create a new item with the specified primary
key, and then adds the attribute.
– DELETE - Nothing happens, because attributes cannot be deleted from a
nonexistent item. The operation succeeds, but DynamoDB does not create
a new item.
– ADD - Causes DynamoDB to create an item with the supplied primary key
and number (or set of numbers) for the attribute value. The only data types
allowed are Number and Number Set.
If you provide any attributes that are part of an index key, then the data types for
those attributes must match those of the schema in the table’s attribute definition.
– (string) –
* (dict) –
For the UpdateItem operation, represents the attributes to be modi-
fied, the action to perform on each, and the new value for each.
Note: You cannot use UpdateItem to update any primary key at-
tributes. Instead, you will need to delete the item, and then use
PutItem to create a new item with new attributes.
Attribute values cannot be null; string and binary type attributes
must have lengths greater than zero; and set type attributes must
not be empty. Requests with empty values will be rejected with a
ValidationException exception.
· Value (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
3.1. Services 907
Boto3 Documentation, Release 1.1.4
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· Action (string) –
Specifies how to perform the update. Valid values are PUT
(default), DELETE , and ADD . The behavior depends on
whether the specified primary key already exists in the table.
If an item with the specified *Key* is found in
the table:
· PUT - Adds the specified attribute to the item. If the attribute
already exists, it is replaced by the new value.
· DELETE - If no value is specified, the attribute and its value
are removed from the item. The data type of the specified
value must match the existing value’s data type. If a set of val-
ues is specified, then those values are subtracted from the old
set. For example, if the attribute value was the set [a,b,c]
and the DELETE action specified [a,c] , then the final at-
tribute value would be [b] . Specifying an empty set is an
error.
908 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· ADD - If the attribute does not already exist, then the attribute
and its values are added to the item. If the attribute does ex-
ist, then the behavior of ADD depends on the data type of the
attribute: * If the existing attribute is a number, and if Value
is also a number, then the Value is mathematically added to
the existing attribute. If Value is a negative number, then it
is subtracted from the existing attribute. .. note:: If you use
ADD to increment or decrement a number value for an item
that doesn’t exist before the update, DynamoDB uses 0 as the
initial value. In addition, if you use ADD to update an exist-
ing item, and intend to increment or decrement an attribute
value which does not yet exist, DynamoDB uses 0 as the ini-
tial value. For example, suppose that the item you want to
update does not yet have an attribute named itemcount , but
you decide to ADD the number 3 to this attribute anyway, even
though it currently does not exist. DynamoDB will create the
itemcount attribute, set its initial value to 0 , and finally add 3
to it. The result will be a new itemcount attribute in the item,
with a value of 3 .
· If the existing data type is a set, and if the Value is also a set,
then the Value is added to the existing set. (This is a set opera-
tion, not mathematical addition.) For example, if the attribute
value was the set [1,2] , and the ADD action specified [3]
, then the final attribute value would be [1,2,3] . An error
occurs if an Add action is specified for a set attribute and the
attribute type specified does not match the existing set type.
Both sets must have the same primitive data type. For exam-
ple, if the existing data type is a set of strings, the Value must
also be a set of strings. The same holds true for number sets
and binary sets.
This action is only valid for an existing attribute whose data
type is number or is a set. Do not use ADD for any other data
types.
If no item with the specified *Key* is found:
· PUT - DynamoDB creates a new item with the specified pri-
mary key, and then adds the attribute.
· DELETE - Nothing happens; there is no attribute to delete.
· ADD - DynamoDB creates an item with the supplied primary
key and number (or set of numbers) for the attribute value.
The only data types allowed are number and number set; no
other data types can be specified.
Warning: This is a legacy parameter, for backward compatibility. New ap-
plications should use ConditionExpression instead. Do not combine legacy
• Expected (dict) –
parameters and expression parameters in a single API call; otherwise, Dy-
namoDB will return a ValidationException exception.
A map of attribute/condition pairs. Expected provides a conditional block for the
UpdateItem operation.
Each element of Expected consists of an attribute name, a comparison operator,
and one or more values. DynamoDB compares the attribute with the value(s)
you supplied, using the comparison operator. For each Expected element, the
result of the evaluation is either true or false.
3.1. Services 909
Boto3 Documentation, Release 1.1.4
If you specify more than one element in the Expected map, then by default all of
the conditions must evaluate to true. In other words, the conditions are ANDed
together. (You can use the ConditionalOperator parameter to OR the conditions
instead. If you do this, then at least one of the conditions must evaluate to true,
rather than all of them.)
If the Expected map evaluates to true, then the conditional operation succeeds;
otherwise, it fails.
Expected contains the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the Com-
parisonOperator being used. For type Number, value comparisons are
numeric. String value comparisons for greater than, equals, or less
than are based on ASCII character code values. For example, a is
greater than A , and a is greater than B . For a list of code values,
see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters . For
type Binary, DynamoDB treats each byte of the binary data as unsigned
when it compares binary values.
– ComparisonOperator - A comparator for evaluating attributes in the
AttributeValueList . When performing the comparison, DynamoDB
uses strongly consistent reads. The following comparison operators
are available: EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH |
IN | BETWEEN The following are descriptions of each comparison
operator. * EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one AttributeValue element
of type String, Number, Binary, String Set, Number Set, or Binary Set.
If an item contains an AttributeValue element of a different type than
the one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
– NE : Not equal. NE is supported for all datatypes, including lists and
maps. AttributeValueList can contain only one AttributeValue of type
String, Number, Binary, String Set, Number Set, or Binary Set. If an item
contains an AttributeValue of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not equal {"NS":["6",
"2", "1"]} .
– LE : Less than or equal. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– LT : Less than. AttributeValueList can contain only one AttributeValue of
type String, Number, or Binary (not a set type). If an item contains an
AttributeValue element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type than
the one provided in the request, the value does not match. For example,
910 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
– GT : Greater than. AttributeValueList can contain only one AttributeValue
element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– NOT_NULL : The attribute exists. NOT_NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for the
existence of an attribute, not its data type. If the data type of attribute “a ”
is null, and you evaluate it using NOT_NULL , the result is a Boolean true
. This result is because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
– NULL : The attribute does not exist. NULL is supported for all datatypes,
including lists and maps. .. note::This operator tests for the nonexistence
of an attribute, not its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean false . This is
because the attribute “a ” exists; its data type is not relevant to the NULL
comparison operator.
– CONTAINS : Checks for a subsequence, or value in a set. AttributeVal-
ueList can contain only one AttributeValue element of type String, Num-
ber, or Binary (not a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring match. If the target
attribute of the comparison is of type Binary, then the operator looks for
a subsequence of the target that matches the input. If the target attribute
of the comparison is a set (“SS ”, “NS ”, or “BS ”), then the operator
evaluates to true if it finds an exact match with any member of the set.
CONTAINS is supported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a list.
– NOT_CONTAINS : Checks for absence of a subsequence, or absence of
a value in a set. AttributeValueList can contain only one AttributeValue
element of type String, Number, or Binary (not a set type). If the target
attribute of the comparison is a String, then the operator checks for the
absence of a substring match. If the target attribute of the comparison is
Binary, then the operator checks for the absence of a subsequence of the
target that matches the input. If the target attribute of the comparison is a
set (“SS ”, “NS ”, or “BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set. NOT_CONTAINS is
supported for lists: When evaluating “a NOT CONTAINS b ”, “a ” can
be a list; however, “b ” cannot be a set, a map, or a list.
– BEGINS_WITH : Checks for a prefix. AttributeValueList can contain only
one AttributeValue of type String or Binary (not a Number or a set type).
The target attribute of the comparison must be of type String or Binary
(not a Number or a set type).
– IN : Checks for matching elements within two sets. AttributeValueList can
contain one or more AttributeValue elements of type String, Number, or
Binary (not a set type). These attributes are compared against an existing
set type attribute of an item. If any elements of the input set are present in
the item attribute, the expression evaluates to true.
– BETWEEN : Greater than or equal to the first value, and less than or equal
to the second value. AttributeValueList must contain two AttributeValue el-
ements of the same type, either String, Number, or Binary (not a set type).
A target attribute matches if the target value is greater than, or equal to, the
3.1. Services 911
Boto3 Documentation, Release 1.1.4
first element and less than, or equal to, the second element. If an item con-
tains an AttributeValue element of a different type than the one provided
in the request, the value does not match. For example, {"S":"6"} does
not compare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see Legacy
Conditional Parameters in the Amazon DynamoDB Developer Guide .
For backward compatibility with previous DynamoDB releases, the following
parameters can be used instead of AttributeValueList and ComparisonOperator :
– Value - A value for DynamoDB to compare with an attribute.
– Exists - A Boolean value that causes DynamoDB to evaluate the value
before attempting the conditional operation: * If Exists is true , Dy-
namoDB will check to see if that attribute value already exists in the table.
If it is found, then the condition evaluates to true; otherwise the condition
evaluate to false.
– If Exists is false , DynamoDB assumes that the attribute value does not
exist in the table. If in fact the value does not exist, then the assumption is
valid and the condition evaluates to true. If the value is found, despite the
assumption that it does not exist, the condition evaluates to false.
Note that the default value for Exists is true .
The Value and Exists parameters are incompatible with AttributeValueList and
ComparisonOperator . Note that if you use both sets of parameters at once,
DynamoDB will return a ValidationException exception.
Note: This parameter does not support attributes of type List or Map.
– (string) –
* (dict) –
Represents a condition to be compared with an attribute value. This
condition can be used with DeleteItem , PutItem or UpdateItem op-
erations; if the comparison evaluates to true, the operation succeeds;
if not, the operation fails. You can use ExpectedAttributeValue in
one of two different ways:
· Use AttributeValueList to specify one or more values to com-
pare against an attribute. Use ComparisonOperator to specify
how you want to perform the comparison. If the comparison
evaluates to true, then the conditional operation succeeds.
· Use Value to specify a value that DynamoDB will compare
against an attribute. If the values match, then ExpectedAt-
tributeValue evaluates to true and the conditional operation
succeeds. Optionally, you can also set Exists to false, indi-
cating that you do not expect to find the attribute value in the
table. In this case, the conditional operation succeeds only if
the comparison evaluates to false.
Value and Exists are incompatible with AttributeValueList and Com-
parisonOperator . Note that if you use both sets of parameters at
once, DynamoDB will return a ValidationException exception.
· Value (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
912 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· Exists (boolean) –
3.1. Services 913
Boto3 Documentation, Release 1.1.4
Causes DynamoDB to evaluate the value before attempting a
conditional operation:
· If Exists is true , DynamoDB will check to see if that at-
tribute value already exists in the table. If it is found, then the
operation succeeds. If it is not found, the operation fails with
a ConditionalCheckFailedException .
· If Exists is false , DynamoDB assumes that the attribute
value does not exist in the table. If in fact the value does not
exist, then the assumption is valid and the operation succeeds.
If the value is found, despite the assumption that it does not
exist, the operation fails with a ConditionalCheckFailedEx-
ception .
The default setting for Exists is true . If you supply a Value
all by itself, DynamoDB assumes the attribute exists: You
don’t have to set Exists to true , because it is implied.
DynamoDB returns a ValidationException if:
· Exists is true but there is no Value to check. (You expect a
value to exist, but don’t specify what that value is.)
· Exists is false but you also provide a Value . (You cannot
expect an attribute to have a value, while also expecting it not
to exist.)
· ComparisonOperator (string) –
A comparator for evaluating attributes in the AttributeVal-
ueList . For example, equals, greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
914 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
3.1. Services 915
Boto3 Documentation, Release 1.1.4
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
The number of values in the list depends on the Comparison-
Operator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
For information on specifying data types in JSON, see JSON
Data Format in the Amazon DynamoDB Developer Guide .
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
916 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Warning: This is a legacy parameter, for backward compatibility
plications should use ConditionExpression instead. Do not comb
• ConditionalOperator (string) –
parameters and expression parameters in a single API call; other
namoDB will return a ValidationException exception.
3.1. Services 917
Boto3 Documentation, Release 1.1.4
A logical operator to apply to the conditions in the Expected map:
– AND - If all of the conditions evaluate to true, then the entire map evaluates
to true.
– OR - If at least one of the conditions evaluate to true, then the entire map
evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ReturnValues (string) – Use ReturnValues if you want to get the item attributes
as they appeared either before or after they were updated. For UpdateItem , the
valid values are:
– NONE - If ReturnValues is not specified, or if its value is NONE , then
nothing is returned. (This setting is the default for ReturnValues .)
– ALL_OLD - If UpdateItem overwrote an attribute name-value pair, then
the content of the old item is returned.
– UPDATED_OLD - The old versions of only the updated attributes are re-
turned.
– ALL_NEW - All of the attributes of the new version of the item are re-
turned.
– UPDATED_NEW - The new versions of only the updated attributes are re-
turned.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ReturnItemCollectionMetrics (string) – Determines whether item collection
metrics are returned. If set to SIZE , the response includes statistics about item
collections, if any, that were modified during the operation are returned in the
response. If set to NONE (the default), no statistics are returned.
• UpdateExpression (string) – An expression that defines one or more attributes
to be updated, the action to be performed on them, and new value(s) for them.
The following action values are available for UpdateExpression .
– SET - Adds one or more attributes and values to an item. If any of these
attribute already exist, they are replaced by the new values. You can also
use SET to add or subtract from an attribute that is of type Number. For
example: SET myNum = myNum + :val SET supports the following
functions: * if_not_exists (path, operand) - if the item does
not contain an attribute at the specified path, then if_not_exists eval-
uates to operand; otherwise, it evaluates to path. You can use this function
to avoid overwriting an attribute that may already be present in the item.
– list_append (operand, operand) - evaluates to a list with a
new element added to it. You can append the new element to the start
or the end of the list by reversing the order of the operands.
These function names are case-sensitive.
918 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– REMOVE - Removes one or more attributes from an item.
– ADD - Adds the specified value to the item, if the attribute does not already
exist. If the attribute does exist, then the behavior of ADD depends on the
data type of the attribute: * If the existing attribute is a number, and if
Value is also a number, then Value is mathematically added to the existing
attribute. If Value is a negative number, then it is subtracted from the
existing attribute. .. note:: If you use ADD to increment or decrement a
number value for an item that doesn’t exist before the update, DynamoDB
uses 0 as the initial value. Similarly, if you use ADD for an existing item
to increment or decrement an attribute value that doesn’t exist before the
update, DynamoDB uses 0 as the initial value. For example, suppose that
the item you want to update doesn’t have an attribute named itemcount ,
but you decide to ADD the number 3 to this attribute anyway. DynamoDB
will create the itemcount attribute, set its initial value to 0 , and finally add
3 to it. The result will be a new itemcount attribute in the item, with a
value of 3 .
– If the existing data type is a set and if Value is also a set, then Value is
added to the existing set. For example, if the attribute value is the set
[1,2] , and the ADD action specified [3] , then the final attribute value
is [1,2,3] . An error occurs if an ADD action is specified for a set
attribute and the attribute type specified does not match the existing set
type. Both sets must have the same primitive data type. For example, if
the existing data type is a set of strings, the Value must also be a set of
strings.
Warning: The ADD action only supports Number and set data types. In
addition, ADD can only be used on top-level attributes, not nested attributes.
– DELETE - Deletes an element from a set. If a set of values is specified,
then those values are subtracted from the old set. For example, if the
attribute value was the set [a,b,c] and the DELETE action specifies
[a,c] , then the final attribute value is [b] . Specifying an empty set
is an error. .. warning::The DELETE action only supports set data types.
In addition, DELETE can only be used on top-level attributes, not nested
attributes.
You can have many actions in a single expression, such as the following: SET
a=:value1, b=:value2 DELETE :value3, :value4, :value5
For more information on update expressions, see Modifying Items and Attributes
in the Amazon DynamoDB Developer Guide .
Note: UpdateExpression replaces the legacy AttributeUpdates parameter.
• ConditionExpression (string) – A condition that must be satisfied in order for a
conditional update to succeed.
An expression can contain any of the following:
– Functions: attribute_exists | attribute_not_exists
| attribute_type | contains | begins_with | size
These function names are case-sensitive.
– Comparison operators: = | | | | = | = | BETWEEN | IN
– Logical operators: AND | OR | NOT
For more information on condition expressions, see Specifying Conditions in the
Amazon DynamoDB Developer Guide .
Note: ConditionExpression replaces the legacy ConditionalOperator and Ex-
pected parameters.
3.1. Services 919
Boto3 Documentation, Release 1.1.4
• ExpressionAttributeNames (dict) – One or more substitution tokens for at-
tribute names in an expression. The following are some use cases for using
ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB reserved
word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be substituted
in an expression.
Use the : (colon) character in an expression to dereference an attribute value.
For example, suppose that you wanted to check whether the value of the Prod-
uctStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Conditions
in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
920 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
Return type dict
Returns
Response Syntax
{
'Attributes': {
3.1. Services 921
Boto3 Documentation, Release 1.1.4
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
'ItemCollectionMetrics': {
'ItemCollectionKey': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
922 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'SizeEstimateRangeGB': [
123.0,
]
}
}
Response Structure
• (dict) –
Represents the output of an UpdateItem operation.
– Attributes (dict) –
A map of attribute values as they appeared before the UpdateItem opera-
tion. This map only appears if ReturnValues was specified as something
other than NONE in the request. Each element represents one attribute.
* (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
3.1. Services 923
Boto3 Documentation, Release 1.1.4
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned includes
the total provisioned throughput consumed, along with statistics for the ta-
ble and any indexes involved in the operation. ConsumedCapacity is only
returned if the request asked for it. For more information, see Provisioned
Throughput in the Amazon DynamoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the operation.
* Table (dict) –
The amount of throughput consumed on the table affected by the
operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
924 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
– ItemCollectionMetrics (dict) –
Information about item collections, if any, that were affected by the oper-
ation. ItemCollectionMetrics is only returned if the request asked for it.
If the table does not have any local secondary indexes, this information is
not returned in the response.
* ItemCollectionKey (dict) –
The hash key value of the item collection. This value is the same as
the hash key of the item.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
3.1. Services 925
Boto3 Documentation, Release 1.1.4
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
* SizeEstimateRangeGB (list) –
An estimate of item collection size, in gigabytes. This value is a
two-element array containing a lower bound and an upper bound
for the estimate. The estimate includes the size of all the items in
the table, plus the size of all attributes projected into all of the lo-
cal secondary indexes on that table. Use this estimate to measure
whether a local secondary index is approaching its size limit.
The estimate is subject to change over time; therefore, do not rely
on the precision or accuracy of the estimate.
· (float) –
update_table(**kwargs)
Modifies the provisioned throughput settings, global secondary indexes, or DynamoDB Streams settings
for a given table.
You can only perform one of the following operations at once:
•Modify the provisioned throughput settings of the table.
•Enable or disable Streams on the table.
•Remove a global secondary index from the table.
•Create a new global secondary index on the table. Once the index begins backfilling, you can use
UpdateTable to perform other operations.
UpdateTable is an asynchronous operation; while it is executing, the table status changes from ACTIVE
to UPDATING . While it is UPDATING , you cannot issue another UpdateTable request. When the table
returns to the ACTIVE state, the UpdateTable operation is complete.
Request Syntax
response = client.update_table(
AttributeDefinitions=[
{
926 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'AttributeName': 'string',
'AttributeType': 'S'|'N'|'B'
},
],
TableName='string',
ProvisionedThroughput={
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
GlobalSecondaryIndexUpdates=[
{
'Update': {
'IndexName': 'string',
'ProvisionedThroughput': {
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
}
},
'Create': {
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'ProvisionedThroughput': {
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
}
},
'Delete': {
'IndexName': 'string'
}
},
],
StreamSpecification={
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_ONLY'
}
)
Parameters
• AttributeDefinitions (list) – An array of attributes that describe the key schema
for the table and indexes. If you are adding a new global secondary index to the
table, AttributeDefinitions must include the key element(s) of the new index.
– (dict) –
Represents an attribute for describing the key schema for the table and
indexes.
* AttributeName (string) – [REQUIRED]
A name for the attribute.
3.1. Services 927
Boto3 Documentation, Release 1.1.4
* AttributeType (string) – [REQUIRED]
The data type for the attribute.
• TableName (string) – [REQUIRED]
The name of the table to be updated.
• ProvisionedThroughput (dict) – Represents the provisioned throughput set-
tings for a specified table or index. The settings can be modified using the Up-
dateTable operation.
For current minimum and maximum provisioned throughput values, see Limits
in the Amazon DynamoDB Developer Guide .
– ReadCapacityUnits (integer) – [REQUIRED]
The maximum number of strongly consistent reads consumed per second
before DynamoDB returns a ThrottlingException . For more information,
see Specifying Read and Write Requirements in the Amazon DynamoDB
Developer Guide .
– WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per second before DynamoDB
returns a ThrottlingException . For more information, see Specifying Read
and Write Requirements in the Amazon DynamoDB Developer Guide .
• GlobalSecondaryIndexUpdates (list) – An array of one or more global sec-
ondary indexes for the table. For each index in the array, you can request one
action:
– Create - add a new global secondary index to the table.
– Update - modify the provisioned throughput settings of an existing global
secondary index.
– Delete - remove a global secondary index from the table.
For more information, see Managing Global Secondary Indexes in the Amazon
DynamoDB Developer Guide .
– (dict) –
Represents one of the following:
* A new global secondary index to be added to an existing table.
* New provisioned throughput parameters for an existing global sec-
ondary index.
* An existing global secondary index to be removed from an existing
table.
* Update (dict) –
The name of an existing global secondary index, along with new
provisioned throughput settings to be applied to that index.
· IndexName (string) – [REQUIRED]
The name of the global secondary index to be updated.
· ProvisionedThroughput (dict) – [REQUIRED]
Represents the provisioned throughput settings for a specified
table or index. The settings can be modified using the Up-
dateTable operation.
For current minimum and maximum provisioned through-
put values, see Limits in the Amazon DynamoDB Developer
Guide .
· ReadCapacityUnits (integer) – [REQUIRED]
928 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. For more information, see Specifying Read and Write Re-
quirements in the Amazon DynamoDB Developer Guide .
· WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException . For more infor-
mation, see Specifying Read and Write Requirements in the
Amazon DynamoDB Developer Guide .
* Create (dict) –
The parameters required for creating a global secondary index on an
existing table:
· IndexName
· KeySchema
· AttributeDefinitions
· Projection
· ProvisionedThroughput
· IndexName (string) – [REQUIRED]
The name of the global secondary index to be created.
· KeySchema (list) – [REQUIRED]
The key schema for the global secondary index.
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) – [REQUIRED]
The name of a key attribute.
· KeyType (string) – [REQUIRED]
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) – [REQUIRED]
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
3.1. Services 929
Boto3 Documentation, Release 1.1.4
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
· ProvisionedThroughput (dict) – [REQUIRED]
Represents the provisioned throughput settings for a specified
table or index. The settings can be modified using the Up-
dateTable operation.
For current minimum and maximum provisioned through-
put values, see Limits in the Amazon DynamoDB Developer
Guide .
· ReadCapacityUnits (integer) – [REQUIRED]
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. For more information, see Specifying Read and Write Re-
quirements in the Amazon DynamoDB Developer Guide .
· WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException . For more infor-
mation, see Specifying Read and Write Requirements in the
Amazon DynamoDB Developer Guide .
* Delete (dict) –
The name of an existing global secondary index to be removed.
· IndexName (string) – [REQUIRED]
The name of the global secondary index to be deleted.
• StreamSpecification (dict) – Represents the DynamoDB Streams configuration
for the table.
Note: You will receive a ResourceInUseException if you attempt to enable a
stream on a table that already has a stream, or if you attempt to disable a stream
on a table which does not have a stream.
– StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled (true) or disabled (false)
on the table.
– StreamViewType (string) –
The DynamoDB Streams settings for the table. These settings consist of:
* StreamEnabled - Indicates whether DynamoDB Streams is enabled
(true) or disabled (false) on the table.
* StreamViewType - When an item in the table is modified,
StreamViewType determines what information is written to the
stream for this table. Valid values for StreamViewType are: *
930 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
KEYS_ONLY - Only the key attributes of the modified item are writ-
ten to the stream.
* NEW_IMAGE - The entire item, as it appears after it was modified,
is written to the stream.
* OLD_IMAGE - The entire item, as it appeared before it was modi-
fied, is written to the stream.
* NEW_AND_OLD_IMAGES - Both the new and the old item images
of the item are written to the stream.
Return type dict
Returns
Response Syntax
{
'TableDescription': {
'AttributeDefinitions': [
{
'AttributeName': 'string',
'AttributeType': 'S'|'N'|'B'
},
],
'TableName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'TableStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'CreationDateTime': datetime(2015, 1, 1),
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'TableSizeBytes': 123,
'ItemCount': 123,
'TableArn': 'string',
'LocalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
3.1. Services 931
Boto3 Documentation, Release 1.1.4
},
],
'GlobalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'Backfilling': True|False,
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
},
],
'StreamSpecification': {
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_O
},
'LatestStreamLabel': 'string',
'LatestStreamArn': 'string'
}
}
Response Structure
• (dict) –
Represents the output of an UpdateTable operation.
– TableDescription (dict) –
Represents the properties of a table.
* AttributeDefinitions (list) –
An array of AttributeDefinition objects. Each of these objects de-
scribes one attribute in the table and index key schema.
Each AttributeDefinition object in this array is composed of:
· AttributeName - The name of the attribute.
· AttributeType - The data type for the attribute.
· (dict) –
Represents an attribute for describing the key schema for the
table and indexes.
932 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· AttributeName (string) –
A name for the attribute.
· AttributeType (string) –
The data type for the attribute.
* TableName (string) –
The name of the table.
* KeySchema (list) –
The primary key structure for the table. Each KeySchemaElement
consists of:
· AttributeName - The name of the attribute.
· KeyType - The key type for the attribute. Can be either HASH
or RANGE .
For more information about primary keys, see Primary Key in the
Amazon DynamoDB Developer Guide .
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
* TableStatus (string) –
The current state of the table:
· CREATING - The table is being created.
· UPDATING - The table is being updated.
· DELETING - The table is being deleted.
· ACTIVE - The table is ready for use.
* CreationDateTime (datetime) –
The date and time when the table was created, in UNIX epoch time
format.
* ProvisionedThroughput (dict) –
The provisioned throughput settings for the table, consisting of read
and write capacity units, along with data about increases and de-
creases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput increase
for this table.
· LastDecreaseDateTime (datetime) –
3.1. Services 933
Boto3 Documentation, Release 1.1.4
The date and time of the last provisioned throughput decrease
for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for this ta-
ble during this UTC calendar day. For current maximums on
provisioned throughput decreases, see Limits in the Amazon
DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. Eventually consistent reads require less effort than strongly
consistent reads, so a setting of 50 ReadCapacityUnits per
second provides 100 eventually consistent ReadCapacityU-
nits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException .
* TableSizeBytes (integer) –
The total size of the specified table, in bytes. DynamoDB updates
this value approximately every six hours. Recent changes might not
be reflected in this value.
* ItemCount (integer) –
The number of items in the specified table. DynamoDB updates this
value approximately every six hours. Recent changes might not be
reflected in this value.
* TableArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies the ta-
ble.
* LocalSecondaryIndexes (list) –
Represents one or more local secondary indexes on the table. Each
index is scoped to a given hash key value. Tables with one or more
local secondary indexes are subject to an item collection size limit,
where the amount of data within a given item collection cannot ex-
ceed 10 GB. Each element is composed of:
· IndexName - The name of the local secondary index.
· KeySchema - Specifies the complete index key schema. The
attribute names in the key schema must be between 1 and 255
characters (inclusive). The key schema must begin with the
same hash key attribute as the table.
· Projection - Specifies attributes that are copied (projected)
from the table into the index. These are in addition to the pri-
mary key attributes and index key attributes, which are auto-
matically projected. Each attribute specification is composed
of: * ProjectionType - One of the following: * KEYS_ONLY -
Only the index and primary keys are projected into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes - A list of one or more non-key attribute
934 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
names that are projected into the secondary index. The total
count of attributes provided in NonKeyAttributes , summed
across all of the secondary indexes, must not exceed 20. If
you project the same attribute into two different indexes, this
counts as two distinct attributes when determining the total.
· IndexSizeBytes - Represents the total size of the index, in
bytes. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
· ItemCount - Represents the number of items in the index. Dy-
namoDB updates this value approximately every six hours.
Recent changes might not be reflected in this value.
If the table is in the DELETING state, no information about indexes
will be returned.
· (dict) –
Represents the properties of a local secondary index.
· IndexName (string) –
Represents the name of the local secondary index.
· KeySchema (list) –
The complete index key schema, which consists of one or
more pairs of attribute names and key types (HASH or RANGE
).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
3.1. Services 935
Boto3 Documentation, Release 1.1.4
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· ItemCount (integer) –
The number of items in the specified index. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the index.
* GlobalSecondaryIndexes (list) –
The global secondary indexes, if any, on the table. Each index is
scoped to a given hash key value. Each element is composed of:
· Backfilling - If true, then the index is currently in the back-
filling phase. Backfilling occurs only when a new global sec-
ondary index is added to the table; it is the process by which
DynamoDB populates the new index with data from the table.
(This attribute does not appear for indexes that were created
during a CreateTable operation.)
· IndexName - The name of the global secondary index.
· IndexSizeBytes - The total size of the global secondary index,
in bytes. DynamoDB updates this value approximately every
six hours. Recent changes might not be reflected in this value.
· IndexStatus - The current status of the global secondary index:
* CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· ItemCount - The number of items in the global secondary in-
dex. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
· KeySchema - Specifies the complete index key schema. The
attribute names in the key schema must be between 1 and 255
characters (inclusive). The key schema must begin with the
same hash key attribute as the table.
· Projection - Specifies attributes that are copied (projected)
from the table into the index. These are in addition to the pri-
mary key attributes and index key attributes, which are auto-
matically projected. Each attribute specification is composed
of: * ProjectionType - One of the following: * KEYS_ONLY -
Only the index and primary keys are projected into the index.
936 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes - A list of one or more non-key attribute
names that are projected into the secondary index. The total
count of attributes provided in NonKeyAttributes , summed
across all of the secondary indexes, must not exceed 20. If
you project the same attribute into two different indexes, this
counts as two distinct attributes when determining the total.
· ProvisionedThroughput - The provisioned throughput settings
for the global secondary index, consisting of read and write
capacity units, along with data about increases and decreases.
If the table is in the DELETING state, no information about indexes
will be returned.
· (dict) –
Represents the properties of a global secondary index.
· IndexName (string) –
The name of the global secondary index.
· KeySchema (list) –
The complete key schema for the global secondary index,
consisting of one or more pairs of attribute names and key
types (HASH or RANGE ).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from the ta-
ble into an index. These are in addition to the primary key
attributes and index key attributes, which are automatically
projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
3.1. Services 937
Boto3 Documentation, Release 1.1.4
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
· IndexStatus (string) –
The current state of the global secondary index:
· CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· Backfilling (boolean) –
Indicates whether the index is currently backfilling. Backfill-
ing is the process of reading items from the table and deter-
mining whether they can be added to the index. (Not all items
will qualify: For example, a hash key attribute cannot have
any duplicates.) If an item can be added to the index, Dy-
namoDB will do so. After all items have been processed, the
backfilling operation is complete and Backfilling is false.
Note: For indexes that were created during a CreateTable
operation, the Backfilling attribute does not appear in the De-
scribeTable output.
· ProvisionedThroughput (dict) –
Represents the provisioned throughput settings for the table,
consisting of read and write capacity units, along with data
about increases and decreases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput increase
for this table.
· LastDecreaseDateTime (datetime) –
The date and time of the last provisioned throughput decrease
for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for this ta-
ble during this UTC calendar day. For current maximums on
provisioned throughput decreases, see Limits in the Amazon
DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. Eventually consistent reads require less effort than strongly
consistent reads, so a setting of 50 ReadCapacityUnits per
938 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
second provides 100 eventually consistent ReadCapacityU-
nits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException .
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· ItemCount (integer) –
The number of items in the specified index. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the index.
* StreamSpecification (dict) –
The current DynamoDB Streams configuration for the table.
· StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled (true) or
disabled (false) on the table.
· StreamViewType (string) –
The DynamoDB Streams settings for the table. These settings
consist of:
· StreamEnabled - Indicates whether DynamoDB Streams is
enabled (true) or disabled (false) on the table.
· StreamViewType - When an item in the table is modified,
StreamViewType determines what information is written to the
stream for this table. Valid values for StreamViewType are: *
KEYS_ONLY - Only the key attributes of the modified item
are written to the stream.
· NEW_IMAGE - The entire item, as it appears after it was
modified, is written to the stream.
· OLD_IMAGE - The entire item, as it appeared before it was
modified, is written to the stream.
· NEW_AND_OLD_IMAGES - Both the new and the old item
images of the item are written to the stream.
* LatestStreamLabel (string) –
A timestamp, in ISO 8601 format, for this stream.
Note that LatestStreamLabel is not a unique identifier for the stream,
because it is possible that a stream from another table might have the
same timestamp. However, the combination of the following three
elements is guaranteed to be unique:
· the AWS customer ID.
· the table name.
· the StreamLabel .
* LatestStreamArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies the lat-
est stream for this table.
3.1. Services 939
Boto3 Documentation, Release 1.1.4
Paginators
The available paginators are:
• DynamoDB.Paginator.ListTables
• DynamoDB.Paginator.Query
• DynamoDB.Paginator.Scan
class DynamoDB.Paginator.ListTables
paginator = client.get_paginator('list_tables')
paginate(**kwargs)
Creates an iterator that will paginate through responses from DynamoDB.Client.list_tables().
Request Syntax
response_iterator = paginator.paginate(
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
• MaxItems (integer) –
The total number of items to return. If the total number of items available is
more than the value specified in max-items then a NextToken will be provided
in the output that you can use to resume pagination.
• PageSize (integer) –
The size of each page.
• StartingToken (string) –
A token to specify where to start paginating. This is the NextToken from a
previous response.
Return type dict
Returns
Response Syntax
{
'TableNames': [
'string',
],
'NextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a ListTables operation.
940 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– TableNames (list) –
The names of the tables associated with the current account at the current
endpoint. The maximum size of this array is 100.
If LastEvaluatedTableName also appears in the output, you can use this
value as the ExclusiveStartTableName parameter in a subsequent ListTa-
bles request and obtain the next page of results.
* (string) –
– NextToken (string) –
A token to resume pagination.
class DynamoDB.Paginator.Query
paginator = client.get_paginator('query')
paginate(**kwargs)
Creates an iterator that will paginate through responses from DynamoDB.Client.query().
Request Syntax
response_iterator = paginator.paginate(
TableName='string',
IndexName='string',
Select='ALL_ATTRIBUTES'|'ALL_PROJECTED_ATTRIBUTES'|'SPECIFIC_ATTRIBUTES'|'COUNT',
AttributesToGet=[
'string',
],
ConsistentRead=True|False,
KeyConditions={
'string': {
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
}
3.1. Services 941
Boto3 Documentation, Release 1.1.4
},
QueryFilter={
'string': {
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
}
},
ConditionalOperator='AND'|'OR',
ScanIndexForward=True|False,
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ProjectionExpression='string',
FilterExpression='string',
KeyConditionExpression='string',
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
942 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'NULL': True|False,
'BOOL': True|False
}
},
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• TableName (string) – [REQUIRED]
The name of the table containing the requested items.
• IndexName (string) – The name of an index to query. This index can be any
local secondary index or global secondary index on the table. Note that if you
use the IndexName parameter, you must also provide TableName.
• Select (string) – The attributes to be returned in the result. You can retrieve all
item attributes, specific item attributes, the count of matching items, or in the
case of an index, some or all of the attributes projected into the index.
– ALL_ATTRIBUTES - Returns all of the item attributes from the specified
table or index. If you query a local secondary index, then for each match-
ing item in the index DynamoDB will fetch the entire item from the parent
table. If the index is configured to project all item attributes, then all of
the data can be obtained from the local secondary index, and no fetching
is required.
– ALL_PROJECTED_ATTRIBUTES - Allowed only when querying an in-
dex. Retrieves all attributes that have been projected into the index. If the
index is configured to project all attributes, this return value is equivalent
to specifying ALL_ATTRIBUTES .
– COUNT - Returns the number of matching items, rather than the matching
items themselves.
– SPECIFIC_ATTRIBUTES - Returns only the attributes listed in At-
tributesToGet . This return value is equivalent to specifying AttributesTo-
Get without specifying any value for Select . If you query a local sec-
ondary index and request only attributes that are projected into that index,
the operation will read only the index and not the table. If any of the
requested attributes are not projected into the local secondary index, Dy-
namoDB will fetch each of these attributes from the parent table. This
extra fetching incurs additional throughput cost and latency. If you query
a global secondary index, you can only request attributes that are projected
into the index. Global secondary index queries cannot fetch attributes from
the parent table.
If neither Select nor AttributesToGet are specified, DynamoDB
defaults to ALL_ATTRIBUTES when accessing a table, and
ALL_PROJECTED_ATTRIBUTES when accessing an index. You cannot
use both Select and AttributesToGet together in a single request, unless the
value for Select is SPECIFIC_ATTRIBUTES . (This usage is equivalent to
specifying AttributesToGet without any value for Select .)
Note: If you use the ProjectionExpression parameter, then the value for Select
can only be SPECIFIC_ATTRIBUTES . Any other value for Select will return
an error.
3.1. Services 943
Boto3 Documentation, Release 1.1.4
Warning: This is a legacy parameter, for backward compatibility. New a
plications should use ProjectionExpression instead. Do not combine lega
parameters and expression parameters in a single API call; otherwise, D
• AttributesToGet (list) –
namoDB will return a ValidationException exception.
This parameter allows you to retrieve attributes of type List or Map; howev
it cannot retrieve individual elements within a List or a Map.
The names of one or more attributes to retrieve. If no attribute names are pro-
vided, then all attributes will be returned. If any of the requested attributes are
not found, they will not appear in the result.
Note that AttributesToGet has no effect on provisioned throughput consumption.
DynamoDB determines capacity units consumed based on item size, not on the
amount of data that is returned to an application.
You cannot use both AttributesToGet and Select together in a Query request,
unless the value for Select is SPECIFIC_ATTRIBUTES . (This usage is equiv-
alent to specifying AttributesToGet without any value for Select .)
If you query a local secondary index and request only attributes that are pro-
jected into that index, the operation will read only the index and not the table. If
any of the requested attributes are not projected into the local secondary index,
DynamoDB will fetch each of these attributes from the parent table. This extra
fetching incurs additional throughput cost and latency.
If you query a global secondary index, you can only request attributes that are
projected into the index. Global secondary index queries cannot fetch attributes
from the parent table.
– (string) –
• ConsistentRead (boolean) – Determines the read consistency model: If set to
true , then the operation uses strongly consistent reads; otherwise, the opera-
tion uses eventually consistent reads.
Strongly consistent reads are not supported on global secondary indexes. If you
query a global secondary index with ConsistentRead set to true , you will
receive a ValidationException .
Warning: This is a legacy parameter, for backward compatibility. New
applications should use KeyConditionExpression instead. Do not combin
• KeyConditions (dict) –
legacy parameters and expression parameters in a single API call; otherwis
DynamoDB will return a ValidationException exception.
The selection criteria for the query. For a query on a table, you can have con-
ditions only on the table primary key attributes. You must provide the hash key
attribute name and value as an EQ condition. You can optionally provide a sec-
ond condition, referring to the range key attribute.
Note: If you don’t provide a range key condition, all of the items that match the
hash key will be retrieved. If a FilterExpression or QueryFilter is present, it will
be applied after the items are retrieved.
For a query on an index, you can have conditions only on the index key attributes.
You must provide the index hash attribute name and value as an EQ condition.
You can optionally provide a second condition, referring to the index key range
attribute.
944 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Each KeyConditions element consists of an attribute name to compare, along
with the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the Com-
parisonOperator being used. For type Number, value comparisons are
numeric. String value comparisons for greater than, equals, or less
than are based on ASCII character code values. For example, a is
greater than A , and a is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters . For Bi-
nary, DynamoDB treats each byte of the binary data as unsigned when it
compares binary values.
– ComparisonOperator - A comparator for evaluating attributes, for exam-
ple, equals, greater than, less than, and so on. For KeyConditions , only
the following comparison operators are supported: EQ | LE | LT |
GE | GT | BEGINS_WITH | BETWEEN The following are descrip-
tions of these comparison operators. * EQ : Equal. AttributeValueList can
contain only one AttributeValue of type String, Number, or Binary (not a
set type). If an item contains an AttributeValue element of a different type
than the one specified in the request, the value does not match. For exam-
ple, {"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does
not equal {"NS":["6", "2", "1"]} .
– LE : Less than or equal. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– LT : Less than. AttributeValueList can contain only one AttributeValue of
type String, Number, or Binary (not a set type). If an item contains an
AttributeValue element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type than
the one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
– GT : Greater than. AttributeValueList can contain only one AttributeValue
element of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one pro-
vided in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
– BEGINS_WITH : Checks for a prefix. AttributeValueList can contain only
one AttributeValue of type String or Binary (not a Number or a set type).
The target attribute of the comparison must be of type String or Binary
(not a Number or a set type).
– BETWEEN : Greater than or equal to the first value, and less than or equal
to the second value. AttributeValueList must contain two AttributeValue el-
ements of the same type, either String, Number, or Binary (not a set type).
A target attribute matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If an item con-
3.1. Services 945
Boto3 Documentation, Release 1.1.4
tains an AttributeValue element of a different type than the one provided
in the request, the value does not match. For example, {"S":"6"} does
not compare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see Legacy
Conditional Parameters in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
Represents the selection criteria for a Query or Scan operation:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an in-
dex. For KeyConditions , only the following comparison
operators are supported: EQ | LE | LT | GE | GT |
BEGINS_WITH | BETWEEN Condition is also used in a
QueryFilter , which evaluates the query results and returns
only the desired values.
· For a Scan operation, Condition is used in a ScanFilter ,
which evaluates the scan results and returns only the desired
values.
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
The number of values in the list depends on the Comparison-
Operator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
946 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example, equals,
greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
3.1. Services 947
Boto3 Documentation, Release 1.1.4
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
948 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
For usage examples of AttributeValueList and Comparison-
Operator , see Legacy Conditional Parameters in the Amazon
DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward compatibility. New
applications should use FilterExpression instead. Do not combine legacy
• QueryFilter (dict) –
parameters and expression parameters in a single API call; otherwise, Dy-
namoDB will return a ValidationException exception.
3.1. Services 949
Boto3 Documentation, Release 1.1.4
A condition that evaluates the query results after the items are read and returns
only the desired values.
This parameter does not support attributes of type List or Map.
Note: A QueryFilter is applied after the items have already been read; the
process of filtering does not consume any additional read capacity units.
If you provide more than one condition in the QueryFilter map, then by default
all of the conditions must evaluate to true. In other words, the conditions are
ANDed together. (You can use the ConditionalOperator parameter to OR the
conditions instead. If you do this, then at least one of the conditions must evalu-
ate to true, rather than all of them.)
Note that QueryFilter does not allow key attributes. You cannot define a filter
condition on a hash key or range key.
Each QueryFilter element consists of an attribute name to compare, along with
the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the oper-
ator specified in ComparisonOperator . For type Number, value com-
parisons are numeric. String value comparisons for greater than, equals,
or less than are based on ASCII character code values. For example, a
is greater than A , and a is greater than B . For a list of code values,
see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters . For
type Binary, DynamoDB treats each byte of the binary data as unsigned
when it compares binary values. For information on specifying data types
in JSON, see JSON Data Format in the Amazon DynamoDB Developer
Guide .
– ComparisonOperator - A comparator for evaluating attributes. For
example, equals, greater than, less than, etc. The following com-
parison operators are available: EQ | NE | LE | LT | GE |
GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN For complete descriptions of all
comparison operators, see the Condition data type.
– (string) –
* (dict) –
Represents the selection criteria for a Query or Scan operation:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an in-
dex. For KeyConditions , only the following comparison
operators are supported: EQ | LE | LT | GE | GT |
BEGINS_WITH | BETWEEN Condition is also used in a
QueryFilter , which evaluates the query results and returns
only the desired values.
· For a Scan operation, Condition is used in a ScanFilter ,
which evaluates the scan results and returns only the desired
values.
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
The number of values in the list depends on the Comparison-
Operator being used.
950 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
3.1. Services 951
Boto3 Documentation, Release 1.1.4
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example, equals,
greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
952 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
3.1. Services 953
Boto3 Documentation, Release 1.1.4
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
For usage examples of AttributeValueList and Comparison-
Operator , see Legacy Conditional Parameters in the Amazon
DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward compatibi
applications should use FilterExpression instead. Do not comb
• ConditionalOperator (string) –
parameters and expression parameters in a single API call; other
namoDB will return a ValidationException exception.
A logical operator to apply to the conditions in a QueryFilter map:
– AND - If all of the conditions evaluate to true, then the entire map evaluates
to true.
– OR - If at least one of the conditions evaluate to true, then the entire map
evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ScanIndexForward (boolean) – Specifies the order in which to return the query
results - either ascending (true ) or descending (false ).
Items with the same hash key are stored in sorted order by range key .If the range
key data type is Number, the results are stored in numeric order. For type String,
the results are returned in order of ASCII character code values. For type Binary,
DynamoDB treats each byte of the binary data as unsigned.
If ScanIndexForward is true , DynamoDB returns the results in order, by range
key. This is the default behavior.
If ScanIndexForward is false , DynamoDB sorts the results in descending
order by range key, and then returns the results to the client.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
954 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ProjectionExpression (string) – A string that identifies one or more attributes to
retrieve from the table. These attributes can include scalars, sets, or elements of a
JSON document. The attributes in the expression must be separated by commas.
If no attribute names are specified, then all attributes will be returned. If any of
the requested attributes are not found, they will not appear in the result.
For more information, see Accessing Item Attributes in the Amazon DynamoDB
Developer Guide .
Note: ProjectionExpression replaces the legacy AttributesToGet parameter.
• FilterExpression (string) – A string that contains conditions that DynamoDB
applies after the Query operation, but before the data is returned to you. Items
that do not satisfy the FilterExpression criteria are not returned.
Note: A FilterExpression is applied after the items have already been read; the
process of filtering does not consume any additional read capacity units.
For more information, see Filter Expressions in the Amazon DynamoDB Devel-
oper Guide .
Note: FilterExpression replaces the legacy QueryFilter and ConditionalOpera-
tor parameters.
• KeyConditionExpression (string) – The condition that specifies the key
value(s) for items to be retrieved by the Query action.
The condition must perform an equality test on a single hash key value. The
condition can also perform one of several comparison tests on a single range key
value. Query can use KeyConditionExpression to retrieve one item with a given
hash and range key value, or several items that have the same hash key value but
different range key values.
The hash key equality test is required, and must be specified in the following
format:
hashAttributeName = :hashval
If you also want to provide a range key condition, it must be combined using
AND with the hash key condition. Following is an example, using the = compar-
ison operator for the range key:
hashAttributeName = :hashval AND
rangeAttributeName = :rangeval
Valid comparisons for the range key condition are as follows:
– rangeAttributeName = :rangeval - true if the range key is equal
to :rangeval .
– rangeAttributeName ** :rangeval - true if the range key is less
than :rangeval .
– rangeAttributeName = :rangeval - true if the range key is less
3.1. Services 955
Boto3 Documentation, Release 1.1.4
than or equal to :rangeval .
– rangeAttributeName ** :rangeval - true if the range key is
greater than :rangeval .
– rangeAttributeName = :rangeval - true if the range key is
greater than or equal to :rangeval .
– rangeAttributeName BETWEEN :rangeval1 AND
:rangeval2 - true if the range key is greater than or equal to
:rangeval1 , and less than or equal to :rangeval2 .
– begins_with ( rangeAttributeName , :rangeval ) - true if the
range key begins with a particular operand. (You cannot use this func-
tion with a range key that is of type Number.) Note that the function name
begins_with is case-sensitive.
Use the ExpressionAttributeValues parameter to replace tokens such as
:hashval and :rangeval with actual values at runtime.
You can optionally use the ExpressionAttributeNames parameter to replace the
names of the hash and range attributes with placeholder tokens. This option
might be necessary if an attribute name conflicts with a DynamoDB reserved
word. For example, the following KeyConditionExpression parameter causes an
error because Size is a reserved word:
– Size = :myval
To work around this, define a placeholder (such a #S ) to represent the attribute
name Size . KeyConditionExpression then is as follows:
– #S = :myval
For a list of reserved words, see Reserved Words in the Amazon DynamoDB
Developer Guide .
For more information on ExpressionAttributeNames and ExpressionAttributeVal-
ues , see Using Placeholders for Attribute Names and Values in the Amazon Dy-
namoDB Developer Guide .
Note: KeyConditionExpression replaces the legacy KeyConditions parameter.
• ExpressionAttributeNames (dict) – One or more substitution tokens for at-
tribute names in an expression. The following are some use cases for using
ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB reserved
word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
956 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be substituted
in an expression.
Use the : (colon) character in an expression to dereference an attribute value.
For example, suppose that you wanted to check whether the value of the Prod-
uctStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Conditions
in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
3.1. Services 957
Boto3 Documentation, Release 1.1.4
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'Items': [
{
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
958 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
],
'Count': 123,
'ScannedCount': 123,
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
'NextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a Query operation.
– Items (list) –
An array of item attributes that match the query criteria. Each element in
this array consists of an attribute name and the value for that attribute.
* (dict) –
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
3.1. Services 959
Boto3 Documentation, Release 1.1.4
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– Count (integer) –
The number of items in the response.
If you used a QueryFilter in the request, then Count is the number of items
returned after the filter was applied, and ScannedCount is the number of
matching items beforethe filter was applied.
If you did not use a filter in the request, then Count and ScannedCount are
the same.
– ScannedCount (integer) –
960 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The number of items evaluated, before any QueryFilter is applied. A high
ScannedCount value with few, or no, Count results indicates an inefficient
Query operation. For more information, see Count and ScannedCount in
the Amazon DynamoDB Developer Guide .
If you did not use a filter in the request, then ScannedCount is the same as
Count .
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned includes
the total provisioned throughput consumed, along with statistics for the ta-
ble and any indexes involved in the operation. ConsumedCapacity is only
returned if the request asked for it. For more information, see Provisioned
Throughput in the Amazon DynamoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the operation.
* Table (dict) –
The amount of throughput consumed on the table affected by the
operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
– NextToken (string) –
A token to resume pagination.
class DynamoDB.Paginator.Scan
3.1. Services 961
Boto3 Documentation, Release 1.1.4
paginator = client.get_paginator('scan')
paginate(**kwargs)
Creates an iterator that will paginate through responses from DynamoDB.Client.scan().
Request Syntax
response_iterator = paginator.paginate(
TableName='string',
IndexName='string',
AttributesToGet=[
'string',
],
Select='ALL_ATTRIBUTES'|'ALL_PROJECTED_ATTRIBUTES'|'SPECIFIC_ATTRIBUTES'|'COUNT',
ScanFilter={
'string': {
'AttributeValueList': [
{
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
},
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NULL'|'N
}
},
ConditionalOperator='AND'|'OR',
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
TotalSegments=123,
Segment=123,
ProjectionExpression='string',
FilterExpression='string',
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
962 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
ConsistentRead=True|False,
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• TableName (string) – [REQUIRED]
The name of the table containing the requested items; or, if you provide
IndexName , the name of the table to which that index belongs.
• IndexName (string) – The name of a secondary index to scan. This index can
be any local secondary index or global secondary index. Note that if you use the
IndexName parameter, you must also provide TableName .
Warning: This is a legacy parameter, for backward compatibility. New a
plications should use ProjectionExpression instead. Do not combine lega
parameters and expression parameters in a single API call; otherwise, D
• AttributesToGet (list) –
namoDB will return a ValidationException exception.
This parameter allows you to retrieve attributes of type List or Map; howev
it cannot retrieve individual elements within a List or a Map.
The names of one or more attributes to retrieve. If no attribute names are pro-
vided, then all attributes will be returned. If any of the requested attributes are
not found, they will not appear in the result.
Note that AttributesToGet has no effect on provisioned throughput consumption.
DynamoDB determines capacity units consumed based on item size, not on the
amount of data that is returned to an application.
– (string) –
• Select (string) – The attributes to be returned in the result. You can retrieve all
item attributes, specific item attributes, or the count of matching items.
– ALL_ATTRIBUTES - Returns all of the item attributes.
– COUNT - Returns the number of matching items, rather than the matching
items themselves.
– SPECIFIC_ATTRIBUTES - Returns only the attributes listed in At-
tributesToGet . This return value is equivalent to specifying AttributesTo-
3.1. Services 963
Boto3 Documentation, Release 1.1.4
Get without specifying any value for Select .
If neither Select nor AttributesToGet are specified, DynamoDB defaults to
ALL_ATTRIBUTES . You cannot use both AttributesToGet and Select together
in a single request, unless the value for Select is SPECIFIC_ATTRIBUTES
. (This usage is equivalent to specifying AttributesToGet without any value for
Select .)
Warning: This is a legacy parameter, for backward compatibility. New
applications should use FilterExpression instead. Do not combine legacy
• ScanFilter (dict) –
parameters and expression parameters in a single API call; otherwise, Dy-
namoDB will return a ValidationException exception.
A condition that evaluates the scan results and returns only the desired values.
Note: This parameter does not support attributes of type List or Map.
If you specify more than one condition in the ScanFilter map, then by default all
of the conditions must evaluate to true. In other words, the conditions are ANDed
together. (You can use the ConditionalOperator parameter to OR the conditions
instead. If you do this, then at least one of the conditions must evaluate to true,
rather than all of them.)
Each ScanFilter element consists of an attribute name to compare, along with
the following:
– AttributeValueList - One or more values to evaluate against the sup-
plied attribute. The number of values in the list depends on the oper-
ator specified in ComparisonOperator . For type Number, value com-
parisons are numeric. String value comparisons for greater than, equals,
or less than are based on ASCII character code values. For example,
a is greater than A , and a is greater than B . For a list of code val-
ues, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters .
For Binary, DynamoDB treats each byte of the binary data as unsigned
when it compares binary values. For information on specifying data types
in JSON, see JSON Data Format in the Amazon DynamoDB Developer
Guide .
– ComparisonOperator - A comparator for evaluating attributes. For
example, equals, greater than, less than, etc. The following com-
parison operators are available: EQ | NE | LE | LT | GE |
GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN For complete descriptions of all
comparison operators, see Condition .
– (string) –
* (dict) –
Represents the selection criteria for a Query or Scan operation:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an in-
dex. For KeyConditions , only the following comparison
operators are supported: EQ | LE | LT | GE | GT |
BEGINS_WITH | BETWEEN Condition is also used in a
QueryFilter , which evaluates the query results and returns
only the desired values.
· For a Scan operation, Condition is used in a ScanFilter ,
which evaluates the scan results and returns only the desired
values.
964 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· AttributeValueList (list) –
One or more values to evaluate against the supplied attribute.
The number of values in the list depends on the Comparison-
Operator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals, or
less than are based on ASCII character code val-
ues. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
3.1. Services 965
Boto3 Documentation, Release 1.1.4
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example, equals,
greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT | NOT_NULL
| NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN
The following are descriptions of each comparison operator.
· EQ : Equal. EQ is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one Attribute-
Value element of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value element of a different type than the one provided in the
request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, includ-
ing lists and maps. AttributeValueList can contain only one
AttributeValue of type String, Number, Binary, String Set,
Number Set, or Binary Set. If an item contains an Attribute-
Value of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can contain only
one AttributeValue element of type String, Number, or Binary
(not a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set
966 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
type). If an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the value
does not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an AttributeValue
element of a different type than the one provided in the re-
quest, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not
compare to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only one At-
tributeValue element of type String, Number, or Binary (not
a set type). If an item contains an AttributeValue element
of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not
equal {"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is supported
for all datatypes, including lists and maps. .. note::This op-
erator tests for the existence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NOT_NULL , the result is a Boolean true . This result is
because the attribute “a ” exists; its data type is not relevant
to the NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported for
all datatypes, including lists and maps. .. note::This operator
tests for the nonexistence of an attribute, not its data type.
If the data type of attribute “a ” is null, and you evaluate it
using NULL , the result is a Boolean false . This is because
the attribute “a ” exists; its data type is not relevant to the
NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element
of type String, Number, or Binary (not a set type). If the
target attribute of the comparison is of type String, then the
operator checks for a substring match. If the target attribute
of the comparison is of type Binary, then the operator looks
for a subsequence of the target that matches the input. If the
target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is supported
for lists: When evaluating “a CONTAINS b ”, “a ” can be
a list; however, “b ” cannot be a set, a map, or a list.
· NOT_CONTAINS : Checks for absence of a subsequence, or
absence of a value in a set. AttributeValueList can contain
only one AttributeValue element of type String, Number, or
Binary (not a set type). If the target attribute of the compar-
ison is a String, then the operator checks for the absence of
a substring match. If the target attribute of the comparison
is Binary, then the operator checks for the absence of a sub-
sequence of the target that matches the input. If the target
attribute of the comparison is a set (“SS ”, “NS ”, or “BS ”),
3.1. Services 967
Boto3 Documentation, Release 1.1.4
then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is sup-
ported for lists: When evaluating “a NOT CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map, or a
list.
· BEGINS_WITH : Checks for a prefix. AttributeValueList can
contain only one AttributeValue of type String or Binary (not a
Number or a set type). The target attribute of the comparison
must be of type String or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. Attribute-
ValueList can contain one or more AttributeValue elements of
type String, Number, or Binary (not a set type). These at-
tributes are compared against an existing set type attribute of
an item. If any elements of the input set are present in the
item attribute, the expression evaluates to true.
· BETWEEN : Greater than or equal to the first value, and less
than or equal to the second value. AttributeValueList must
contain two AttributeValue elements of the same type, either
String, Number, or Binary (not a set type). A target attribute
matches if the target value is greater than, or equal to, the
first element and less than, or equal to, the second element. If
an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not compare to {"N":"6"}
. Also, {"N":"6"} does not compare to {"NS":["6",
"2", "1"]}
For usage examples of AttributeValueList and Comparison-
Operator , see Legacy Conditional Parameters in the Amazon
DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward compatibi
applications should use FilterExpression instead. Do not comb
• ConditionalOperator (string) –
parameters and expression parameters in a single API call; other
namoDB will return a ValidationException exception.
A logical operator to apply to the conditions in a ScanFilter map:
– AND - If all of the conditions evaluate to true, then the entire map evaluates
to true.
– OR - If at least one of the conditions evaluate to true, then the entire map
evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
968 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• TotalSegments (integer) – For a parallel Scan request, TotalSegments represents
the total number of segments into which the Scan operation will be divided. The
value of TotalSegments corresponds to the number of application workers that
will perform the parallel scan. For example, if you want to use four application
threads to scan a table or an index, specify a TotalSegments value of 4.
The value for TotalSegments must be greater than or equal to 1, and less than or
equal to 1000000. If you specify a TotalSegments value of 1, the Scan operation
will be sequential rather than parallel.
If you specify TotalSegments , you must also specify Segment .
• Segment (integer) – For a parallel Scan request, Segment identifies an individual
segment to be scanned by an application worker.
Segment IDs are zero-based, so the first segment is always 0. For example, if
you want to use four application threads to scan a table or an index, then the first
thread specifies a Segment value of 0, the second thread specifies 1, and so on.
The value of LastEvaluatedKey returned from a parallel Scan request must be
used as ExclusiveStartKey with the same segment ID in a subsequent Scan oper-
ation.
The value for Segment must be greater than or equal to 0, and less than the value
provided for TotalSegments .
If you provide Segment , you must also provide TotalSegments .
• ProjectionExpression (string) – A string that identifies one or more attributes
to retrieve from the specified table or index. These attributes can include scalars,
sets, or elements of a JSON document. The attributes in the expression must be
separated by commas.
If no attribute names are specified, then all attributes will be returned. If any of
the requested attributes are not found, they will not appear in the result.
For more information, see Accessing Item Attributes in the Amazon DynamoDB
Developer Guide .
Note: ProjectionExpression replaces the legacy AttributesToGet parameter.
• FilterExpression (string) – A string that contains conditions that DynamoDB
applies after the Scan operation, but before the data is returned to you. Items that
do not satisfy the FilterExpression criteria are not returned.
Note: A FilterExpression is applied after the items have already been read; the
process of filtering does not consume any additional read capacity units.
For more information, see Filter Expressions in the Amazon DynamoDB Devel-
oper Guide .
Note: FilterExpression replaces the legacy ScanFilter and ConditionalOperator
parameters.
• ExpressionAttributeNames (dict) – One or more substitution tokens for at-
tribute names in an expression. The following are some use cases for using
ExpressionAttributeNames :
3.1. Services 969
Boto3 Documentation, Release 1.1.4
– To access an attribute whose name conflicts with a DynamoDB reserved
word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be substituted
in an expression.
Use the : (colon) character in an expression to dereference an attribute value.
For example, suppose that you wanted to check whether the value of the Prod-
uctStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Conditions
in the Amazon DynamoDB Developer Guide .
– (string) –
* (dict) –
Represents the data for an attribute. You can set one, and only one,
of the elements.
Each attribute in an item is a name-value pair. An attribute can be
single-valued or multi-valued set. For example, a book item can
have title and authors attributes. Each book has one title but can
have many authors. The multi-valued attribute is a set; duplicate
values are not allowed.
· S (string) –
A String data type.
· N (string) –
970 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
• ConsistentRead (boolean) – A Boolean value that determines the read consis-
tency model during the scan:
– If ConsistentRead is false , then Scan will use eventually consistent
reads. The data returned from Scan might not contain the results of other
recently completed write operations (PutItem, UpdateItem or DeleteItem).
The Scan response might include some stale data.
– If ConsistentRead is true , then Scan will use strongly consistent reads.
All of the write operations that completed before the Scan began are guar-
anteed to be contained in the Scan response.
The default setting for ConsistentRead is false , meaning that eventually con-
sistent reads will be used.
3.1. Services 971
Boto3 Documentation, Release 1.1.4
Strongly consistent reads are not supported on global secondary indexes. If you
scan a global secondary index with ConsistentRead set to true, you will receive
a ValidationException .
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'Items': [
{
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
],
'Count': 123,
'ScannedCount': 123,
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
972 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
'NextToken': 'string'
}
Response Structure
• (dict) –
Represents the output of a Scan operation.
– Items (list) –
An array of item attributes that match the scan criteria. Each element in
this array consists of an attribute name and the value for that attribute.
* (dict) –
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map of attribute values.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
3.1. Services 973
Boto3 Documentation, Release 1.1.4
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List of attribute values.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
– Count (integer) –
The number of items in the response.
If you set ScanFilter in the request, then Count is the number of items
returned after the filter was applied, and ScannedCount is the number of
matching items before the filter was applied.
If you did not use a filter in the request, then Count is the same as Scanned-
Count .
– ScannedCount (integer) –
The number of items evaluated, before any ScanFilter is applied. A high
ScannedCount value with few, or no, Count results indicates an inefficient
Scan operation. For more information, see Count and ScannedCount in
the Amazon DynamoDB Developer Guide .
If you did not use a filter in the request, then ScannedCount is the same as
Count .
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned includes
the total provisioned throughput consumed, along with statistics for the ta-
ble and any indexes involved in the operation. ConsumedCapacity is only
returned if the request asked for it. For more information, see Provisioned
Throughput in the Amazon DynamoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the operation.
* Table (dict) –
The amount of throughput consumed on the table affected by the
operation.
974 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index affected
by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
– NextToken (string) –
A token to resume pagination.
Waiters
The available waiters are:
• DynamoDB.Waiter.TableExists
• DynamoDB.Waiter.TableNotExists
class DynamoDB.Waiter.TableExists
waiter = client.get_waiter('table_exists')
wait(**kwargs)
Polls DynamoDB.Client.describe_table() every 20 seconds until a successful state is reached.
An error is returned after 25 failed checks.
Request Syntax
waiter.wait(
TableName='string'
)
Parameters TableName (string) – [REQUIRED]
The name of the table to describe.
3.1. Services 975
Boto3 Documentation, Release 1.1.4
Returns None
class DynamoDB.Waiter.TableNotExists
waiter = client.get_waiter('table_not_exists')
wait(**kwargs)
Polls DynamoDB.Client.describe_table() every 20 seconds until a successful state is reached.
An error is returned after 25 failed checks.
Request Syntax
waiter.wait(
TableName='string'
)
Parameters TableName (string) – [REQUIRED]
The name of the table to describe.
Returns None
Service Resource
class DynamoDB.ServiceResource
A resource representing Amazon DynamoDB:
import boto3
dynamodb = boto3.resource('dynamodb')
These are the resource’s available actions:
•batch_get_item()
•batch_write_item()
•create_table()
These are the resource’s available sub-resources:
•Table()
These are the resource’s available collections:
•tables
Actions
Actions call operations on resources. They may automatically handle the passing in of arguments set from
identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.
batch_get_item(**kwargs)
The BatchGetItem operation returns the attributes of one or more items from one or more tables. You
identify requested items by primary key.
A single operation can retrieve up to 16 MB of data, which can contain as many as 100 items.
BatchGetItem will return a partial result if the response size limit is exceeded, the table’s provisioned
throughput is exceeded, or an internal processing failure occurs. If a partial result is returned, the opera-
tion returns a value for UnprocessedKeys . You can use this value to retry the operation starting with the
next item to get.
Warning: If you request more than 100 items BatchGetItem will return a ValidationException with
the message “Too many items requested for the BatchGetItem call”.
976 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
For example, if you ask to retrieve 100 items, but each individual item is 300 KB in size, the system
returns 52 items (so as not to exceed the 16 MB limit). It also returns an appropriate UnprocessedKeys
value so you can get the next page of results. If desired, your application can include its own logic to
assemble the pages of results into one data set.
If none of the items can be processed due to insufficient provisioned throughput on all of the tables in the
request, then BatchGetItem will return a ProvisionedThroughputExceededException . If at least one of
the items is successfully processed, then BatchGetItem completes successfully, while returning the keys
of the unread items in UnprocessedKeys .
Warning: If DynamoDB returns any unprocessed items, you should retry the batch operation on
those items. However, we strongly recommend that you use an exponential backoff algorithm . If
you retry the batch operation immediately, the underlying read or write requests can still fail due to
throttling on the individual tables. If you delay the batch operation using exponential backoff, the
individual requests in the batch are much more likely to succeed.
For more information, see Batch Operations and Error Handling in the Amazon DynamoDB Developer
Guide .
By default, BatchGetItem performs eventually consistent reads on every table in the request. If you want
strongly consistent reads instead, you can set ConsistentRead to true for any or all tables.
In order to minimize response latency, BatchGetItem retrieves items in parallel.
When designing your application, keep in mind that DynamoDB does not return attributes in any particular
order. To help parse the response by item, include the primary key values for the items in your request in
the AttributesToGet parameter.
If a requested item does not exist, it is not returned in the result. Requests for nonexistent items consume
the minimum read capacity units according to the type of read. For more information, see Capacity Units
Calculations in the Amazon DynamoDB Developer Guide .
Request Syntax
response = dynamodb.batch_get_item(
RequestItems={
'string': {
'Keys': [
{
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([1
},
],
'AttributesToGet': [
'string',
],
'ConsistentRead': True|False,
'ProjectionExpression': 'string',
'ExpressionAttributeNames': {
'string': 'string'
}
}
},
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE'
)
Parameters
• RequestItems (dict) – [REQUIRED]
A map of one or more table names and, for each table, a map that describes one
or more items to retrieve from that table. Each table name can be used only once
3.1. Services 977
Boto3 Documentation, Release 1.1.4
per BatchGetItem request.
Each element in the map of items to retrieve consists of the following:
– ConsistentRead - If true , a strongly consistent read is used; if false
(the default), an eventually consistent read is used.
– ExpressionAttributeNames - One or more substitution tokens for attribute
names in the ProjectionExpression parameter. The following are some use
cases for using ExpressionAttributeNames : * To access an attribute whose
name conflicts with a DynamoDB reserved word.
– To create a placeholder for repeating occurrences of an attribute name in
an expression.
– To prevent special characters in an attribute name from being misinter-
preted in an expression.
Use the # character in an expression to dereference an attribute name. For exam-
ple, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be used
directly in an expression. (For the complete list of reserved words, see Reserved
Words in the Amazon DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute values ,
which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item At-
tributes in the Amazon DynamoDB Developer Guide .
– Keys - An array of primary key attribute values that define specific items in
the table. For each primary key, you must provide all of the key attributes.
For example, with a hash type primary key, you only need to provide the
hash attribute. For a hash-and-range type primary key, you must provide
both the hash attribute and the range attribute.
– ProjectionExpression - A string that identifies one or more attributes to re-
trieve from the table. These attributes can include scalars, sets, or elements
of a JSON document. The attributes in the expression must be separated
by commas. If no attribute names are specified, then all attributes will be
returned. If any of the requested attributes are not found, they will not
appear in the result. For more information, see Accessing Item Attributes
in the Amazon DynamoDB Developer Guide .
– AttributesToGet - .. warning:: This is a legacy parameter, for backward
compatibility. New applications should use ProjectionExpression instead.
Do not combine legacy parameters and expression parameters in a single
API call; otherwise, DynamoDB will return a ValidationException excep-
tion. This parameter allows you to retrieve attributes of type List or Map;
however, it cannot retrieve individual elements within a List or a Map. The
names of one or more attributes to retrieve. If no attribute names are pro-
vided, then all attributes will be returned. If any of the requested attributes
are not found, they will not appear in the result. Note that AttributesToGet
has no effect on provisioned throughput consumption. DynamoDB deter-
mines capacity units consumed based on item size, not on the amount of
data that is returned to an application.
– (string) –
978 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* (dict) –
Represents a set of primary keys and, for each key, the attributes to
retrieve from the table.
For each primary key, you must provide all of the key attributes. For
example, with a hash type primary key, you only need to provide
the hash attribute. For a hash-and-range type primary key, you must
provide both the hash attribute and the range attribute.
· Keys (list) – [REQUIRED]
The primary key attribute values that define the items and the
attributes associated with the items.
· (dict) –
· (string) –
· (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
· AttributesToGet (list) –
One or more attributes to retrieve from the table or index. If
no attribute names are specified then all attributes will be re-
turned. If any of the specified attributes are not found, they
will not appear in the result.
· (string) –
· ConsistentRead (boolean) –
The consistency of a read operation. If set to true , then
a strongly consistent read is used; otherwise, an eventually
consistent read is used.
· ProjectionExpression (string) –
A string that identifies one or more attributes to retrieve from
the table. These attributes can include scalars, sets, or ele-
ments of a JSON document. The attributes in the Projection-
Expression must be separated by commas.
If no attribute names are specified, then all attributes will be
returned. If any of the requested attributes are not found, they
will not appear in the result.
For more information, see Accessing Item Attributes in the
Amazon DynamoDB Developer Guide .
Note: ProjectionExpression replaces the legacy At-
tributesToGet parameter.
· ExpressionAttributeNames (dict) –
One or more substitution tokens for attribute names in an ex-
pression. The following are some use cases for using Expres-
sionAttributeNames :
· To access an attribute whose name conflicts with a Dy-
namoDB reserved word.
· To create a placeholder for repeating occurrences of an at-
tribute name in an expression.
· To prevent special characters in an attribute name from being
misinterpreted in an expression.
3.1. Services 979
Boto3 Documentation, Release 1.1.4
Use the # character in an expression to dereference an at-
tribute name. For example, consider the following attribute
name:
· Percentile
The name of this attribute conflicts with a reserved word, so
it cannot be used directly in an expression. (For the complete
list of reserved words, see Reserved Words in the Amazon
DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
· {"#P":"Percentile"}
You could then use this substitution in an expression, as in
this example:
· #P = :val
Note: Tokens that begin with the : character are expression
attribute values , which are placeholders for the actual value
at runtime.
For more information on expression attribute names, see Ac-
cessing Item Attributes in the Amazon DynamoDB Developer
Guide .
· (string) –
· (string) –
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
Return type dict
Returns
Response Syntax
{
'Responses': {
'string': [
{
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|
},
]
},
'UnprocessedKeys': {
'string': {
'Keys': [
{
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string
},
],
'AttributesToGet': [
'string',
980 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'ConsistentRead': True|False,
'ProjectionExpression': 'string',
'ExpressionAttributeNames': {
'string': 'string'
}
}
},
'ConsumedCapacity': [
{
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
]
}
Response Structure
• (dict) –
Represents the output of a BatchGetItem operation.
– Responses (dict) –
A map of table name to a list of items. Each object in Responses consists
of a table name, along with a map of attribute data consisting of the data
type and attribute value.
* (string) –
· (list) –
· (dict) –
· (string) –
· (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
– UnprocessedKeys (dict) –
A map of tables and their respective keys that were not processed with
the current response. The UnprocessedKeys value is in the same form
as RequestItems , so the value can be provided directly to a subsequent
BatchGetItem operation. For more information, see RequestItems in the
Request Parameters section.
Each element consists of:
* Keys - An array of primary key attribute values that define specific
items in the table.
* AttributesToGet - One or more attributes to be retrieved from the
table or index. By default, all attributes are returned. If a requested
3.1. Services 981
Boto3 Documentation, Release 1.1.4
attribute is not found, it does not appear in the result.
* ConsistentRead - The consistency of a read operation. If set to
true , then a strongly consistent read is used; otherwise, an even-
tually consistent read is used.
If there are no unprocessed keys remaining, the response contains an
empty UnprocessedKeys map.
* (string) –
· (dict) –
Represents a set of primary keys and, for each key, the at-
tributes to retrieve from the table.
For each primary key, you must provide all of the key at-
tributes. For example, with a hash type primary key, you only
need to provide the hash attribute. For a hash-and-range type
primary key, you must provide both the hash attribute and the
range attribute.
· Keys (list) –
The primary key attribute values that define the items and the
attributes associated with the items.
· (dict) –
· (string) –
· (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
· AttributesToGet (list) –
One or more attributes to retrieve from the table or index. If
no attribute names are specified then all attributes will be re-
turned. If any of the specified attributes are not found, they
will not appear in the result.
· (string) –
· ConsistentRead (boolean) –
The consistency of a read operation. If set to true , then
a strongly consistent read is used; otherwise, an eventually
consistent read is used.
· ProjectionExpression (string) –
A string that identifies one or more attributes to retrieve from
the table. These attributes can include scalars, sets, or ele-
ments of a JSON document. The attributes in the Projection-
Expression must be separated by commas.
If no attribute names are specified, then all attributes will be
returned. If any of the requested attributes are not found, they
will not appear in the result.
For more information, see Accessing Item Attributes in the
Amazon DynamoDB Developer Guide .
Note: ProjectionExpression replaces the legacy At-
tributesToGet parameter.
· ExpressionAttributeNames (dict) –
One or more substitution tokens for attribute names in an ex-
pression. The following are some use cases for using Expres-
982 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
sionAttributeNames :
· To access an attribute whose name conflicts with a Dy-
namoDB reserved word.
· To create a placeholder for repeating occurrences of an at-
tribute name in an expression.
· To prevent special characters in an attribute name from being
misinterpreted in an expression.
Use the # character in an expression to dereference an at-
tribute name. For example, consider the following attribute
name:
· Percentile
The name of this attribute conflicts with a reserved word, so
it cannot be used directly in an expression. (For the complete
list of reserved words, see Reserved Words in the Amazon
DynamoDB Developer Guide ). To work around this, you
could specify the following for ExpressionAttributeNames :
· {"#P":"Percentile"}
You could then use this substitution in an expression, as in
this example:
· #P = :val
Note: Tokens that begin with the : character are expression
attribute values , which are placeholders for the actual value
at runtime.
For more information on expression attribute names, see Ac-
cessing Item Attributes in the Amazon DynamoDB Developer
Guide .
· (string) –
· (string) –
– ConsumedCapacity (list) –
The read capacity units consumed by the operation.
Each element consists of:
* TableName - The table that consumed the provisioned throughput.
* CapacityUnits - The total number of capacity units consumed.
* (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
· TableName (string) –
The name of the table that was affected by the operation.
· CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
· Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
3.1. Services 983
Boto3 Documentation, Release 1.1.4
The total number of capacity units consumed on a table or an
index.
· LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
· GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
batch_write_item(**kwargs)
The BatchWriteItem operation puts or deletes multiple items in one or more tables. A single call to
BatchWriteItem can write up to 16 MB of data, which can comprise as many as 25 put or delete requests.
Individual items to be written can be as large as 400 KB.
Note: BatchWriteItem cannot update items. To update items, use the UpdateItem API.
The individual PutItem and DeleteItem operations specified in BatchWriteItem are atomic; however Batch-
WriteItem as a whole is not. If any requested operations fail because the table’s provisioned throughput
is exceeded or an internal processing failure occurs, the failed operations are returned in the Unpro-
cessedItems response parameter. You can investigate and optionally resend the requests. Typically, you
would call BatchWriteItem in a loop. Each iteration would check for unprocessed items and submit a new
BatchWriteItem request with those unprocessed items until all items have been processed.
Note that if none of the items can be processed due to insufficient provisioned throughput on all of the
tables in the request, then BatchWriteItem will return a ProvisionedThroughputExceededException .
Warning: If DynamoDB returns any unprocessed items, you should retry the batch operation on
those items. However, we strongly recommend that you use an exponential backoff algorithm . If
you retry the batch operation immediately, the underlying read or write requests can still fail due to
throttling on the individual tables. If you delay the batch operation using exponential backoff, the
individual requests in the batch are much more likely to succeed.
For more information, see Batch Operations and Error Handling in the Amazon DynamoDB Developer
Guide .
With BatchWriteItem , you can efficiently write or delete large amounts of data, such as from Amazon
Elastic MapReduce (EMR), or copy data from another database into DynamoDB. In order to improve
performance with these large-scale operations, BatchWriteItem does not behave in the same way as indi-
984 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
vidual PutItem and DeleteItem calls would. For example, you cannot specify conditions on individual put
and delete requests, and BatchWriteItem does not return deleted items in the response.
If you use a programming language that supports concurrency, you can use threads to write items in
parallel. Your application must include the necessary logic to manage the threads. With languages that
don’t support threading, you must update or delete the specified items one at a time. In both situations,
BatchWriteItem provides an alternative where the API performs the specified put and delete operations in
parallel, giving you the power of the thread pool approach without having to introduce complexity into
your application.
Parallel processing reduces latency, but each specified put and delete request consumes the same number
of write capacity units whether it is processed in parallel or not. Delete operations on nonexistent items
consume one write capacity unit.
If one or more of the following is true, DynamoDB rejects the entire batch write operation:
•One or more tables specified in the BatchWriteItem request does not exist.
•Primary key attributes specified on an item in the request do not match those in the corresponding
table’s primary key schema.
•You try to perform multiple operations on the same item in the same BatchWriteItem request. For
example, you cannot put and delete the same item in the same BatchWriteItem request.
•There are more than 25 requests in the batch.
•Any individual item in a batch exceeds 400 KB.
•The total request size exceeds 16 MB.
Request Syntax
response = dynamodb.batch_write_item(
RequestItems={
'string': [
{
'PutRequest': {
'Item': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|se
}
},
'DeleteRequest': {
'Key': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|se
}
}
},
]
},
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ReturnItemCollectionMetrics='SIZE'|'NONE'
)
Parameters
• RequestItems (dict) – [REQUIRED]
A map of one or more table names and, for each table, a list of operations to be
performed (DeleteRequest or PutRequest ). Each element in the map consists of
the following:
– DeleteRequest - Perform a DeleteItem operation on the specified item. The
item to be deleted is identified by a Key subelement: * Key - A map of
primary key attribute values that uniquely identify the ! item. Each entry
in this map consists of an attribute name and an attribute value. For each
primary key, you must provide all of the key attributes. For example, with
a hash type primary key, you only need to provide the hash attribute. For a
3.1. Services 985
Boto3 Documentation, Release 1.1.4
hash-and-range type primary key, you must provide both the hash attribute
and the range attribute.
– PutRequest - Perform a PutItem operation on the specified item. The item
to be put is identified by an Item subelement: * Item - A map of attributes
and their values. Each entry in this map consists of an attribute name and
an attribute value. Attribute values must not be null; string and binary type
attributes must have lengths greater than zero; and set type attributes must
not be empty. Requests that contain empty values will be rejected with a
ValidationException exception. If you specify any attributes that are part
of an index key, then the data types for those attributes must match those
of the schema in the table’s attribute definition.
– (string) –
* (list) –
· (dict) –
Represents an operation to perform - either DeleteItem or
PutItem . You can only request one of these operations, not
both, in a single WriteRequest . If you do need to perform
both of these operations, you will need to provide two sepa-
rate WriteRequest objects.
· PutRequest (dict) –
A request to perform a PutItem operation.
· Item (dict) – [REQUIRED]
A map of attribute name to attribute values, representing the
primary key of an item to be processed by PutItem . All of
the table’s primary key attributes must be specified, and their
data types must match those of the table’s key schema. If any
attributes are present in the item which are part of an index
key schema for the table, their types must match the index
key schema.
· (string) –
· (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
· DeleteRequest (dict) –
A request to perform a DeleteItem operation.
· Key (dict) – [REQUIRED]
A map of attribute name to attribute values, representing the
primary key of the item to delete. All of the table’s primary
key attributes must be specified, and their data types must
match those of the table’s key schema.
· (string) –
· (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
• ReturnConsumedCapacity (string) – Determines the level of detail about pro-
visioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapacity for
the operation, together with ConsumedCapacity for each table and sec-
ondary index that was accessed. Note that some operations, such as
GetItem and BatchGetItem , do not access any indexes at all. In these
cases, specifying INDEXES will only return ConsumedCapacity informa-
986 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
tion for table(s).
– TOTAL - The response includes only the aggregate ConsumedCapacity for
the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ReturnItemCollectionMetrics (string) – Determines whether item collection
metrics are returned. If set to SIZE , the response includes statistics about item
collections, if any, that were modified during the operation are returned in the
response. If set to NONE (the default), no statistics are returned.
Return type dict
Returns
Response Syntax
{
'UnprocessedItems': {
'string': [
{
'PutRequest': {
'Item': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['st
}
},
'DeleteRequest': {
'Key': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['st
}
}
},
]
},
'ItemCollectionMetrics': {
'string': [
{
'ItemCollectionKey': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string
},
'SizeEstimateRangeGB': [
123.0,
]
},
]
},
'ConsumedCapacity': [
{
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
3.1. Services 987
Boto3 Documentation, Release 1.1.4
}
},
]
}
Response Structure
• (dict) –
Represents the output of a BatchWriteItem operation.
– UnprocessedItems (dict) –
A map of tables and requests against those tables that were not processed.
The UnprocessedItems value is in the same form as RequestItems , so you
can provide this value directly to a subsequent BatchGetItem operation.
For more information, see RequestItems in the Request Parameters section.
Each UnprocessedItems entry consists of a table name and, for that table,
a list of operations to perform (DeleteRequest or PutRequest ).
* DeleteRequest - Perform a DeleteItem operation on the specified
item. The item to be deleted is identified by a Key subelement: *
Key - A map of primary key attribute values that uniquely identify
the item. Each entry in this map consists of an attribute name and
an attribute value.
* PutRequest - Perform a PutItem operation on the specified item. The
item to be put is identified by an Item subelement: * Item - A map
of attributes and their values. Each entry in this map consists of
an attribute name and an attribute value. Attribute values must not
be null; string and binary type attributes must have lengths greater
than zero; and set type attributes must not be empty. Requests that
contain empty values will be rejected with a ValidationException
exception. If you specify any attributes that are part of an index
key, then the data types for those attributes must match those of the
schema in the table’s attribute definition.
If there are no unprocessed items remaining, the response contains an
empty UnprocessedItems map.
* (string) –
· (list) –
· (dict) –
Represents an operation to perform - either DeleteItem or
PutItem . You can only request one of these operations, not
both, in a single WriteRequest . If you do need to perform
both of these operations, you will need to provide two sepa-
rate WriteRequest objects.
· PutRequest (dict) –
A request to perform a PutItem operation.
· Item (dict) –
A map of attribute name to attribute values, representing the
primary key of an item to be processed by PutItem . All of
the table’s primary key attributes must be specified, and their
data types must match those of the table’s key schema. If any
attributes are present in the item which are part of an index
key schema for the table, their types must match the index
key schema.
· (string) –
988 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
· DeleteRequest (dict) –
A request to perform a DeleteItem operation.
· Key (dict) –
A map of attribute name to attribute values, representing the
primary key of the item to delete. All of the table’s primary
key attributes must be specified, and their data types must
match those of the table’s key schema.
· (string) –
· (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
– ItemCollectionMetrics (dict) –
A list of tables that were processed by BatchWriteItem and, for each table,
information about any item collections that were affected by individual
DeleteItem or PutItem operations.
Each entry consists of the following subelements:
* ItemCollectionKey - The hash key value of the item collection. This
is the same as the hash key of the item.
* SizeEstimateRange - An estimate of item collection size, expressed
in GB. This is a two-element array containing a lower bound and
an upper bound for the estimate. The estimate includes the size of
all the items in the table, plus the size of all attributes projected into
all of the local secondary indexes on the table. Use this estimate
to measure whether a local secondary index is approaching its size
limit. The estimate is subject to change over time; therefore, do not
rely on the precision or accuracy of the estimate.
* (string) –
· (list) –
· (dict) –
Information about item collections, if any, that were affected
by the operation. ItemCollectionMetrics is only returned if
the request asked for it. If the table does not have any lo-
cal secondary indexes, this information is not returned in the
response.
· ItemCollectionKey (dict) –
The hash key value of the item collection. This value is the
same as the hash key of the item.
· (string) –
· (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
· SizeEstimateRangeGB (list) –
An estimate of item collection size, in gigabytes. This value
is a two-element array containing a lower bound and an upper
bound for the estimate. The estimate includes the size of all
the items in the table, plus the size of all attributes projected
into all of the local secondary indexes on that table. Use this
3.1. Services 989
Boto3 Documentation, Release 1.1.4
estimate to measure whether a local secondary index is ap-
proaching its size limit.
The estimate is subject to change over time; therefore, do not
rely on the precision or accuracy of the estimate.
· (float) –
– ConsumedCapacity (list) –
The capacity units consumed by the operation.
Each element consists of:
* TableName - The table that consumed the provisioned throughput.
* CapacityUnits - The total number of capacity units consumed.
* (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
· TableName (string) –
The name of the table that was affected by the operation.
· CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
· Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
· LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table or an
index.
· GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput capacity
consumed on a table or an index.
· CapacityUnits (float) –
990 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The total number of capacity units consumed on a table or an
index.
create_table(**kwargs)
The CreateTable operation adds a new table to your account. In an AWS account, table names must be
unique within each region. That is, you can have two tables with same name if you create the tables in
different regions.
CreateTable is an asynchronous operation. Upon receiving a CreateTable request, DynamoDB immedi-
ately returns a response with a TableStatus of CREATING . After the table is created, DynamoDB sets the
TableStatus to ACTIVE . You can perform read and write operations only on an ACTIVE table.
You can optionally define secondary indexes on the new table, as part of the CreateTable operation. If you
want to create multiple tables with secondary indexes on them, you must create the tables sequentially.
Only one table with secondary indexes can be in the CREATING state at any given time.
You can use the DescribeTable API to check the table status.
Request Syntax
table = dynamodb.create_table(
AttributeDefinitions=[
{
'AttributeName': 'string',
'AttributeType': 'S'|'N'|'B'
},
],
TableName='string',
KeySchema=[
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
LocalSecondaryIndexes=[
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
}
},
],
GlobalSecondaryIndexes=[
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
3.1. Services 991
Boto3 Documentation, Release 1.1.4
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'ProvisionedThroughput': {
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
}
},
],
ProvisionedThroughput={
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
StreamSpecification={
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_ONLY'
}
)
Parameters
• AttributeDefinitions (list) – [REQUIRED]
An array of attributes that describe the key schema for the table and indexes.
– (dict) –
Represents an attribute for describing the key schema for the table and
indexes.
* AttributeName (string) – [REQUIRED]
A name for the attribute.
* AttributeType (string) – [REQUIRED]
The data type for the attribute.
• TableName (string) – [REQUIRED]
The name of the table to create.
• KeySchema (list) – [REQUIRED]
Specifies the attributes that make up the primary key for a table or an index. The
attributes in KeySchema must also be defined in the AttributeDefinitions array.
For more information, see Data Model in the Amazon DynamoDB Developer
Guide .
Each KeySchemaElement in the array is composed of:
– AttributeName - The name of this key attribute.
– KeyType - Determines whether the key attribute is HASH or RANGE .
For a primary key that consists of a hash attribute, you must provide exactly one
element with a KeyType of HASH .
For a primary key that consists of hash and range attributes, you must provide
exactly two elements, in this order: The first element must have a KeyType of
HASH , and the second element must have a KeyType of RANGE .
For more information, see Specifying the Primary Key in the Amazon Dy-
namoDB Developer Guide .
– (dict) –
992 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Represents a single element of a key schema. A key schema specifies the
attributes that make up the primary key of a table, or the key attributes of
an index.
A KeySchemaElement represents exactly one attribute of the primary key.
For example, a hash type primary key would be represented by one
KeySchemaElement . A hash-and-range type primary key would require
one KeySchemaElement for the hash attribute, and another KeySchemaEle-
ment for the range attribute.
* AttributeName (string) – [REQUIRED]
The name of a key attribute.
* KeyType (string) – [REQUIRED]
The attribute data, consisting of the data type and the attribute value
itself.
• LocalSecondaryIndexes (list) – One or more local secondary indexes (the max-
imum is five) to be created on the table. Each index is scoped to a given hash
key value. There is a 10 GB size limit per hash key; otherwise, the size of a local
secondary index is unconstrained.
Each local secondary index in the array includes the following:
– IndexName - The name of the local secondary index. Must be unique only
for this table.
– KeySchema - Specifies the key schema for the local secondary index. The
key schema must begin with the same hash key attribute as the table.
– Projection - Specifies attributes that are copied (projected) from the table
into the index. These are in addition to the primary key attributes and
index key attributes, which are automatically projected. Each attribute
specification is composed of: * ProjectionType - One of the following:
* KEYS_ONLY - Only the index and primary keys are projected into the
index.
– INCLUDE - Only the specified table attributes are projected into the index.
The list of projected attributes are in NonKeyAttributes .
– ALL - All of the table attributes are projected into the index.
– NonKeyAttributes - A list of one or more non-key attribute names that are
projected into the secondary index. The total count of attributes provided
in NonKeyAttributes , summed across all of the secondary indexes, must
not exceed 20. If you project the same attribute into two different indexes,
this counts as two distinct attributes when determining the total.
– (dict) –
Represents the properties of a local secondary index.
* IndexName (string) – [REQUIRED]
The name of the local secondary index. The name must be unique
among all other indexes on this table.
* KeySchema (list) – [REQUIRED]
The complete key schema for the local secondary index, consisting
of one or more pairs of attribute names and key types (HASH or
RANGE ).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
3.1. Services 993
Boto3 Documentation, Release 1.1.4
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) – [REQUIRED]
The name of a key attribute.
· KeyType (string) – [REQUIRED]
The attribute data, consisting of the data type and the attribute
value itself.
* Projection (dict) – [REQUIRED]
Represents attributes that are copied (projected) from the table into
an index. These are in addition to the primary key attributes and
index key attributes, which are automatically projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
• GlobalSecondaryIndexes (list) – One or more global secondary indexes (the
maximum is five) to be created on the table. Each global secondary index in the
array includes the following:
– IndexName - The name of the global secondary index. Must be unique
only for this table.
– KeySchema - Specifies the key schema for the global secondary index.
– Projection - Specifies attributes that are copied (projected) from the table
into the index. These are in addition to the primary key attributes and
index key attributes, which are automatically projected. Each attribute
specification is composed of: * ProjectionType - One of the following:
* KEYS_ONLY - Only the index and primary keys are projected into the
index.
– INCLUDE - Only the specified table attributes are projected into the index.
The list of projected attributes are in NonKeyAttributes .
– ALL - All of the table attributes are projected into the index.
– NonKeyAttributes - A list of one or more non-key attribute names that are
projected into the secondary index. The total count of attributes provided
in NonKeyAttributes , summed across all of the secondary indexes, must
not exceed 20. If you project the same attribute into two different indexes,
994 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
this counts as two distinct attributes when determining the total.
– ProvisionedThroughput - The provisioned throughput settings for the
global secondary index, consisting of read and write capacity units.
– (dict) –
Represents the properties of a global secondary index.
* IndexName (string) – [REQUIRED]
The name of the global secondary index. The name must be unique
among all other indexes on this table.
* KeySchema (list) – [REQUIRED]
The complete key schema for a global secondary index, which con-
sists of one or more pairs of attribute names and key types (HASH
or RANGE ).
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) – [REQUIRED]
The name of a key attribute.
· KeyType (string) – [REQUIRED]
The attribute data, consisting of the data type and the attribute
value itself.
* Projection (dict) – [REQUIRED]
Represents attributes that are copied (projected) from the table into
an index. These are in addition to the primary key attributes and
index key attributes, which are automatically projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are projected
into the index.
· INCLUDE - Only the specified table attributes are projected
into the index. The list of projected attributes are in NonKey-
Attributes .
· ALL - All of the table attributes are projected into the index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be pro-
jected into the index.
For local secondary indexes, the total count of NonKeyAt-
tributes summed across all of the local secondary indexes,
must not exceed 20. If you project the same attribute into two
different indexes, this counts as two distinct attributes when
determining the total.
· (string) –
3.1. Services 995
Boto3 Documentation, Release 1.1.4
* ProvisionedThroughput (dict) – [REQUIRED]
Represents the provisioned throughput settings for a specified ta-
ble or index. The settings can be modified using the UpdateTable
operation.
For current minimum and maximum provisioned throughput values,
see Limits in the Amazon DynamoDB Developer Guide .
· ReadCapacityUnits (integer) – [REQUIRED]
The maximum number of strongly consistent reads consumed
per second before DynamoDB returns a ThrottlingException
. For more information, see Specifying Read and Write Re-
quirements in the Amazon DynamoDB Developer Guide .
· WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per second before
DynamoDB returns a ThrottlingException . For more infor-
mation, see Specifying Read and Write Requirements in the
Amazon DynamoDB Developer Guide .
• ProvisionedThroughput (dict) – [REQUIRED]
Represents the provisioned throughput settings for a specified table or index.
The settings can be modified using the UpdateTable operation.
For current minimum and maximum provisioned throughput values, see Limits
in the Amazon DynamoDB Developer Guide .
– ReadCapacityUnits (integer) – [REQUIRED]
The maximum number of strongly consistent reads consumed per second
before DynamoDB returns a ThrottlingException . For more information,
see Specifying Read and Write Requirements in the Amazon DynamoDB
Developer Guide .
– WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per second before DynamoDB
returns a ThrottlingException . For more information, see Specifying Read
and Write Requirements in the Amazon DynamoDB Developer Guide .
• StreamSpecification (dict) – The settings for DynamoDB Streams on the table.
These settings consist of:
– StreamEnabled - Indicates whether Streams is to be enabled (true) or dis-
abled (false).
– StreamViewType - When an item in the table is modified, StreamViewType
determines what information is written to the table’s stream. Valid values
for StreamViewType are: * KEYS_ONLY - Only the key attributes of the
modified item are written to the stream.
– NEW_IMAGE - The entire item, as it appears after it was modified, is
written to the stream.
– OLD_IMAGE - The entire item, as it appeared before it was modified, is
written to the stream.
– NEW_AND_OLD_IMAGES - Both the new and the old item images of the
item are written to the stream.
– StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled (true) or disabled (false)
on the table.
– StreamViewType (string) –
996 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The DynamoDB Streams settings for the table. These settings consist of:
* StreamEnabled - Indicates whether DynamoDB Streams is enabled
(true) or disabled (false) on the table.
* StreamViewType - When an item in the table is modified,
StreamViewType determines what information is written to the
stream for this table. Valid values for StreamViewType are: *
KEYS_ONLY - Only the key attributes of the modified item are writ-
ten to the stream.
* NEW_IMAGE - The entire item, as it appears after it was modified,
is written to the stream.
* OLD_IMAGE - The entire item, as it appeared before it was modi-
fied, is written to the stream.
* NEW_AND_OLD_IMAGES - Both the new and the old item images
of the item are written to the stream.
Return type dynamodb.Table
Returns Table resource
Sub-resources
Sub-resources are methods that create a new instance of a child resource. This resource’s identifiers get passed
along to the child. For more information about sub-resources refer to the Resources Introduction Guide.
Table(name)
Creates a Table resource.:
table = dynamodb.Table('name')
Parameters name (string) – The Table’s name identifier. This must be set.
Return type DynamoDB.Table
Returns A Table resource
Collections
Collections provide an interface to iterate over and manipulate groups of resources. For more information about
collections refer to the Resources Introduction Guide.
tables
all()
Creates an iterable of all Table resources in the collection.
Request Syntax
table_iterator = dynamodb.tables.all()
Return type list(dynamodb.Table)
Returns A list of Table resources
filter(**kwargs)
Creates an iterable of all Table resources in the collection filtered by kwargs passed to method.
Request Syntax
table_iterator = dynamodb.tables.filter(
ExclusiveStartTableName='string',
Limit=123
)
Parameters
3.1. Services 997
Boto3 Documentation, Release 1.1.4
• ExclusiveStartTableName (string) – The first table name that this op-
eration will evaluate. Use the value that was returned for LastEvaluat-
edTableName in a previous operation, so that you can obtain the next page
of results.
• Limit (integer) – A maximum number of table names to return. If this
parameter is not specified, the limit is 100.
Return type list(dynamodb.Table)
Returns A list of Table resources
limit(**kwargs)
Creates an iterable up to a specified amount of Table resources in the collection.
Request Syntax
table_iterator = dynamodb.tables.limit(
count=123
)
Parameters count (integer) – The limit to the number of resources in the iterable.
Return type list(dynamodb.Table)
Returns A list of Table resources
page_size(**kwargs)
Creates an iterable of all Table resources in the collection, but limits the number of items returned
by each service call by the specified amount.
Request Syntax
table_iterator = dynamodb.tables.page_size(
count=123
)
Parameters count (integer) – The number of items returned by each service call
Return type list(dynamodb.Table)
Returns A list of Table resources
Table
class DynamoDB.Table(name)
A resource representing an Amazon DynamoDB Table:
import boto3
dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('name')
Parameters name (string) – The Table’s name identifier. This must be set.
These are the resource’s available identifiers:
•name
These are the resource’s available attributes:
•attribute_definitions
•creation_date_time
•global_secondary_indexes
•item_count
•key_schema
998 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
•latest_stream_arn
•latest_stream_label
•local_secondary_indexes
•provisioned_throughput
•stream_specification
•table_arn
•table_name
•table_size_bytes
•table_status
These are the resource’s available actions:
•batch_writer()
•delete()
•delete_item()
•get_item()
•load()
•put_item()
•query()
•reload()
•scan()
•update()
•update_item()
Identifiers
Identifiers are properties of a resource that are set upon instantation of the resource. For more information about
identifiers refer to the Resources Introduction Guide.
name
(string) The Table’s name identifier. This must be set.
Attributes
Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed
via the load() method. For more information about attributes refer to the Resources Introduction Guide.
attribute_definitions
(list)
An array of AttributeDefinition objects. Each of these objects describes one attribute in the table and index
key schema.
Each AttributeDefinition object in this array is composed of:
•AttributeName - The name of the attribute.
•AttributeType - The data type for the attribute.
creation_date_time
(datetime)
The date and time when the table was created, in UNIX epoch time format.
global_secondary_indexes
(list)
The global secondary indexes, if any, on the table. Each index is scoped to a given hash key value. Each
element is composed of:
•Backfilling - If true, then the index is currently in the backfilling phase. Backfilling occurs only
when a new global secondary index is added to the table; it is the process by which DynamoDB
populates the new index with data from the table. (This attribute does not appear for indexes that
were created during a CreateTable operation.)
•IndexName - The name of the global secondary index.
3.1. Services 999
Boto3 Documentation, Release 1.1.4
•IndexSizeBytes - The total size of the global secondary index, in bytes. DynamoDB updates this
value approximately every six hours. Recent changes might not be reflected in this value.
•IndexStatus - The current status of the global secondary index: * CREATING - The index is being
created.
•UPDATING - The index is being updated.
•DELETING - The index is being deleted.
•ACTIVE - The index is ready for use.
•ItemCount - The number of items in the global secondary index. DynamoDB updates this value
approximately every six hours. Recent changes might not be reflected in this value.
•KeySchema - Specifies the complete index key schema. The attribute names in the key schema must
be between 1 and 255 characters (inclusive). The key schema must begin with the same hash key
attribute as the table.
•Projection - Specifies attributes that are copied (projected) from the table into the index. These
are in addition to the primary key attributes and index key attributes, which are automatically pro-
jected. Each attribute specification is composed of: * ProjectionType - One of the following: *
KEYS_ONLY - Only the index and primary keys are projected into the index.
•INCLUDE - Only the specified table attributes are projected into the index. The list of projected
attributes are in NonKeyAttributes .
•ALL - All of the table attributes are projected into the index.
•NonKeyAttributes - A list of one or more non-key attribute names that are projected into the sec-
ondary index. The total count of attributes provided in NonKeyAttributes , summed across all of the
secondary indexes, must not exceed 20. If you project the same attribute into two different indexes,
this counts as two distinct attributes when determining the total.
•ProvisionedThroughput - The provisioned throughput settings for the global secondary index, con-
sisting of read and write capacity units, along with data about increases and decreases.
If the table is in the DELETING state, no information about indexes will be returned.
item_count
(integer)
The number of items in the specified table. DynamoDB updates this value approximately every six hours.
Recent changes might not be reflected in this value.
key_schema
(list)
The primary key structure for the table. Each KeySchemaElement consists of:
•AttributeName - The name of the attribute.
•KeyType - The key type for the attribute. Can be either HASH or RANGE .
For more information about primary keys, see Primary Key in the Amazon DynamoDB Developer Guide .
latest_stream_arn
(string)
The Amazon Resource Name (ARN) that uniquely identifies the latest stream for this table.
latest_stream_label
(string)
A timestamp, in ISO 8601 format, for this stream.
Note that LatestStreamLabel is not a unique identifier for the stream, because it is possible that a stream
from another table might have the same timestamp. However, the combination of the following three
elements is guaranteed to be unique:
•the AWS customer ID.
•the table name.
•the StreamLabel .
1000 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
local_secondary_indexes
(list)
Represents one or more local secondary indexes on the table. Each index is scoped to a given hash key
value. Tables with one or more local secondary indexes are subject to an item collection size limit, where
the amount of data within a given item collection cannot exceed 10 GB. Each element is composed of:
•IndexName - The name of the local secondary index.
•KeySchema - Specifies the complete index key schema. The attribute names in the key schema must
be between 1 and 255 characters (inclusive). The key schema must begin with the same hash key
attribute as the table.
•Projection - Specifies attributes that are copied (projected) from the table into the index. These
are in addition to the primary key attributes and index key attributes, which are automatically pro-
jected. Each attribute specification is composed of: * ProjectionType - One of the following: *
KEYS_ONLY - Only the index and primary keys are projected into the index.
•INCLUDE - Only the specified table attributes are projected into the index. The list of projected
attributes are in NonKeyAttributes .
•ALL - All of the table attributes are projected into the index.
•NonKeyAttributes - A list of one or more non-key attribute names that are projected into the sec-
ondary index. The total count of attributes provided in NonKeyAttributes , summed across all of the
secondary indexes, must not exceed 20. If you project the same attribute into two different indexes,
this counts as two distinct attributes when determining the total.
•IndexSizeBytes - Represents the total size of the index, in bytes. DynamoDB updates this value
approximately every six hours. Recent changes might not be reflected in this value.
•ItemCount - Represents the number of items in the index. DynamoDB updates this value approxi-
mately every six hours. Recent changes might not be reflected in this value.
If the table is in the DELETING state, no information about indexes will be returned.
provisioned_throughput
(dict)
The provisioned throughput settings for the table, consisting of read and write capacity units, along with
data about increases and decreases.
stream_specification
(dict)
The current DynamoDB Streams configuration for the table.
table_arn
(string)
The Amazon Resource Name (ARN) that uniquely identifies the table.
table_name
(string)
The name of the table.
table_size_bytes
(integer)
The total size of the specified table, in bytes. DynamoDB updates this value approximately every six
hours. Recent changes might not be reflected in this value.
table_status
(string)
The current state of the table:
•CREATING - The table is being created.
•UPDATING - The table is being updated.
3.1. Services 1001
Boto3 Documentation, Release 1.1.4
•DELETING - The table is being deleted.
•ACTIVE - The table is ready for use.
Actions
Actions call operations on resources. They may automatically handle the passing in of arguments set from
identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.
batch_writer()
Create a batch writer object.
This method creates a context manager for writing objects to Amazon DynamoDB in batch.
The batch writer will automatically handle buffering and sending items in batches. In addition, the batch
writer will also automatically handle any unprocessed items and resend them as needed. All you need
to do is call put_item for any items you want to add, and delete_item for any items you want to
delete.
Example usage:
with table.batch_writer() as batch:
for _ in xrange(1000000):
batch.put_item(Item={'HashKey': '...',
'Otherstuff': '...'})
# You can also delete_items in a batch.
batch.delete_item(Key={'HashKey': 'SomeHashKey'})
delete()
The DeleteTable operation deletes a table and all of its items. After a DeleteTable request, the
specified table is in the DELETING state until DynamoDB completes the deletion. If the table is
in the ACTIVE state, you can delete it. If a table is in CREATING or UPDATING states, then
DynamoDB returns a ResourceInUseException . If the specified table does not exist, DynamoDB
returns a ResourceNotFoundException . If table is already in the DELETING state, no error is
returned.
Note: DynamoDB might continue to accept data read and write operations, such as GetItem and
PutItem , on a table in the DELETING state until the table deletion is complete.
When you delete a table, any indexes on that table are also deleted.
If you have DynamoDB Streams enabled on the table, then the corresponding stream on that table
goes into the DISABLED state, and the stream is automatically deleted after 24 hours.
Use the DescribeTable API to check the status of the table.
Request Syntax
response = table.delete()
Return type dict
Returns
Response Syntax
{
'TableDescription': {
'AttributeDefinitions': [
{
'AttributeName': 'string',
1002 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'AttributeType': 'S'|'N'|'B'
},
],
'TableName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'TableStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
'CreationDateTime': datetime(2015, 1, 1),
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'TableSizeBytes': 123,
'ItemCount': 123,
'TableArn': 'string',
'LocalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
},
],
'GlobalSecondaryIndexes': [
{
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'IndexStatus': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE',
3.1. Services 1003
Boto3 Documentation, Release 1.1.4
'Backfilling': True|False,
'ProvisionedThroughput': {
'LastIncreaseDateTime': datetime(2015, 1, 1),
'LastDecreaseDateTime': datetime(2015, 1, 1),
'NumberOfDecreasesToday': 123,
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
'IndexSizeBytes': 123,
'ItemCount': 123,
'IndexArn': 'string'
},
],
'StreamSpecification': {
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KE
},
'LatestStreamLabel': 'string',
'LatestStreamArn': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a DeleteTable operation.
– TableDescription (dict) –
Represents the properties of a table.
* AttributeDefinitions (list) –
An array of AttributeDefinition objects. Each of these objects
describes one attribute in the table and index key schema.
Each AttributeDefinition object in this array is composed of:
· AttributeName - The name of the attribute.
· AttributeType - The data type for the attribute.
· (dict) –
Represents an attribute for describing the key schema
for the table and indexes.
· AttributeName (string) –
A name for the attribute.
· AttributeType (string) –
The data type for the attribute.
* TableName (string) –
The name of the table.
* KeySchema (list) –
The primary key structure for the table. Each KeySchemaEle-
ment consists of:
· AttributeName - The name of the attribute.
· KeyType - The key type for the attribute. Can be either
HASH or RANGE .
For more information about primary keys, see Primary Key in
the Amazon DynamoDB Developer Guide .
1004 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Represents a single element of a key schema. A key
schema specifies the attributes that make up the primary
key of a table, or the key attributes of an index.
A KeySchemaElement represents exactly one attribute
of the primary key. For example, a hash type primary
key would be represented by one KeySchemaElement .
A hash-and-range type primary key would require one
KeySchemaElement for the hash attribute, and another
KeySchemaElement for the range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the
attribute value itself.
* TableStatus (string) –
The current state of the table:
· CREATING - The table is being created.
· UPDATING - The table is being updated.
· DELETING - The table is being deleted.
· ACTIVE - The table is ready for use.
* CreationDateTime (datetime) –
The date and time when the table was created, in UNIX epoch
time format.
* ProvisionedThroughput (dict) –
The provisioned throughput settings for the table, consisting
of read and write capacity units, along with data about in-
creases and decreases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput
increase for this table.
· LastDecreaseDateTime (datetime) –
The date and time of the last provisioned throughput
decrease for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for
this table during this UTC calendar day. For current
maximums on provisioned throughput decreases, see
Limits in the Amazon DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads
consumed per second before DynamoDB returns a
ThrottlingException . Eventually consistent reads re-
quire less effort than strongly consistent reads, so a set-
ting of 50 ReadCapacityUnits per second provides 100
eventually consistent ReadCapacityUnits per second.
· WriteCapacityUnits (integer) –
3.1. Services 1005
Boto3 Documentation, Release 1.1.4
The maximum number of writes consumed per second
before DynamoDB returns a ThrottlingException .
* TableSizeBytes (integer) –
The total size of the specified table, in bytes. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
* ItemCount (integer) –
The number of items in the specified table. DynamoDB
updates this value approximately every six hours. Recent
changes might not be reflected in this value.
* TableArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the table.
* LocalSecondaryIndexes (list) –
Represents one or more local secondary indexes on the table.
Each index is scoped to a given hash key value. Tables with
one or more local secondary indexes are subject to an item
collection size limit, where the amount of data within a given
item collection cannot exceed 10 GB. Each element is com-
posed of:
· IndexName - The name of the local secondary index.
· KeySchema - Specifies the complete index key schema.
The attribute names in the key schema must be between
1 and 255 characters (inclusive). The key schema must
begin with the same hash key attribute as the table.
· Projection - Specifies attributes that are copied (pro-
jected) from the table into the index. These are in ad-
dition to the primary key attributes and index key at-
tributes, which are automatically projected. Each at-
tribute specification is composed of: * ProjectionType -
One of the following: * KEYS_ONLY - Only the index
and primary keys are projected into the index.
· INCLUDE - Only the specified table attributes are pro-
jected into the index. The list of projected attributes are
in NonKeyAttributes .
· ALL - All of the table attributes are projected into the
index.
· NonKeyAttributes - A list of one or more non-key at-
tribute names that are projected into the secondary in-
dex. The total count of attributes provided in Non-
KeyAttributes , summed across all of the secondary in-
dexes, must not exceed 20. If you project the same
attribute into two different indexes, this counts as two
distinct attributes when determining the total.
· IndexSizeBytes - Represents the total size of the index,
in bytes. DynamoDB updates this value approximately
every six hours. Recent changes might not be reflected
in this value.
· ItemCount - Represents the number of items in the in-
dex. DynamoDB updates this value approximately ev-
ery six hours. Recent changes might not be reflected in
this value.
1006 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
If the table is in the DELETING state, no information about
indexes will be returned.
· (dict) –
Represents the properties of a local secondary index.
· IndexName (string) –
Represents the name of the local secondary index.
· KeySchema (list) –
The complete index key schema, which consists of one
or more pairs of attribute names and key types (HASH
or RANGE ).
· (dict) –
Represents a single element of a key schema. A key
schema specifies the attributes that make up the primary
key of a table, or the key attributes of an index.
A KeySchemaElement represents exactly one attribute
of the primary key. For example, a hash type primary
key would be represented by one KeySchemaElement .
A hash-and-range type primary key would require one
KeySchemaElement for the hash attribute, and another
KeySchemaElement for the range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the
attribute value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from
the table into an index. These are in addition to the
primary key attributes and index key attributes, which
are automatically projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are
projected into the index.
· INCLUDE - Only the specified table attributes are pro-
jected into the index. The list of projected attributes are
in NonKeyAttributes .
· ALL - All of the table attributes are projected into the
index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be
projected into the index.
For local secondary indexes, the total count of Non-
KeyAttributes summed across all of the local secondary
indexes, must not exceed 20. If you project the same
attribute into two different indexes, this counts as two
distinct attributes when determining the total.
· (string) –
3.1. Services 1007
Boto3 Documentation, Release 1.1.4
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. Dy-
namoDB updates this value approximately every six
hours. Recent changes might not be reflected in this
value.
· ItemCount (integer) –
The number of items in the specified index. Dy-
namoDB updates this value approximately every six
hours. Recent changes might not be reflected in this
value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely
identifies the index.
* GlobalSecondaryIndexes (list) –
The global secondary indexes, if any, on the table. Each in-
dex is scoped to a given hash key value. Each element is
composed of:
· Backfilling - If true, then the index is currently in the
backfilling phase. Backfilling occurs only when a new
global secondary index is added to the table; it is the
process by which DynamoDB populates the new index
with data from the table. (This attribute does not ap-
pear for indexes that were created during a CreateTable
operation.)
· IndexName - The name of the global secondary index.
· IndexSizeBytes - The total size of the global secondary
index, in bytes. DynamoDB updates this value approx-
imately every six hours. Recent changes might not be
reflected in this value.
· IndexStatus - The current status of the global secondary
index: * CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· ItemCount - The number of items in the global sec-
ondary index. DynamoDB updates this value approx-
imately every six hours. Recent changes might not be
reflected in this value.
· KeySchema - Specifies the complete index key schema.
The attribute names in the key schema must be between
1 and 255 characters (inclusive). The key schema must
begin with the same hash key attribute as the table.
· Projection - Specifies attributes that are copied (pro-
jected) from the table into the index. These are in ad-
dition to the primary key attributes and index key at-
tributes, which are automatically projected. Each at-
tribute specification is composed of: * ProjectionType -
One of the following: * KEYS_ONLY - Only the index
and primary keys are projected into the index.
· INCLUDE - Only the specified table attributes are pro-
jected into the index. The list of projected attributes are
in NonKeyAttributes .
1008 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· ALL - All of the table attributes are projected into the
index.
· NonKeyAttributes - A list of one or more non-key at-
tribute names that are projected into the secondary in-
dex. The total count of attributes provided in Non-
KeyAttributes , summed across all of the secondary in-
dexes, must not exceed 20. If you project the same
attribute into two different indexes, this counts as two
distinct attributes when determining the total.
· ProvisionedThroughput - The provisioned throughput
settings for the global secondary index, consisting of
read and write capacity units, along with data about in-
creases and decreases.
If the table is in the DELETING state, no information about
indexes will be returned.
· (dict) –
Represents the properties of a global secondary index.
· IndexName (string) –
The name of the global secondary index.
· KeySchema (list) –
The complete key schema for the global secondary in-
dex, consisting of one or more pairs of attribute names
and key types (HASH or RANGE ).
· (dict) –
Represents a single element of a key schema. A key
schema specifies the attributes that make up the primary
key of a table, or the key attributes of an index.
A KeySchemaElement represents exactly one attribute
of the primary key. For example, a hash type primary
key would be represented by one KeySchemaElement .
A hash-and-range type primary key would require one
KeySchemaElement for the hash attribute, and another
KeySchemaElement for the range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the
attribute value itself.
· Projection (dict) –
Represents attributes that are copied (projected) from
the table into an index. These are in addition to the
primary key attributes and index key attributes, which
are automatically projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are
projected into the index.
· INCLUDE - Only the specified table attributes are pro-
jected into the index. The list of projected attributes are
3.1. Services 1009
Boto3 Documentation, Release 1.1.4
in NonKeyAttributes .
· ALL - All of the table attributes are projected into the
index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be
projected into the index.
For local secondary indexes, the total count of Non-
KeyAttributes summed across all of the local secondary
indexes, must not exceed 20. If you project the same
attribute into two different indexes, this counts as two
distinct attributes when determining the total.
· (string) –
· IndexStatus (string) –
The current state of the global secondary index:
· CREATING - The index is being created.
· UPDATING - The index is being updated.
· DELETING - The index is being deleted.
· ACTIVE - The index is ready for use.
· Backfilling (boolean) –
Indicates whether the index is currently backfilling.
Backfilling is the process of reading items from the ta-
ble and determining whether they can be added to the
index. (Not all items will qualify: For example, a hash
key attribute cannot have any duplicates.) If an item can
be added to the index, DynamoDB will do so. After all
items have been processed, the backfilling operation is
complete and Backfilling is false.
Note: For indexes that were created during a Cre-
ateTable operation, the Backfilling attribute does not
appear in the DescribeTable output.
· ProvisionedThroughput (dict) –
Represents the provisioned throughput settings for the
table, consisting of read and write capacity units, along
with data about increases and decreases.
· LastIncreaseDateTime (datetime) –
The date and time of the last provisioned throughput
increase for this table.
· LastDecreaseDateTime (datetime) –
The date and time of the last provisioned throughput
decrease for this table.
· NumberOfDecreasesToday (integer) –
The number of provisioned throughput decreases for
this table during this UTC calendar day. For current
maximums on provisioned throughput decreases, see
Limits in the Amazon DynamoDB Developer Guide .
· ReadCapacityUnits (integer) –
The maximum number of strongly consistent reads
consumed per second before DynamoDB returns a
1010 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
ThrottlingException . Eventually consistent reads re-
quire less effort than strongly consistent reads, so a set-
ting of 50 ReadCapacityUnits per second provides 100
eventually consistent ReadCapacityUnits per second.
· WriteCapacityUnits (integer) –
The maximum number of writes consumed per second
before DynamoDB returns a ThrottlingException .
· IndexSizeBytes (integer) –
The total size of the specified index, in bytes. Dy-
namoDB updates this value approximately every six
hours. Recent changes might not be reflected in this
value.
· ItemCount (integer) –
The number of items in the specified index. Dy-
namoDB updates this value approximately every six
hours. Recent changes might not be reflected in this
value.
· IndexArn (string) –
The Amazon Resource Name (ARN) that uniquely
identifies the index.
* StreamSpecification (dict) –
The current DynamoDB Streams configuration for the table.
· StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled
(true) or disabled (false) on the table.
· StreamViewType (string) –
The DynamoDB Streams settings for the table. These
settings consist of:
· StreamEnabled - Indicates whether DynamoDB
Streams is enabled (true) or disabled (false) on the
table.
· StreamViewType - When an item in the table is mod-
ified, StreamViewType determines what information is
written to the stream for this table. Valid values for
StreamViewType are: * KEYS_ONLY - Only the key at-
tributes of the modified item are written to the stream.
· NEW_IMAGE - The entire item, as it appears after it
was modified, is written to the stream.
· OLD_IMAGE - The entire item, as it appeared before it
was modified, is written to the stream.
· NEW_AND_OLD_IMAGES - Both the new and the old
item images of the item are written to the stream.
* LatestStreamLabel (string) –
A timestamp, in ISO 8601 format, for this stream.
Note that LatestStreamLabel is not a unique identifier for the
stream, because it is possible that a stream from another table
might have the same timestamp. However, the combination
of the following three elements is guaranteed to be unique:
· the AWS customer ID.
3.1. Services 1011
Boto3 Documentation, Release 1.1.4
· the table name.
· the StreamLabel .
* LatestStreamArn (string) –
The Amazon Resource Name (ARN) that uniquely identifies
the latest stream for this table.
delete_item(**kwargs)
Deletes a single item in a table by primary key. You can perform a conditional delete operation that
deletes the item if it exists, or if it has an expected attribute value.
In addition to deleting an item, you can also return the item’s attribute values in the same operation,
using the ReturnValues parameter.
Unless you specify conditions, the DeleteItem is an idempotent operation; running it multiple times
on the same item or attribute does not result in an error response.
Conditional deletes are useful for deleting items only if specific conditions are met. If those condi-
tions are met, DynamoDB performs the delete. Otherwise, the item is not deleted.
Request Syntax
response = table.delete_item(
Key={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
},
Expected={
'string': {
'Value': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])
'Exists': True|False,
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NUL
'AttributeValueList': [
'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|set(
]
}
},
ConditionalOperator='AND'|'OR',
ReturnValues='NONE'|'ALL_OLD'|'UPDATED_OLD'|'ALL_NEW'|'UPDATED_NEW',
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ReturnItemCollectionMetrics='SIZE'|'NONE',
ConditionExpression=Attr('myattribute').eq('myvalue'),
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
}
)
Parameters
• Key (dict) – [REQUIRED]
A map of attribute names to AttributeValue objects, representing the pri-
mary key of the item to delete.
For the primary key, you must provide all of the attributes. For example,
with a hash type primary key, you only need to provide the hash attribute.
For a hash-and-range type primary key, you must provide both the hash
attribute and the range attribute.
– (string) –
1012 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
Warning: This is a legacy parameter, for backward compatibility.
New applications should use ConditionExpression instead. Do not
• Expected (dict) – combine legacy parameters and expression parameters in a single API
call; otherwise, DynamoDB will return a ValidationException excep-
tion.
A map of attribute/condition pairs. Expected provides a conditional block
for the DeleteItem operation.
Each element of Expected consists of an attribute name, a comparison op-
erator, and one or more values. DynamoDB compares the attribute with
the value(s) you supplied, using the comparison operator. For each Ex-
pected element, the result of the evaluation is either true or false.
If you specify more than one element in the Expected map, then by default
all of the conditions must evaluate to true. In other words, the conditions
are ANDed together. (You can use the ConditionalOperator parameter to
OR the conditions instead. If you do this, then at least one of the conditions
must evaluate to true, rather than all of them.)
If the Expected map evaluates to true, then the conditional operation suc-
ceeds; otherwise, it fails.
Expected contains the following:
– AttributeValueList - One or more values to evaluate against
the supplied attribute. The number of values in the list de-
pends on the ComparisonOperator being used. For type
Number, value comparisons are numeric. String value com-
parisons for greater than, equals, or less than are based on
ASCII character code values. For example, a is greater than
A , and a is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters .
For type Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
– ComparisonOperator - A comparator for evaluating attributes in
the AttributeValueList . When performing the comparison, Dy-
namoDB uses strongly consistent reads. The following comparison
operators are available: EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN The following are descrip-
tions of each comparison operator. * EQ : Equal. EQ is supported
for all datatypes, including lists and maps. AttributeValueList can
contain only one AttributeValue element of type String, Number,
Binary, String Set, Number Set, or Binary Set. If an item contains
an AttributeValue element of a different type than the one provided
in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
– NE : Not equal. NE is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one AttributeValue
of type String, Number, Binary, String Set, Number Set, or Binary
Set. If an item contains an AttributeValue of a different type than the
3.1. Services 1013
Boto3 Documentation, Release 1.1.4
one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"}
does not equal {"NS":["6", "2", "1"]} .
– LE : Less than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– LT : Less than. AttributeValueList can contain only one Attribute-
Value of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one
provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"}
does not compare to {"NS":["6", "2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– GT : Greater than. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– NOT_NULL : The attribute exists. NOT_NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for
the existence of an attribute, not its data type. If the data type of
attribute “a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the attribute “a ”
exists; its data type is not relevant to the NOT_NULL comparison
operator.
– NULL : The attribute does not exist. NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for
the nonexistence of an attribute, not its data type. If the data type of
attribute “a ” is null, and you evaluate it using NULL , the result is
a Boolean false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
– CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element of type
String, Number, or Binary (not a set type). If the target attribute of
the comparison is of type String, then the operator checks for a sub-
string match. If the target attribute of the comparison is of type
Binary, then the operator looks for a subsequence of the target that
matches the input. If the target attribute of the comparison is a set
(“SS ”, “NS ”, or “BS ”), then the operator evaluates to true if it
finds an exact match with any member of the set. CONTAINS is
supported for lists: When evaluating “a CONTAINS b ”, “a ” can
be a list; however, “b ” cannot be a set, a map, or a list.
1014 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– NOT_CONTAINS : Checks for absence of a subsequence, or ab-
sence of a value in a set. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If the target attribute of the comparison is a String, then the
operator checks for the absence of a substring match. If the target
attribute of the comparison is Binary, then the operator checks for
the absence of a subsequence of the target that matches the input.
If the target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is supported
for lists: When evaluating “a NOT CONTAINS b ”, “a ” can be a
list; however, “b ” cannot be a set, a map, or a list.
– BEGINS_WITH : Checks for a prefix. AttributeValueList can con-
tain only one AttributeValue of type String or Binary (not a Number
or a set type). The target attribute of the comparison must be of type
String or Binary (not a Number or a set type).
– IN : Checks for matching elements within two sets. AttributeVal-
ueList can contain one or more AttributeValue elements of type
String, Number, or Binary (not a set type). These attributes are
compared against an existing set type attribute of an item. If any
elements of the input set are present in the item attribute, the ex-
pression evaluates to true.
– BETWEEN : Greater than or equal to the first value, and less than
or equal to the second value. AttributeValueList must contain two
AttributeValue elements of the same type, either String, Number, or
Binary (not a set type). A target attribute matches if the target value
is greater than, or equal to, the first element and less than, or equal
to, the second element. If an item contains an AttributeValue ele-
ment of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not com-
pare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see
Legacy Conditional Parameters in the Amazon DynamoDB Developer
Guide .
For backward compatibility with previous DynamoDB releases, the fol-
lowing parameters can be used instead of AttributeValueList and Compar-
isonOperator :
– Value - A value for DynamoDB to compare with an attribute.
– Exists - A Boolean value that causes DynamoDB to evaluate the
value before attempting the conditional operation: * If Exists is
true , DynamoDB will check to see if that attribute value already
exists in the table. If it is found, then the condition evaluates to true;
otherwise the condition evaluate to false.
– If Exists is false , DynamoDB assumes that the attribute value
does not exist in the table. If in fact the value does not exist, then the
assumption is valid and the condition evaluates to true. If the value
is found, despite the assumption that it does not exist, the condition
evaluates to false.
Note that the default value for Exists is true .
The Value and Exists parameters are incompatible with AttributeValueList
and ComparisonOperator . Note that if you use both sets of parameters at
once, DynamoDB will return a ValidationException exception.
3.1. Services 1015
Boto3 Documentation, Release 1.1.4
Note: This parameter does not support attributes of type List or Map.
– (string) –
* (dict) –
Represents a condition to be compared with an attribute value.
This condition can be used with DeleteItem , PutItem or Up-
dateItem operations; if the comparison evaluates to true, the
operation succeeds; if not, the operation fails. You can use
ExpectedAttributeValue in one of two different ways:
· Use AttributeValueList to specify one or more values to
compare against an attribute. Use ComparisonOpera-
tor to specify how you want to perform the comparison.
If the comparison evaluates to true, then the conditional
operation succeeds.
· Use Value to specify a value that DynamoDB will com-
pare against an attribute. If the values match, then Ex-
pectedAttributeValue evaluates to true and the condi-
tional operation succeeds. Optionally, you can also set
Exists to false, indicating that you do not expect to find
the attribute value in the table. In this case, the condi-
tional operation succeeds only if the comparison evalu-
ates to false.
Value and Exists are incompatible with AttributeValueList and
ComparisonOperator . Note that if you use both sets of pa-
rameters at once, DynamoDB will return a ValidationExcep-
tion exception.
· Value (valid DynamoDB type) – - The value of the
attribute. The valid value types are listed in the Dy-
namoDB Reference Guide.
· Exists (boolean) –
Causes DynamoDB to evaluate the value before at-
tempting a conditional operation:
· If Exists is true , DynamoDB will check to see if that
attribute value already exists in the table. If it is found,
then the operation succeeds. If it is not found, the op-
eration fails with a ConditionalCheckFailedException
.
· If Exists is false , DynamoDB assumes that the at-
tribute value does not exist in the table. If in fact the
value does not exist, then the assumption is valid and
the operation succeeds. If the value is found, despite
the assumption that it does not exist, the operation fails
with a ConditionalCheckFailedException .
The default setting for Exists is true . If you supply
a Value all by itself, DynamoDB assumes the attribute
exists: You don’t have to set Exists to true , because
it is implied.
DynamoDB returns a ValidationException if:
· Exists is true but there is no Value to check. (You
expect a value to exist, but don’t specify what that value
is.)
1016 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Exists is false but you also provide a Value . (You
cannot expect an attribute to have a value, while also
expecting it not to exist.)
· ComparisonOperator (string) –
A comparator for evaluating attributes in the Attribute-
ValueList . For example, equals, greater than, less than,
etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS |
NOT_CONTAINS | BEGINS_WITH | IN |
BETWEEN
The following are descriptions of each comparison op-
erator.
· EQ : Equal. EQ is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can contain
only one AttributeValue element of type String, Num-
ber, Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the
value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can con-
tain only one AttributeValue of type String, Number,
Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue of a different type
than the one provided in the request, the value does
not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one
AttributeValue of type String, Number, or Binary (not a
set type). If an item contains an AttributeValue element
of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does
not compare to {"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
3.1. Services 1017
Boto3 Documentation, Release 1.1.4
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only
one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an Attribute-
Value element of a different type than the one provided
in the request, the value does not match. For exam-
ple, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is sup-
ported for all datatypes, including lists and maps. ..
note::This operator tests for the existence of an at-
tribute, not its data type. If the data type of attribute
“a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the at-
tribute “a ” exists; its data type is not relevant to the
NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported
for all datatypes, including lists and maps. .. note::This
operator tests for the nonexistence of an attribute, not
its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean
false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a
set. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not
a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring
match. If the target attribute of the comparison is of
type Binary, then the operator looks for a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or “BS
”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is sup-
ported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map,
or a list.
· NOT_CONTAINS : Checks for absence of a subse-
quence, or absence of a value in a set. AttributeVal-
ueList can contain only one AttributeValue element of
type String, Number, or Binary (not a set type). If the
target attribute of the comparison is a String, then the
operator checks for the absence of a substring match.
If the target attribute of the comparison is Binary, then
the operator checks for the absence of a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set.
NOT_CONTAINS is supported for lists: When eval-
uating “a NOT CONTAINS b ”, “a ” can be a list;
1018 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
however, “b ” cannot be a set, a map, or a list.
· BEGINS_WITH : Checks for a prefix. AttributeVal-
ueList can contain only one AttributeValue of type
String or Binary (not a Number or a set type). The tar-
get attribute of the comparison must be of type String
or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. At-
tributeValueList can contain one or more AttributeValue
elements of type String, Number, or Binary (not a set
type). These attributes are compared against an exist-
ing set type attribute of an item. If any elements of the
input set are present in the item attribute, the expression
evaluates to true.
· BETWEEN : Greater than or equal to the first value,
and less than or equal to the second value. Attribute-
ValueList must contain two AttributeValue elements of
the same type, either String, Number, or Binary (not
a set type). A target attribute matches if the target
value is greater than, or equal to, the first element and
less than, or equal to, the second element. If an item
contains an AttributeValue element of a different type
than the one provided in the request, the value does not
match. For example, {"S":"6"} does not compare
to {"N":"6"} . Also, {"N":"6"} does not com-
pare to {"NS":["6", "2", "1"]}
· AttributeValueList (list) –
One or more values to evaluate against the supplied at-
tribute. The number of values in the list depends on the
ComparisonOperator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals,
or less than are based on ASCII character code
values. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary
data as unsigned when it compares binary values.
For information on specifying data types in JSON, see
JSON Data Format in the Amazon DynamoDB Devel-
oper Guide .
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
Warning: This is a legacy parameter, for backward com
New applications should use ConditionExpression instead
• ConditionalOperator (string) – combine legacy parameters and expression parameters in a s
call; otherwise, DynamoDB will return a ValidationExcepti
tion.
A logical operator to apply to the conditions in the Expected map:
3.1. Services 1019
Boto3 Documentation, Release 1.1.4
– AND - If all of the conditions evaluate to true, then the entire map
evaluates to true.
– OR - If at least one of the conditions evaluate to true, then the entire
map evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ReturnValues (string) – Use ReturnValues if you want to get the item
attributes as they appeared before they were deleted. For DeleteItem , the
valid values are:
– NONE - If ReturnValues is not specified, or if its value is NONE , then
nothing is returned. (This setting is the default for ReturnValues .)
– ALL_OLD - The content of the old item is returned.
• ReturnConsumedCapacity (string) – Determines the level of detail about
provisioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapac-
ity for the operation, together with ConsumedCapacity for each table
and secondary index that was accessed. Note that some operations,
such as GetItem and BatchGetItem , do not access any indexes at all.
In these cases, specifying INDEXES will only return ConsumedCa-
pacity information for table(s).
– TOTAL - The response includes only the aggregate ConsumedCa-
pacity for the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ReturnItemCollectionMetrics (string) – Determines whether item col-
lection metrics are returned. If set to SIZE , the response includes statis-
tics about item collections, if any, that were modified during the operation
are returned in the response. If set to NONE (the default), no statistics are
returned.
• ConditionExpression (condition from
boto3.dynamodb.conditions.Attr method) – The condi-
tion(s) an attribute(s) must meet. Valid conditions are listed in the
DynamoDB Reference Guide.
• ExpressionAttributeNames (dict) – One or more substitution tokens for
attribute names in an expression. The following are some use cases for
using ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB re-
served word.
– To create a placeholder for repeating occurrences of an attribute
name in an expression.
– To prevent special characters in an attribute name from being mis-
interpreted in an expression.
Use the # character in an expression to dereference an attribute name. For
example, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be
used directly in an expression. (For the complete list of reserved words,
see Reserved Words in the Amazon DynamoDB Developer Guide ). To
work around this, you could specify the following for ExpressionAttribute-
Names :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
1020 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– #P = :val
Note: Tokens that begin with the : character are expression attribute
values , which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item
Attributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be sub-
stituted in an expression.
Use the : (colon) character in an expression to dereference an attribute
value. For example, suppose that you wanted to check whether the value
of the ProductStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"},
":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Con-
ditions in the Amazon DynamoDB Developer Guide .
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
Return type dict
Returns
Response Syntax
{
'Attributes': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set(
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
3.1. Services 1021
Boto3 Documentation, Release 1.1.4
'ItemCollectionMetrics': {
'ItemCollectionKey': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|
},
'SizeEstimateRangeGB': [
123.0,
]
}
}
Response Structure
• (dict) –
Represents the output of a DeleteItem operation.
– Attributes (dict) –
A map of attribute names to AttributeValue objects, representing
the item as it appeared before the DeleteItem operation. This
map appears in the response only if ReturnValues was specified as
ALL_OLD in the request.
* (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
* Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
1022 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The total number of capacity units consumed on a table
or an index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
– ItemCollectionMetrics (dict) –
Information about item collections, if any, that were affected by
the operation. ItemCollectionMetrics is only returned if the request
asked for it. If the table does not have any local secondary indexes,
this information is not returned in the response.
Each ItemCollectionMetrics element consists of:
* ItemCollectionKey - The hash key value of the item collection.
This is the same as the hash key of the item.
* SizeEstimateRange - An estimate of item collection size, in
gigabytes. This value is a two-element array containing a
lower bound and an upper bound for the estimate. The es-
timate includes the size of all the items in the table, plus the
size of all attributes projected into all of the local secondary
indexes on that table. Use this estimate to measure whether a
local secondary index is approaching its size limit. The esti-
mate is subject to change over time; therefore, do not rely on
the precision or accuracy of the estimate.
* ItemCollectionKey (dict) –
The hash key value of the item collection. This value is the
same as the hash key of the item.
· (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
* SizeEstimateRangeGB (list) –
An estimate of item collection size, in gigabytes. This value
is a two-element array containing a lower bound and an upper
bound for the estimate. The estimate includes the size of all
the items in the table, plus the size of all attributes projected
into all of the local secondary indexes on that table. Use this
estimate to measure whether a local secondary index is ap-
proaching its size limit.
The estimate is subject to change over time; therefore, do not
rely on the precision or accuracy of the estimate.
· (float) –
get_item(**kwargs)
The GetItem operation returns a set of attributes for the item with the given primary key. If there is
3.1. Services 1023
Boto3 Documentation, Release 1.1.4
no matching item, GetItem does not return any data.
GetItem provides an eventually consistent read by default. If your application requires a strongly
consistent read, set ConsistentRead to true . Although a strongly consistent read might take more
time than an eventually consistent read, it always returns the last updated value.
Request Syntax
response = table.get_item(
Key={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
},
AttributesToGet=[
'string',
],
ConsistentRead=True|False,
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ProjectionExpression='string',
ExpressionAttributeNames={
'string': 'string'
}
)
Parameters
• Key (dict) – [REQUIRED]
A map of attribute names to AttributeValue objects, representing the pri-
mary key of the item to retrieve.
For the primary key, you must provide all of the attributes. For example,
with a hash type primary key, you only need to provide the hash attribute.
For a hash-and-range type primary key, you must provide both the hash
attribute and the range attribute.
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
Warning: This is a legacy parameter, for backward compatibili
New applications should use ProjectionExpression instead. Do n
combine legacy parameters and expression parameters in a single A
• AttributesToGet (list) – call; otherwise, DynamoDB will return a ValidationException exce
tion.
This parameter allows you to retrieve attributes of type List or Ma
however, it cannot retrieve individual elements within a List or a Ma
The names of one or more attributes to retrieve. If no attribute names
are provided, then all attributes will be returned. If any of the requested
attributes are not found, they will not appear in the result.
Note that AttributesToGet has no effect on provisioned throughput con-
sumption. DynamoDB determines capacity units consumed based on item
size, not on the amount of data that is returned to an application.
– (string) –
• ConsistentRead (boolean) – Determines the read consistency model: If
set to true , then the operation uses strongly consistent reads; otherwise,
the operation uses eventually consistent reads.
1024 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• ReturnConsumedCapacity (string) – Determines the level of detail about
provisioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapac-
ity for the operation, together with ConsumedCapacity for each table
and secondary index that was accessed. Note that some operations,
such as GetItem and BatchGetItem , do not access any indexes at all.
In these cases, specifying INDEXES will only return ConsumedCa-
pacity information for table(s).
– TOTAL - The response includes only the aggregate ConsumedCa-
pacity for the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ProjectionExpression (string) – A string that identifies one or more at-
tributes to retrieve from the table. These attributes can include scalars,
sets, or elements of a JSON document. The attributes in the expression
must be separated by commas.
If no attribute names are specified, then all attributes will be returned. If
any of the requested attributes are not found, they will not appear in the
result.
For more information, see Accessing Item Attributes in the Amazon Dy-
namoDB Developer Guide .
Note: ProjectionExpression replaces the legacy AttributesToGet parame-
ter.
• ExpressionAttributeNames (dict) – One or more substitution tokens for
attribute names in an expression. The following are some use cases for
using ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB re-
served word.
– To create a placeholder for repeating occurrences of an attribute
name in an expression.
– To prevent special characters in an attribute name from being mis-
interpreted in an expression.
Use the # character in an expression to dereference an attribute name. For
example, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be
used directly in an expression. (For the complete list of reserved words,
see Reserved Words in the Amazon DynamoDB Developer Guide ). To
work around this, you could specify the following for ExpressionAttribute-
Names :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute
values , which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item
Attributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
Return type dict
Returns
3.1. Services 1025
Boto3 Documentation, Release 1.1.4
Response Syntax
{
'Item': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set(
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
}
}
Response Structure
• (dict) –
Represents the output of a GetItem operation.
– Item (dict) –
A map of attribute names to AttributeValue objects, as specified by
AttributesToGet .
* (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
* Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
1026 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The total number of capacity units consumed on a table
or an index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
load()
Calls dynamodb.Client.describe_table() to update the attributes of the Table resource
Request Syntax
table.load()
Returns None
put_item(**kwargs)
Creates a new item, or replaces an old item with a new item. If an item that has the same primary
key as the new item already exists in the specified table, the new item completely replaces the
existing item. You can perform a conditional put operation (add a new item if one with the specified
primary key doesn’t exist), or replace an existing item if it has certain attribute values.
In addition to putting an item, you can also return the item’s attribute values in the same operation,
using the ReturnValues parameter.
When you add an item, the primary key attribute(s) are the only required attributes. Attribute values
cannot be null. String and Binary type attributes must have lengths greater than zero. Set type
attributes cannot be empty. Requests with empty values will be rejected with a ValidationException
exception.
You can request that PutItem return either a copy of the original item (before the update) or a copy
of the updated item (after the update). For more information, see the ReturnValues description
below.
Note: To prevent a new item from replacing an existing item, use a conditional put operation with
ComparisonOperator set to NULL for the primary key attribute, or attributes.
3.1. Services 1027
Boto3 Documentation, Release 1.1.4
For more information about using this API, see Working with Items in the Amazon DynamoDB
Developer Guide .
Request Syntax
response = table.put_item(
Item={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
},
Expected={
'string': {
'Value': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])
'Exists': True|False,
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NUL
'AttributeValueList': [
'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|set(
]
}
},
ReturnValues='NONE'|'ALL_OLD'|'UPDATED_OLD'|'ALL_NEW'|'UPDATED_NEW',
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ReturnItemCollectionMetrics='SIZE'|'NONE',
ConditionalOperator='AND'|'OR',
ConditionExpression=Attr('myattribute').eq('myvalue'),
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
}
)
Parameters
• Item (dict) – [REQUIRED]
A map of attribute name/value pairs, one for each attribute. Only the pri-
mary key attributes are required; you can optionally provide other attribute
name-value pairs for the item.
You must provide all of the attributes for the primary key. For example,
with a hash type primary key, you only need to provide the hash attribute.
For a hash-and-range type primary key, you must provide both the hash
attribute and the range attribute.
If you specify any attributes that are part of an index key, then the data
types for those attributes must match those of the schema in the table’s
attribute definition.
For more information about primary keys, see Primary Key in the Amazon
DynamoDB Developer Guide .
Each element in the Item map is an AttributeValue object.
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
1028 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Warning: This is a legacy parameter, for backward compatibility.
New applications should use ConditionExpression instead. Do not
• Expected (dict) – combine legacy parameters and expression parameters in a single API
call; otherwise, DynamoDB will return a ValidationException excep-
tion.
A map of attribute/condition pairs. Expected provides a conditional block
for the PutItem operation.
Note: This parameter does not support attributes of type List or Map.
Each element of Expected consists of an attribute name, a comparison op-
erator, and one or more values. DynamoDB compares the attribute with
the value(s) you supplied, using the comparison operator. For each Ex-
pected element, the result of the evaluation is either true or false.
If you specify more than one element in the Expected map, then by default
all of the conditions must evaluate to true. In other words, the conditions
are ANDed together. (You can use the ConditionalOperator parameter to
OR the conditions instead. If you do this, then at least one of the conditions
must evaluate to true, rather than all of them.)
If the Expected map evaluates to true, then the conditional operation suc-
ceeds; otherwise, it fails.
Expected contains the following:
– AttributeValueList - One or more values to evaluate against
the supplied attribute. The number of values in the list de-
pends on the ComparisonOperator being used. For type
Number, value comparisons are numeric. String value com-
parisons for greater than, equals, or less than are based on
ASCII character code values. For example, a is greater than
A , and a is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters .
For type Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
– ComparisonOperator - A comparator for evaluating attributes in
the AttributeValueList . When performing the comparison, Dy-
namoDB uses strongly consistent reads. The following comparison
operators are available: EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN The following are descrip-
tions of each comparison operator. * EQ : Equal. EQ is supported
for all datatypes, including lists and maps. AttributeValueList can
contain only one AttributeValue element of type String, Number,
Binary, String Set, Number Set, or Binary Set. If an item contains
an AttributeValue element of a different type than the one provided
in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
– NE : Not equal. NE is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one AttributeValue
of type String, Number, Binary, String Set, Number Set, or Binary
Set. If an item contains an AttributeValue of a different type than the
one provided in the request, the value does not match. For example,
3.1. Services 1029
Boto3 Documentation, Release 1.1.4
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"}
does not equal {"NS":["6", "2", "1"]} .
– LE : Less than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– LT : Less than. AttributeValueList can contain only one Attribute-
Value of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one
provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"}
does not compare to {"NS":["6", "2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– GT : Greater than. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– NOT_NULL : The attribute exists. NOT_NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for
the existence of an attribute, not its data type. If the data type of
attribute “a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the attribute “a ”
exists; its data type is not relevant to the NOT_NULL comparison
operator.
– NULL : The attribute does not exist. NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for
the nonexistence of an attribute, not its data type. If the data type of
attribute “a ” is null, and you evaluate it using NULL , the result is
a Boolean false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
– CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element of type
String, Number, or Binary (not a set type). If the target attribute of
the comparison is of type String, then the operator checks for a sub-
string match. If the target attribute of the comparison is of type
Binary, then the operator looks for a subsequence of the target that
matches the input. If the target attribute of the comparison is a set
(“SS ”, “NS ”, or “BS ”), then the operator evaluates to true if it
finds an exact match with any member of the set. CONTAINS is
supported for lists: When evaluating “a CONTAINS b ”, “a ” can
be a list; however, “b ” cannot be a set, a map, or a list.
– NOT_CONTAINS : Checks for absence of a subsequence, or ab-
1030 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
sence of a value in a set. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If the target attribute of the comparison is a String, then the
operator checks for the absence of a substring match. If the target
attribute of the comparison is Binary, then the operator checks for
the absence of a subsequence of the target that matches the input.
If the target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is supported
for lists: When evaluating “a NOT CONTAINS b ”, “a ” can be a
list; however, “b ” cannot be a set, a map, or a list.
– BEGINS_WITH : Checks for a prefix. AttributeValueList can con-
tain only one AttributeValue of type String or Binary (not a Number
or a set type). The target attribute of the comparison must be of type
String or Binary (not a Number or a set type).
– IN : Checks for matching elements within two sets. AttributeVal-
ueList can contain one or more AttributeValue elements of type
String, Number, or Binary (not a set type). These attributes are
compared against an existing set type attribute of an item. If any
elements of the input set are present in the item attribute, the ex-
pression evaluates to true.
– BETWEEN : Greater than or equal to the first value, and less than
or equal to the second value. AttributeValueList must contain two
AttributeValue elements of the same type, either String, Number, or
Binary (not a set type). A target attribute matches if the target value
is greater than, or equal to, the first element and less than, or equal
to, the second element. If an item contains an AttributeValue ele-
ment of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not com-
pare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see
Legacy Conditional Parameters in the Amazon DynamoDB Developer
Guide .
For backward compatibility with previous DynamoDB releases, the fol-
lowing parameters can be used instead of AttributeValueList and Compar-
isonOperator :
– Value - A value for DynamoDB to compare with an attribute.
– Exists - A Boolean value that causes DynamoDB to evaluate the
value before attempting the conditional operation: * If Exists is
true , DynamoDB will check to see if that attribute value already
exists in the table. If it is found, then the condition evaluates to true;
otherwise the condition evaluate to false.
– If Exists is false , DynamoDB assumes that the attribute value
does not exist in the table. If in fact the value does not exist, then the
assumption is valid and the condition evaluates to true. If the value
is found, despite the assumption that it does not exist, the condition
evaluates to false.
Note that the default value for Exists is true .
The Value and Exists parameters are incompatible with AttributeValueList
and ComparisonOperator . Note that if you use both sets of parameters at
once, DynamoDB will return a ValidationException exception.
– (string) –
3.1. Services 1031
Boto3 Documentation, Release 1.1.4
* (dict) –
Represents a condition to be compared with an attribute value.
This condition can be used with DeleteItem , PutItem or Up-
dateItem operations; if the comparison evaluates to true, the
operation succeeds; if not, the operation fails. You can use
ExpectedAttributeValue in one of two different ways:
· Use AttributeValueList to specify one or more values to
compare against an attribute. Use ComparisonOpera-
tor to specify how you want to perform the comparison.
If the comparison evaluates to true, then the conditional
operation succeeds.
· Use Value to specify a value that DynamoDB will com-
pare against an attribute. If the values match, then Ex-
pectedAttributeValue evaluates to true and the condi-
tional operation succeeds. Optionally, you can also set
Exists to false, indicating that you do not expect to find
the attribute value in the table. In this case, the condi-
tional operation succeeds only if the comparison evalu-
ates to false.
Value and Exists are incompatible with AttributeValueList and
ComparisonOperator . Note that if you use both sets of pa-
rameters at once, DynamoDB will return a ValidationExcep-
tion exception.
· Value (valid DynamoDB type) – - The value of the
attribute. The valid value types are listed in the Dy-
namoDB Reference Guide.
· Exists (boolean) –
Causes DynamoDB to evaluate the value before at-
tempting a conditional operation:
· If Exists is true , DynamoDB will check to see if that
attribute value already exists in the table. If it is found,
then the operation succeeds. If it is not found, the op-
eration fails with a ConditionalCheckFailedException
.
· If Exists is false , DynamoDB assumes that the at-
tribute value does not exist in the table. If in fact the
value does not exist, then the assumption is valid and
the operation succeeds. If the value is found, despite
the assumption that it does not exist, the operation fails
with a ConditionalCheckFailedException .
The default setting for Exists is true . If you supply
a Value all by itself, DynamoDB assumes the attribute
exists: You don’t have to set Exists to true , because
it is implied.
DynamoDB returns a ValidationException if:
· Exists is true but there is no Value to check. (You
expect a value to exist, but don’t specify what that value
is.)
· Exists is false but you also provide a Value . (You
cannot expect an attribute to have a value, while also
expecting it not to exist.)
· ComparisonOperator (string) –
1032 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A comparator for evaluating attributes in the Attribute-
ValueList . For example, equals, greater than, less than,
etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS |
NOT_CONTAINS | BEGINS_WITH | IN |
BETWEEN
The following are descriptions of each comparison op-
erator.
· EQ : Equal. EQ is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can contain
only one AttributeValue element of type String, Num-
ber, Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the
value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can con-
tain only one AttributeValue of type String, Number,
Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue of a different type
than the one provided in the request, the value does
not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one
AttributeValue of type String, Number, or Binary (not a
set type). If an item contains an AttributeValue element
of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does
not compare to {"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only
3.1. Services 1033
Boto3 Documentation, Release 1.1.4
one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an Attribute-
Value element of a different type than the one provided
in the request, the value does not match. For exam-
ple, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is sup-
ported for all datatypes, including lists and maps. ..
note::This operator tests for the existence of an at-
tribute, not its data type. If the data type of attribute
“a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the at-
tribute “a ” exists; its data type is not relevant to the
NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported
for all datatypes, including lists and maps. .. note::This
operator tests for the nonexistence of an attribute, not
its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean
false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a
set. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not
a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring
match. If the target attribute of the comparison is of
type Binary, then the operator looks for a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or “BS
”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is sup-
ported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map,
or a list.
· NOT_CONTAINS : Checks for absence of a subse-
quence, or absence of a value in a set. AttributeVal-
ueList can contain only one AttributeValue element of
type String, Number, or Binary (not a set type). If the
target attribute of the comparison is a String, then the
operator checks for the absence of a substring match.
If the target attribute of the comparison is Binary, then
the operator checks for the absence of a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set.
NOT_CONTAINS is supported for lists: When eval-
uating “a NOT CONTAINS b ”, “a ” can be a list;
however, “b ” cannot be a set, a map, or a list.
· BEGINS_WITH : Checks for a prefix. AttributeVal-
ueList can contain only one AttributeValue of type
String or Binary (not a Number or a set type). The tar-
1034 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
get attribute of the comparison must be of type String
or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. At-
tributeValueList can contain one or more AttributeValue
elements of type String, Number, or Binary (not a set
type). These attributes are compared against an exist-
ing set type attribute of an item. If any elements of the
input set are present in the item attribute, the expression
evaluates to true.
· BETWEEN : Greater than or equal to the first value,
and less than or equal to the second value. Attribute-
ValueList must contain two AttributeValue elements of
the same type, either String, Number, or Binary (not
a set type). A target attribute matches if the target
value is greater than, or equal to, the first element and
less than, or equal to, the second element. If an item
contains an AttributeValue element of a different type
than the one provided in the request, the value does not
match. For example, {"S":"6"} does not compare
to {"N":"6"} . Also, {"N":"6"} does not com-
pare to {"NS":["6", "2", "1"]}
· AttributeValueList (list) –
One or more values to evaluate against the supplied at-
tribute. The number of values in the list depends on the
ComparisonOperator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals,
or less than are based on ASCII character code
values. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary
data as unsigned when it compares binary values.
For information on specifying data types in JSON, see
JSON Data Format in the Amazon DynamoDB Devel-
oper Guide .
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
• ReturnValues (string) – Use ReturnValues if you want to get the item
attributes as they appeared before they were updated with the PutItem re-
quest. For PutItem , the valid values are:
– NONE - If ReturnValues is not specified, or if its value is NONE , then
nothing is returned. (This setting is the default for ReturnValues .)
– ALL_OLD - If PutItem overwrote an attribute name-value pair, then
the content of the old item is returned.
Note: Other “Valid Values” are not relevant to PutItem.
• ReturnConsumedCapacity (string) – Determines the level of detail about
provisioned throughput consumption that is returned in the response:
3.1. Services 1035
Boto3 Documentation, Release 1.1.4
– INDEXES - The response includes the aggregate ConsumedCapac-
ity for the operation, together with ConsumedCapacity for each table
and secondary index that was accessed. Note that some operations,
such as GetItem and BatchGetItem , do not access any indexes at all.
In these cases, specifying INDEXES will only return ConsumedCa-
pacity information for table(s).
– TOTAL - The response includes only the aggregate ConsumedCa-
pacity for the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ReturnItemCollectionMetrics (string) – Determines whether item col-
lection metrics are returned. If set to SIZE , the response includes statis-
tics about item collections, if any, that were modified during the operation
are returned in the response. If set to NONE (the default), no statistics are
returned.
Warning: This is a legacy parameter, for backward com
New applications should use ConditionExpression instead
• ConditionalOperator (string) – combine legacy parameters and expression parameters in a s
call; otherwise, DynamoDB will return a ValidationExcepti
tion.
A logical operator to apply to the conditions in the Expected map:
– AND - If all of the conditions evaluate to true, then the entire map
evaluates to true.
– OR - If at least one of the conditions evaluate to true, then the entire
map evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ConditionExpression (condition from
boto3.dynamodb.conditions.Attr method) – The condi-
tion(s) an attribute(s) must meet. Valid conditions are listed in the
DynamoDB Reference Guide.
• ExpressionAttributeNames (dict) – One or more substitution tokens for
attribute names in an expression. The following are some use cases for
using ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB re-
served word.
– To create a placeholder for repeating occurrences of an attribute
name in an expression.
– To prevent special characters in an attribute name from being mis-
interpreted in an expression.
Use the # character in an expression to dereference an attribute name. For
example, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be
used directly in an expression. (For the complete list of reserved words,
see Reserved Words in the Amazon DynamoDB Developer Guide ). To
work around this, you could specify the following for ExpressionAttribute-
Names :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
1036 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– #P = :val
Note: Tokens that begin with the : character are expression attribute
values , which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item
Attributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be sub-
stituted in an expression.
Use the : (colon) character in an expression to dereference an attribute
value. For example, suppose that you wanted to check whether the value
of the ProductStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"},
":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Con-
ditions in the Amazon DynamoDB Developer Guide .
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
Return type dict
Returns
Response Syntax
{
'Attributes': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set(
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
3.1. Services 1037
Boto3 Documentation, Release 1.1.4
'ItemCollectionMetrics': {
'ItemCollectionKey': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|
},
'SizeEstimateRangeGB': [
123.0,
]
}
}
Response Structure
• (dict) –
Represents the output of a PutItem operation.
– Attributes (dict) –
The attribute values as they appeared before the PutItem operation,
but only if ReturnValues is specified as ALL_OLD in the request.
Each element consists of an attribute name and an attribute value.
* (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
* Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
1038 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
– ItemCollectionMetrics (dict) –
Information about item collections, if any, that were affected by
the operation. ItemCollectionMetrics is only returned if the request
asked for it. If the table does not have any local secondary indexes,
this information is not returned in the response.
Each ItemCollectionMetrics element consists of:
* ItemCollectionKey - The hash key value of the item collection.
This is the same as the hash key of the item.
* SizeEstimateRange - An estimate of item collection size, in
gigabytes. This value is a two-element array containing a
lower bound and an upper bound for the estimate. The es-
timate includes the size of all the items in the table, plus the
size of all attributes projected into all of the local secondary
indexes on that table. Use this estimate to measure whether a
local secondary index is approaching its size limit. The esti-
mate is subject to change over time; therefore, do not rely on
the precision or accuracy of the estimate.
* ItemCollectionKey (dict) –
The hash key value of the item collection. This value is the
same as the hash key of the item.
· (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
* SizeEstimateRangeGB (list) –
An estimate of item collection size, in gigabytes. This value
is a two-element array containing a lower bound and an upper
bound for the estimate. The estimate includes the size of all
the items in the table, plus the size of all attributes projected
into all of the local secondary indexes on that table. Use this
estimate to measure whether a local secondary index is ap-
proaching its size limit.
The estimate is subject to change over time; therefore, do not
rely on the precision or accuracy of the estimate.
· (float) –
query(**kwargs)
A Query operation uses the primary key of a table or a secondary index to directly access items
from that table or index.
3.1. Services 1039
Boto3 Documentation, Release 1.1.4
Use the KeyConditionExpression parameter to provide a specific hash key value. The Query opera-
tion will return all of the items from the table or index with that hash key value. You can optionally
narrow the scope of the Query operation by specifying a range key value and a comparison operator
in KeyConditionExpression . You can use the ScanIndexForward parameter to get results in forward
or reverse order, by range key or by index key.
Queries that do not return results consume the minimum number of read capacity units for that type
of read operation.
If the total number of items meeting the query criteria exceeds the result set size limit of 1 MB, the
query stops and results are returned to the user with the LastEvaluatedKey element to continue the
query in a subsequent operation. Unlike a Scan operation, a Query operation never returns both an
empty result set and a LastEvaluatedKey value. LastEvaluatedKey is only provided if the results
exceed 1 MB, or if you have used the Limit parameter.
You can query a table, a local secondary index, or a global secondary index. For a query on a table
or on a local secondary index, you can set the ConsistentRead parameter to true and obtain a
strongly consistent result. Global secondary indexes support eventually consistent reads only, so do
not specify ConsistentRead when querying a global secondary index.
Request Syntax
response = table.query(
IndexName='string',
Select='ALL_ATTRIBUTES'|'ALL_PROJECTED_ATTRIBUTES'|'SPECIFIC_ATTRIBUTES'|'COUNT',
AttributesToGet=[
'string',
],
Limit=123,
ConsistentRead=True|False,
KeyConditions={
'string': {
'AttributeValueList': [
'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|set(
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NUL
}
},
QueryFilter={
'string': {
'AttributeValueList': [
'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|set(
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NUL
}
},
ConditionalOperator='AND'|'OR',
ScanIndexForward=True|False,
ExclusiveStartKey={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
},
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ProjectionExpression='string',
FilterExpression=Attr('myattribute').eq('myvalue'),
KeyConditionExpression=Key('mykey').eq('myvalue'),
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
1040 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
}
)
Parameters
• IndexName (string) – The name of an index to query. This index can be
any local secondary index or global secondary index on the table. Note that
if you use the IndexName parameter, you must also provide TableName.
• Select (string) – The attributes to be returned in the result. You can retrieve
all item attributes, specific item attributes, the count of matching items, or
in the case of an index, some or all of the attributes projected into the
index.
– ALL_ATTRIBUTES - Returns all of the item attributes from the
specified table or index. If you query a local secondary index, then
for each matching item in the index DynamoDB will fetch the entire
item from the parent table. If the index is configured to project all
item attributes, then all of the data can be obtained from the local
secondary index, and no fetching is required.
– ALL_PROJECTED_ATTRIBUTES - Allowed only when querying
an index. Retrieves all attributes that have been projected into the
index. If the index is configured to project all attributes, this return
value is equivalent to specifying ALL_ATTRIBUTES .
– COUNT - Returns the number of matching items, rather than the
matching items themselves.
– SPECIFIC_ATTRIBUTES - Returns only the attributes listed in
AttributesToGet . This return value is equivalent to specifying At-
tributesToGet without specifying any value for Select . If you query
a local secondary index and request only attributes that are projected
into that index, the operation will read only the index and not the
table. If any of the requested attributes are not projected into the lo-
cal secondary index, DynamoDB will fetch each of these attributes
from the parent table. This extra fetching incurs additional through-
put cost and latency. If you query a global secondary index, you can
only request attributes that are projected into the index. Global sec-
ondary index queries cannot fetch attributes from the parent table.
If neither Select nor AttributesToGet are specified, DynamoDB
defaults to ALL_ATTRIBUTES when accessing a table, and
ALL_PROJECTED_ATTRIBUTES when accessing an index. You
cannot use both Select and AttributesToGet together in a single request,
unless the value for Select is SPECIFIC_ATTRIBUTES . (This usage is
equivalent to specifying AttributesToGet without any value for Select .)
Note: If you use the ProjectionExpression parameter, then the value for
Select can only be SPECIFIC_ATTRIBUTES . Any other value for Se-
lect will return an error.
Warning: This is a legacy parameter, for backward compatibili
New applications should use ProjectionExpression instead. Do n
combine legacy parameters and expression parameters in a single A
• AttributesToGet (list) – call; otherwise, DynamoDB will return a ValidationException exce
tion.
This parameter allows you to retrieve attributes of type List or Ma
however, it cannot retrieve individual elements within a List or a Ma
3.1. Services 1041
Boto3 Documentation, Release 1.1.4
The names of one or more attributes to retrieve. If no attribute names
are provided, then all attributes will be returned. If any of the requested
attributes are not found, they will not appear in the result.
Note that AttributesToGet has no effect on provisioned throughput con-
sumption. DynamoDB determines capacity units consumed based on item
size, not on the amount of data that is returned to an application.
You cannot use both AttributesToGet and Select together in a Query re-
quest, unless the value for Select is SPECIFIC_ATTRIBUTES . (This
usage is equivalent to specifying AttributesToGet without any value for
Select .)
If you query a local secondary index and request only attributes that are
projected into that index, the operation will read only the index and not
the table. If any of the requested attributes are not projected into the local
secondary index, DynamoDB will fetch each of these attributes from the
parent table. This extra fetching incurs additional throughput cost and
latency.
If you query a global secondary index, you can only request attributes that
are projected into the index. Global secondary index queries cannot fetch
attributes from the parent table.
– (string) –
• Limit (integer) – The maximum number of items to evaluate (not neces-
sarily the number of matching items). If DynamoDB processes the number
of items up to the limit while processing the results, it stops the operation
and returns the matching values up to that point, and a key in LastEvalu-
atedKey to apply in a subsequent operation, so that you can pick up where
you left off. Also, if the processed data set size exceeds 1 MB before Dy-
namoDB reaches this limit, it stops the operation and returns the matching
values up to the limit, and a key in LastEvaluatedKey to apply in a sub-
sequent operation to continue the operation. For more information, see
Query and Scan in the Amazon DynamoDB Developer Guide .
• ConsistentRead (boolean) – Determines the read consistency model: If
set to true , then the operation uses strongly consistent reads; otherwise,
the operation uses eventually consistent reads.
Strongly consistent reads are not supported on global secondary indexes.
If you query a global secondary index with ConsistentRead set to true ,
you will receive a ValidationException .
Warning: This is a legacy parameter, for backward compatibilit
New applications should use KeyConditionExpression instead. Do no
• KeyConditions (dict) – combine legacy parameters and expression parameters in a single AP
call; otherwise, DynamoDB will return a ValidationException excep
tion.
The selection criteria for the query. For a query on a table, you can have
conditions only on the table primary key attributes. You must provide the
hash key attribute name and value as an EQ condition. You can optionally
provide a second condition, referring to the range key attribute.
Note: If you don’t provide a range key condition, all of the items that
match the hash key will be retrieved. If a FilterExpression or QueryFilter
is present, it will be applied after the items are retrieved.
1042 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
For a query on an index, you can have conditions only on the index key
attributes. You must provide the index hash attribute name and value as an
EQ condition. You can optionally provide a second condition, referring to
the index key range attribute.
Each KeyConditions element consists of an attribute name to compare,
along with the following:
– AttributeValueList - One or more values to evaluate against
the supplied attribute. The number of values in the list de-
pends on the ComparisonOperator being used. For type
Number, value comparisons are numeric. String value com-
parisons for greater than, equals, or less than are based on
ASCII character code values. For example, a is greater than
A , and a is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
. For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
– ComparisonOperator - A comparator for evaluating attributes,
for example, equals, greater than, less than, and so on. For
KeyConditions , only the following comparison operators are
supported: EQ | LE | LT | GE | GT | BEGINS_WITH
| BETWEEN The following are descriptions of these comparison
operators. * EQ : Equal. AttributeValueList can contain only one At-
tributeValue of type String, Number, or Binary (not a set type). If an
item contains an AttributeValue element of a different type than the
one specified in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"}
does not equal {"NS":["6", "2", "1"]} .
– LE : Less than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– LT : Less than. AttributeValueList can contain only one Attribute-
Value of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one
provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"}
does not compare to {"NS":["6", "2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– GT : Greater than. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
3.1. Services 1043
Boto3 Documentation, Release 1.1.4
.
– BEGINS_WITH : Checks for a prefix. AttributeValueList can con-
tain only one AttributeValue of type String or Binary (not a Number
or a set type). The target attribute of the comparison must be of type
String or Binary (not a Number or a set type).
– BETWEEN : Greater than or equal to the first value, and less than
or equal to the second value. AttributeValueList must contain two
AttributeValue elements of the same type, either String, Number, or
Binary (not a set type). A target attribute matches if the target value
is greater than, or equal to, the first element and less than, or equal
to, the second element. If an item contains an AttributeValue ele-
ment of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not com-
pare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see
Legacy Conditional Parameters in the Amazon DynamoDB Developer
Guide .
– (string) –
* (dict) –
Represents the selection criteria for a Query or Scan opera-
tion:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an
index. For KeyConditions , only the following compar-
ison operators are supported: EQ | LE | LT | GE
| GT | BEGINS_WITH | BETWEEN Condition is
also used in a QueryFilter , which evaluates the query
results and returns only the desired values.
· For a Scan operation, Condition is used in a ScanFilter
, which evaluates the scan results and returns only the
desired values.
· AttributeValueList (list) –
One or more values to evaluate against the supplied at-
tribute. The number of values in the list depends on the
ComparisonOperator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals,
or less than are based on ASCII character code
values. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary
data as unsigned when it compares binary values.
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example,
1044 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
equals, greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS |
NOT_CONTAINS | BEGINS_WITH | IN |
BETWEEN
The following are descriptions of each comparison op-
erator.
· EQ : Equal. EQ is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can contain
only one AttributeValue element of type String, Num-
ber, Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the
value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can con-
tain only one AttributeValue of type String, Number,
Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue of a different type
than the one provided in the request, the value does
not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one
AttributeValue of type String, Number, or Binary (not a
set type). If an item contains an AttributeValue element
of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does
not compare to {"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only
one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an Attribute-
3.1. Services 1045
Boto3 Documentation, Release 1.1.4
Value element of a different type than the one provided
in the request, the value does not match. For exam-
ple, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is sup-
ported for all datatypes, including lists and maps. ..
note::This operator tests for the existence of an at-
tribute, not its data type. If the data type of attribute
“a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the at-
tribute “a ” exists; its data type is not relevant to the
NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported
for all datatypes, including lists and maps. .. note::This
operator tests for the nonexistence of an attribute, not
its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean
false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a
set. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not
a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring
match. If the target attribute of the comparison is of
type Binary, then the operator looks for a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or “BS
”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is sup-
ported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map,
or a list.
· NOT_CONTAINS : Checks for absence of a subse-
quence, or absence of a value in a set. AttributeVal-
ueList can contain only one AttributeValue element of
type String, Number, or Binary (not a set type). If the
target attribute of the comparison is a String, then the
operator checks for the absence of a substring match.
If the target attribute of the comparison is Binary, then
the operator checks for the absence of a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set.
NOT_CONTAINS is supported for lists: When eval-
uating “a NOT CONTAINS b ”, “a ” can be a list;
however, “b ” cannot be a set, a map, or a list.
· BEGINS_WITH : Checks for a prefix. AttributeVal-
ueList can contain only one AttributeValue of type
String or Binary (not a Number or a set type). The tar-
get attribute of the comparison must be of type String
or Binary (not a Number or a set type).
1046 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· IN : Checks for matching elements within two sets. At-
tributeValueList can contain one or more AttributeValue
elements of type String, Number, or Binary (not a set
type). These attributes are compared against an exist-
ing set type attribute of an item. If any elements of the
input set are present in the item attribute, the expression
evaluates to true.
· BETWEEN : Greater than or equal to the first value,
and less than or equal to the second value. Attribute-
ValueList must contain two AttributeValue elements of
the same type, either String, Number, or Binary (not
a set type). A target attribute matches if the target
value is greater than, or equal to, the first element and
less than, or equal to, the second element. If an item
contains an AttributeValue element of a different type
than the one provided in the request, the value does not
match. For example, {"S":"6"} does not compare
to {"N":"6"} . Also, {"N":"6"} does not com-
pare to {"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and Compar-
isonOperator , see Legacy Conditional Parameters in
the Amazon DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward compatibility.
New applications should use FilterExpression instead. Do not com-
• QueryFilter (dict) –
bine legacy parameters and expression parameters in a single API call;
otherwise, DynamoDB will return a ValidationException exception.
A condition that evaluates the query results after the items are read and
returns only the desired values.
This parameter does not support attributes of type List or Map.
Note: A QueryFilter is applied after the items have already been read; the
process of filtering does not consume any additional read capacity units.
If you provide more than one condition in the QueryFilter map, then by
default all of the conditions must evaluate to true. In other words, the
conditions are ANDed together. (You can use the ConditionalOperator
parameter to OR the conditions instead. If you do this, then at least one of
the conditions must evaluate to true, rather than all of them.)
Note that QueryFilter does not allow key attributes. You cannot define a
filter condition on a hash key or range key.
Each QueryFilter element consists of an attribute name to compare, along
with the following:
– AttributeValueList - One or more values to evaluate against the
supplied attribute. The number of values in the list depends
on the operator specified in ComparisonOperator . For type
Number, value comparisons are numeric. String value com-
parisons for greater than, equals, or less than are based on
ASCII character code values. For example, a is greater than
A , and a is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters .
3.1. Services 1047
Boto3 Documentation, Release 1.1.4
For type Binary, DynamoDB treats each byte of the binary data
as unsigned when it compares binary values. For information
on specifying data types in JSON, see JSON Data Format in the
Amazon DynamoDB Developer Guide .
– ComparisonOperator - A comparator for evaluating attributes.
For example, equals, greater than, less than, etc. The follow-
ing comparison operators are available: EQ | NE | LE |
LT | GE | GT | NOT_NULL | NULL | CONTAINS
| NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN
For complete descriptions of all comparison operators, see the
Condition data type.
– (string) –
* (dict) –
Represents the selection criteria for a Query or Scan opera-
tion:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an
index. For KeyConditions , only the following compar-
ison operators are supported: EQ | LE | LT | GE
| GT | BEGINS_WITH | BETWEEN Condition is
also used in a QueryFilter , which evaluates the query
results and returns only the desired values.
· For a Scan operation, Condition is used in a ScanFilter
, which evaluates the scan results and returns only the
desired values.
· AttributeValueList (list) –
One or more values to evaluate against the supplied at-
tribute. The number of values in the list depends on the
ComparisonOperator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals,
or less than are based on ASCII character code
values. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary
data as unsigned when it compares binary values.
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example,
equals, greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS |
NOT_CONTAINS | BEGINS_WITH | IN |
BETWEEN
1048 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The following are descriptions of each comparison op-
erator.
· EQ : Equal. EQ is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can contain
only one AttributeValue element of type String, Num-
ber, Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the
value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can con-
tain only one AttributeValue of type String, Number,
Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue of a different type
than the one provided in the request, the value does
not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one
AttributeValue of type String, Number, or Binary (not a
set type). If an item contains an AttributeValue element
of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does
not compare to {"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· GT : Greater than. AttributeValueList can contain only
one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an Attribute-
Value element of a different type than the one provided
in the request, the value does not match. For exam-
ple, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is sup-
ported for all datatypes, including lists and maps. ..
note::This operator tests for the existence of an at-
3.1. Services 1049
Boto3 Documentation, Release 1.1.4
tribute, not its data type. If the data type of attribute
“a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the at-
tribute “a ” exists; its data type is not relevant to the
NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported
for all datatypes, including lists and maps. .. note::This
operator tests for the nonexistence of an attribute, not
its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean
false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a
set. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not
a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring
match. If the target attribute of the comparison is of
type Binary, then the operator looks for a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or “BS
”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is sup-
ported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map,
or a list.
· NOT_CONTAINS : Checks for absence of a subse-
quence, or absence of a value in a set. AttributeVal-
ueList can contain only one AttributeValue element of
type String, Number, or Binary (not a set type). If the
target attribute of the comparison is a String, then the
operator checks for the absence of a substring match.
If the target attribute of the comparison is Binary, then
the operator checks for the absence of a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set.
NOT_CONTAINS is supported for lists: When eval-
uating “a NOT CONTAINS b ”, “a ” can be a list;
however, “b ” cannot be a set, a map, or a list.
· BEGINS_WITH : Checks for a prefix. AttributeVal-
ueList can contain only one AttributeValue of type
String or Binary (not a Number or a set type). The tar-
get attribute of the comparison must be of type String
or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. At-
tributeValueList can contain one or more AttributeValue
elements of type String, Number, or Binary (not a set
type). These attributes are compared against an exist-
ing set type attribute of an item. If any elements of the
input set are present in the item attribute, the expression
evaluates to true.
· BETWEEN : Greater than or equal to the first value,
1050 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
and less than or equal to the second value. Attribute-
ValueList must contain two AttributeValue elements of
the same type, either String, Number, or Binary (not
a set type). A target attribute matches if the target
value is greater than, or equal to, the first element and
less than, or equal to, the second element. If an item
contains an AttributeValue element of a different type
than the one provided in the request, the value does not
match. For example, {"S":"6"} does not compare
to {"N":"6"} . Also, {"N":"6"} does not com-
pare to {"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and Compar-
isonOperator , see Legacy Conditional Parameters in
the Amazon DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward com
New applications should use FilterExpression instead. Do
• ConditionalOperator (string) –
bine legacy parameters and expression parameters in a single
otherwise, DynamoDB will return a ValidationException ex
A logical operator to apply to the conditions in a QueryFilter map:
– AND - If all of the conditions evaluate to true, then the entire map
evaluates to true.
– OR - If at least one of the conditions evaluate to true, then the entire
map evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ScanIndexForward (boolean) – Specifies the order in which to return the
query results - either ascending (true ) or descending (false ).
Items with the same hash key are stored in sorted order by range key .If
the range key data type is Number, the results are stored in numeric order.
For type String, the results are returned in order of ASCII character code
values. For type Binary, DynamoDB treats each byte of the binary data as
unsigned.
If ScanIndexForward is true , DynamoDB returns the results in order,
by range key. This is the default behavior.
If ScanIndexForward is false , DynamoDB sorts the results in descend-
ing order by range key, and then returns the results to the client.
• ExclusiveStartKey (dict) – The primary key of the first item that this oper-
ation will evaluate. Use the value that was returned for LastEvaluatedKey
in the previous operation.
The data type for ExclusiveStartKey must be String, Number or Binary.
No set data types are allowed.
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
• ReturnConsumedCapacity (string) – Determines the level of detail about
3.1. Services 1051
Boto3 Documentation, Release 1.1.4
provisioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapac-
ity for the operation, together with ConsumedCapacity for each table
and secondary index that was accessed. Note that some operations,
such as GetItem and BatchGetItem , do not access any indexes at all.
In these cases, specifying INDEXES will only return ConsumedCa-
pacity information for table(s).
– TOTAL - The response includes only the aggregate ConsumedCa-
pacity for the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ProjectionExpression (string) – A string that identifies one or more at-
tributes to retrieve from the table. These attributes can include scalars,
sets, or elements of a JSON document. The attributes in the expression
must be separated by commas.
If no attribute names are specified, then all attributes will be returned. If
any of the requested attributes are not found, they will not appear in the
result.
For more information, see Accessing Item Attributes in the Amazon Dy-
namoDB Developer Guide .
Note: ProjectionExpression replaces the legacy AttributesToGet parame-
ter.
• FilterExpression (condition from boto3.dynamodb.conditions.Attr
method) – The condition(s) an attribute(s) must meet. Valid conditions
are listed in the DynamoDB Reference Guide.
• KeyConditionExpression (condition from
boto3.dynamodb.conditions.Key method) – The condi-
tion(s) a key(s) must meet. Valid conditions are listed in the DynamoDB
Reference Guide.
• ExpressionAttributeNames (dict) – One or more substitution tokens for
attribute names in an expression. The following are some use cases for
using ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB re-
served word.
– To create a placeholder for repeating occurrences of an attribute
name in an expression.
– To prevent special characters in an attribute name from being mis-
interpreted in an expression.
Use the # character in an expression to dereference an attribute name. For
example, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be
used directly in an expression. (For the complete list of reserved words,
see Reserved Words in the Amazon DynamoDB Developer Guide ). To
work around this, you could specify the following for ExpressionAttribute-
Names :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute
values , which are placeholders for the actual value at runtime.
1052 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
For more information on expression attribute names, see Accessing Item
Attributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be sub-
stituted in an expression.
Use the : (colon) character in an expression to dereference an attribute
value. For example, suppose that you wanted to check whether the value
of the ProductStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"},
":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Con-
ditions in the Amazon DynamoDB Developer Guide .
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
Return type dict
Returns
Response Syntax
{
'Items': [
{
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|
},
],
'Count': 123,
'ScannedCount': 123,
'LastEvaluatedKey': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set(
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
3.1. Services 1053
Boto3 Documentation, Release 1.1.4
}
}
}
Response Structure
• (dict) –
Represents the output of a Query operation.
– Items (list) –
An array of item attributes that match the query criteria. Each el-
ement in this array consists of an attribute name and the value for
that attribute.
* (dict) –
· (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
– Count (integer) –
The number of items in the response.
If you used a QueryFilter in the request, then Count is the number
of items returned after the filter was applied, and ScannedCount is
the number of matching items beforethe filter was applied.
If you did not use a filter in the request, then Count and Scanned-
Count are the same.
– ScannedCount (integer) –
The number of items evaluated, before any QueryFilter is applied.
A high ScannedCount value with few, or no, Count results indicates
an inefficient Query operation. For more information, see Count and
ScannedCount in the Amazon DynamoDB Developer Guide .
If you did not use a filter in the request, then ScannedCount is the
same as Count .
– LastEvaluatedKey (dict) –
The primary key of the item where the operation stopped, inclusive
of the previous result set. Use this value to start a new operation,
excluding this value in the new request.
If LastEvaluatedKey is empty, then the “last page” of results has
been processed and there is no more data to be retrieved.
If LastEvaluatedKey is not empty, it does not necessarily mean that
there is more data in the result set. The only way to know when you
have reached the end of the result set is when LastEvaluatedKey is
empty.
* (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
1054 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
* Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
reload()
Calls dynamodb.Client.describe_table() to update the attributes of the Table resource
Request Syntax
table.reload()
Returns None
scan(**kwargs)
The Scan operation returns one or more items and item attributes by accessing every item in a
table or a secondary index. To have DynamoDB return fewer items, you can provide a ScanFilter
operation.
If the total number of scanned items exceeds the maximum data set size limit of 1 MB, the scan
stops and results are returned to the user as a LastEvaluatedKey value to continue the scan in a
3.1. Services 1055
Boto3 Documentation, Release 1.1.4
subsequent operation. The results also include the number of items exceeding the limit. A scan can
result in no table data meeting the filter criteria.
By default, Scan operations proceed sequentially; however, for faster performance on a large table
or secondary index, applications can request a parallel Scan operation by providing the Segment
and TotalSegments parameters. For more information, see Parallel Scan in the Amazon DynamoDB
Developer Guide .
By default, Scan uses eventually consistent reads when acessing the data in the table or local sec-
ondary index. However, you can use strongly consistent reads instead by setting the ConsistentRead
parameter to true .
Request Syntax
response = table.scan(
IndexName='string',
AttributesToGet=[
'string',
],
Limit=123,
Select='ALL_ATTRIBUTES'|'ALL_PROJECTED_ATTRIBUTES'|'SPECIFIC_ATTRIBUTES'|'COUNT',
ScanFilter={
'string': {
'AttributeValueList': [
'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|set(
],
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NUL
}
},
ConditionalOperator='AND'|'OR',
ExclusiveStartKey={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
},
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
TotalSegments=123,
Segment=123,
ProjectionExpression='string',
FilterExpression=Attr('myattribute').eq('myvalue'),
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
},
ConsistentRead=True|False
)
Parameters
• IndexName (string) – The name of a secondary index to scan. This index
can be any local secondary index or global secondary index. Note that if
you use the IndexName parameter, you must also provide TableName
.
1056 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Warning: This is a legacy parameter, for backward compatibili
New applications should use ProjectionExpression instead. Do n
combine legacy parameters and expression parameters in a single A
• AttributesToGet (list) – call; otherwise, DynamoDB will return a ValidationException exce
tion.
This parameter allows you to retrieve attributes of type List or Ma
however, it cannot retrieve individual elements within a List or a Ma
The names of one or more attributes to retrieve. If no attribute names
are provided, then all attributes will be returned. If any of the requested
attributes are not found, they will not appear in the result.
Note that AttributesToGet has no effect on provisioned throughput con-
sumption. DynamoDB determines capacity units consumed based on item
size, not on the amount of data that is returned to an application.
– (string) –
• Limit (integer) – The maximum number of items to evaluate (not neces-
sarily the number of matching items). If DynamoDB processes the number
of items up to the limit while processing the results, it stops the operation
and returns the matching values up to that point, and a key in LastEvalu-
atedKey to apply in a subsequent operation, so that you can pick up where
you left off. Also, if the processed data set size exceeds 1 MB before Dy-
namoDB reaches this limit, it stops the operation and returns the matching
values up to the limit, and a key in LastEvaluatedKey to apply in a sub-
sequent operation to continue the operation. For more information, see
Query and Scan in the Amazon DynamoDB Developer Guide .
• Select (string) – The attributes to be returned in the result. You can retrieve
all item attributes, specific item attributes, or the count of matching items.
– ALL_ATTRIBUTES - Returns all of the item attributes.
– COUNT - Returns the number of matching items, rather than the
matching items themselves.
– SPECIFIC_ATTRIBUTES - Returns only the attributes listed in
AttributesToGet . This return value is equivalent to specifying At-
tributesToGet without specifying any value for Select .
If neither Select nor AttributesToGet are specified, DynamoDB de-
faults to ALL_ATTRIBUTES . You cannot use both AttributesToGet
and Select together in a single request, unless the value for Select is
SPECIFIC_ATTRIBUTES . (This usage is equivalent to specifying At-
tributesToGet without any value for Select .)
Warning: This is a legacy parameter, for backward compatibility.
New applications should use FilterExpression instead. Do not com-
• ScanFilter (dict) –
bine legacy parameters and expression parameters in a single API call;
otherwise, DynamoDB will return a ValidationException exception.
A condition that evaluates the scan results and returns only the desired
values.
Note: This parameter does not support attributes of type List or Map.
If you specify more than one condition in the ScanFilter map, then by
default all of the conditions must evaluate to true. In other words, the
conditions are ANDed together. (You can use the ConditionalOperator
parameter to OR the conditions instead. If you do this, then at least one of
3.1. Services 1057
Boto3 Documentation, Release 1.1.4
the conditions must evaluate to true, rather than all of them.)
Each ScanFilter element consists of an attribute name to compare, along
with the following:
– AttributeValueList - One or more values to evaluate against the
supplied attribute. The number of values in the list depends
on the operator specified in ComparisonOperator . For type
Number, value comparisons are numeric. String value com-
parisons for greater than, equals, or less than are based on
ASCII character code values. For example, a is greater than
A , and a is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
. For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values. For information on
specifying data types in JSON, see JSON Data Format in the
Amazon DynamoDB Developer Guide .
– ComparisonOperator - A comparator for evaluating attributes.
For example, equals, greater than, less than, etc. The follow-
ing comparison operators are available: EQ | NE | LE |
LT | GE | GT | NOT_NULL | NULL | CONTAINS |
NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN For
complete descriptions of all comparison operators, see Condition .
– (string) –
* (dict) –
Represents the selection criteria for a Query or Scan opera-
tion:
· For a Query operation, Condition is used for specifying
the KeyConditions to use when querying a table or an
index. For KeyConditions , only the following compar-
ison operators are supported: EQ | LE | LT | GE
| GT | BEGINS_WITH | BETWEEN Condition is
also used in a QueryFilter , which evaluates the query
results and returns only the desired values.
· For a Scan operation, Condition is used in a ScanFilter
, which evaluates the scan results and returns only the
desired values.
· AttributeValueList (list) –
One or more values to evaluate against the supplied at-
tribute. The number of values in the list depends on the
ComparisonOperator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals,
or less than are based on ASCII character code
values. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary
data as unsigned when it compares binary values.
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
1058 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
erence Guide.
· ComparisonOperator (string) – [REQUIRED]
A comparator for evaluating attributes. For example,
equals, greater than, less than, etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS |
NOT_CONTAINS | BEGINS_WITH | IN |
BETWEEN
The following are descriptions of each comparison op-
erator.
· EQ : Equal. EQ is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can contain
only one AttributeValue element of type String, Num-
ber, Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the
value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can con-
tain only one AttributeValue of type String, Number,
Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue of a different type
than the one provided in the request, the value does
not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one
AttributeValue of type String, Number, or Binary (not a
set type). If an item contains an AttributeValue element
of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does
not compare to {"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
3.1. Services 1059
Boto3 Documentation, Release 1.1.4
· GT : Greater than. AttributeValueList can contain only
one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an Attribute-
Value element of a different type than the one provided
in the request, the value does not match. For exam-
ple, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is sup-
ported for all datatypes, including lists and maps. ..
note::This operator tests for the existence of an at-
tribute, not its data type. If the data type of attribute
“a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the at-
tribute “a ” exists; its data type is not relevant to the
NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported
for all datatypes, including lists and maps. .. note::This
operator tests for the nonexistence of an attribute, not
its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean
false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a
set. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not
a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring
match. If the target attribute of the comparison is of
type Binary, then the operator looks for a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or “BS
”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is sup-
ported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map,
or a list.
· NOT_CONTAINS : Checks for absence of a subse-
quence, or absence of a value in a set. AttributeVal-
ueList can contain only one AttributeValue element of
type String, Number, or Binary (not a set type). If the
target attribute of the comparison is a String, then the
operator checks for the absence of a substring match.
If the target attribute of the comparison is Binary, then
the operator checks for the absence of a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set.
NOT_CONTAINS is supported for lists: When eval-
uating “a NOT CONTAINS b ”, “a ” can be a list;
however, “b ” cannot be a set, a map, or a list.
· BEGINS_WITH : Checks for a prefix. AttributeVal-
ueList can contain only one AttributeValue of type
1060 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
String or Binary (not a Number or a set type). The tar-
get attribute of the comparison must be of type String
or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. At-
tributeValueList can contain one or more AttributeValue
elements of type String, Number, or Binary (not a set
type). These attributes are compared against an exist-
ing set type attribute of an item. If any elements of the
input set are present in the item attribute, the expression
evaluates to true.
· BETWEEN : Greater than or equal to the first value,
and less than or equal to the second value. Attribute-
ValueList must contain two AttributeValue elements of
the same type, either String, Number, or Binary (not
a set type). A target attribute matches if the target
value is greater than, or equal to, the first element and
less than, or equal to, the second element. If an item
contains an AttributeValue element of a different type
than the one provided in the request, the value does not
match. For example, {"S":"6"} does not compare
to {"N":"6"} . Also, {"N":"6"} does not com-
pare to {"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and Compar-
isonOperator , see Legacy Conditional Parameters in
the Amazon DynamoDB Developer Guide .
Warning: This is a legacy parameter, for backward com
New applications should use FilterExpression instead. Do
• ConditionalOperator (string) –
bine legacy parameters and expression parameters in a single
otherwise, DynamoDB will return a ValidationException ex
A logical operator to apply to the conditions in a ScanFilter map:
– AND - If all of the conditions evaluate to true, then the entire map
evaluates to true.
– OR - If at least one of the conditions evaluate to true, then the entire
map evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ExclusiveStartKey (dict) – The primary key of the first item that this oper-
ation will evaluate. Use the value that was returned for LastEvaluatedKey
in the previous operation.
The data type for ExclusiveStartKey must be String, Number or Binary.
No set data types are allowed.
In a parallel scan, a Scan request that includes ExclusiveStartKey must
specify the same segment whose previous Scan returned the corresponding
value of LastEvaluatedKey .
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
3.1. Services 1061
Boto3 Documentation, Release 1.1.4
Guide.
• ReturnConsumedCapacity (string) – Determines the level of detail about
provisioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapac-
ity for the operation, together with ConsumedCapacity for each table
and secondary index that was accessed. Note that some operations,
such as GetItem and BatchGetItem , do not access any indexes at all.
In these cases, specifying INDEXES will only return ConsumedCa-
pacity information for table(s).
– TOTAL - The response includes only the aggregate ConsumedCa-
pacity for the operation.
– NONE - No ConsumedCapacity details are included in the response.
• TotalSegments (integer) – For a parallel Scan request, TotalSegments rep-
resents the total number of segments into which the Scan operation will
be divided. The value of TotalSegments corresponds to the number of ap-
plication workers that will perform the parallel scan. For example, if you
want to use four application threads to scan a table or an index, specify a
TotalSegments value of 4.
The value for TotalSegments must be greater than or equal to 1, and less
than or equal to 1000000. If you specify a TotalSegments value of 1, the
Scan operation will be sequential rather than parallel.
If you specify TotalSegments , you must also specify Segment .
• Segment (integer) – For a parallel Scan request, Segment identifies an
individual segment to be scanned by an application worker.
Segment IDs are zero-based, so the first segment is always 0. For example,
if you want to use four application threads to scan a table or an index, then
the first thread specifies a Segment value of 0, the second thread specifies
1, and so on.
The value of LastEvaluatedKey returned from a parallel Scan request must
be used as ExclusiveStartKey with the same segment ID in a subsequent
Scan operation.
The value for Segment must be greater than or equal to 0, and less than the
value provided for TotalSegments .
If you provide Segment , you must also provide TotalSegments .
• ProjectionExpression (string) – A string that identifies one or more at-
tributes to retrieve from the specified table or index. These attributes can
include scalars, sets, or elements of a JSON document. The attributes in
the expression must be separated by commas.
If no attribute names are specified, then all attributes will be returned. If
any of the requested attributes are not found, they will not appear in the
result.
For more information, see Accessing Item Attributes in the Amazon Dy-
namoDB Developer Guide .
Note: ProjectionExpression replaces the legacy AttributesToGet parame-
ter.
• FilterExpression (condition from boto3.dynamodb.conditions.Attr
method) – The condition(s) an attribute(s) must meet. Valid conditions
are listed in the DynamoDB Reference Guide.
1062 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• ExpressionAttributeNames (dict) – One or more substitution tokens for
attribute names in an expression. The following are some use cases for
using ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB re-
served word.
– To create a placeholder for repeating occurrences of an attribute
name in an expression.
– To prevent special characters in an attribute name from being mis-
interpreted in an expression.
Use the # character in an expression to dereference an attribute name. For
example, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be
used directly in an expression. (For the complete list of reserved words,
see Reserved Words in the Amazon DynamoDB Developer Guide ). To
work around this, you could specify the following for ExpressionAttribute-
Names :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute
values , which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item
Attributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be sub-
stituted in an expression.
Use the : (colon) character in an expression to dereference an attribute
value. For example, suppose that you wanted to check whether the value
of the ProductStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"},
":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Con-
ditions in the Amazon DynamoDB Developer Guide .
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
• ConsistentRead (boolean) – A Boolean value that determines the read
consistency model during the scan:
– If ConsistentRead is false , then Scan will use eventually consis-
tent reads. The data returned from Scan might not contain the results
3.1. Services 1063
Boto3 Documentation, Release 1.1.4
of other recently completed write operations (PutItem, UpdateItem
or DeleteItem). The Scan response might include some stale data.
– If ConsistentRead is true , then Scan will use strongly consistent
reads. All of the write operations that completed before the Scan
began are guaranteed to be contained in the Scan response.
The default setting for ConsistentRead is false , meaning that eventually
consistent reads will be used.
Strongly consistent reads are not supported on global secondary indexes.
If you scan a global secondary index with ConsistentRead set to true, you
will receive a ValidationException .
Return type dict
Returns
Response Syntax
{
'Items': [
{
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|
},
],
'Count': 123,
'ScannedCount': 123,
'LastEvaluatedKey': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set(
},
'ConsumedCapacity': {
'TableName': 'string',
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
}
}
Response Structure
• (dict) –
Represents the output of a Scan operation.
– Items (list) –
An array of item attributes that match the scan criteria. Each element
in this array consists of an attribute name and the value for that
attribute.
* (dict) –
· (string) –
1064 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
– Count (integer) –
The number of items in the response.
If you set ScanFilter in the request, then Count is the number of
items returned after the filter was applied, and ScannedCount is the
number of matching items before the filter was applied.
If you did not use a filter in the request, then Count is the same as
ScannedCount .
– ScannedCount (integer) –
The number of items evaluated, before any ScanFilter is applied. A
high ScannedCount value with few, or no, Count results indicates
an inefficient Scan operation. For more information, see Count and
ScannedCount in the Amazon DynamoDB Developer Guide .
If you did not use a filter in the request, then ScannedCount is the
same as Count .
– LastEvaluatedKey (dict) –
The primary key of the item where the operation stopped, inclusive
of the previous result set. Use this value to start a new operation,
excluding this value in the new request.
If LastEvaluatedKey is empty, then the “last page” of results has
been processed and there is no more data to be retrieved.
If LastEvaluatedKey is not empty, it does not necessarily mean that
there is more data in the result set. The only way to know when you
have reached the end of the result set is when LastEvaluatedKey is
empty.
* (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
* Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
3.1. Services 1065
Boto3 Documentation, Release 1.1.4
The total number of capacity units consumed on a table
or an index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
update(**kwargs)
Modifies the provisioned throughput settings, global secondary indexes, or DynamoDB Streams
settings for a given table.
You can only perform one of the following operations at once:
•Modify the provisioned throughput settings of the table.
•Enable or disable Streams on the table.
•Remove a global secondary index from the table.
•Create a new global secondary index on the table. Once the index begins backfilling, you can
use UpdateTable to perform other operations.
UpdateTable is an asynchronous operation; while it is executing, the table status changes from
ACTIVE to UPDATING . While it is UPDATING , you cannot issue another UpdateTable request.
When the table returns to the ACTIVE state, the UpdateTable operation is complete.
Request Syntax
table = table.update(
AttributeDefinitions=[
{
'AttributeName': 'string',
'AttributeType': 'S'|'N'|'B'
},
],
ProvisionedThroughput={
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
},
GlobalSecondaryIndexUpdates=[
{
'Update': {
1066 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'IndexName': 'string',
'ProvisionedThroughput': {
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
}
},
'Create': {
'IndexName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Projection': {
'ProjectionType': 'ALL'|'KEYS_ONLY'|'INCLUDE',
'NonKeyAttributes': [
'string',
]
},
'ProvisionedThroughput': {
'ReadCapacityUnits': 123,
'WriteCapacityUnits': 123
}
},
'Delete': {
'IndexName': 'string'
}
},
],
StreamSpecification={
'StreamEnabled': True|False,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_ONLY'
}
)
Parameters
• AttributeDefinitions (list) – An array of attributes that describe the key
schema for the table and indexes. If you are adding a new global secondary
index to the table, AttributeDefinitions must include the key element(s) of
the new index.
– (dict) –
Represents an attribute for describing the key schema for the table
and indexes.
* AttributeName (string) – [REQUIRED]
A name for the attribute.
* AttributeType (string) – [REQUIRED]
The data type for the attribute.
• ProvisionedThroughput (dict) – Represents the provisioned throughput
settings for a specified table or index. The settings can be modified using
the UpdateTable operation.
For current minimum and maximum provisioned throughput values, see
Limits in the Amazon DynamoDB Developer Guide .
– ReadCapacityUnits (integer) – [REQUIRED]
3.1. Services 1067
Boto3 Documentation, Release 1.1.4
The maximum number of strongly consistent reads consumed per
second before DynamoDB returns a ThrottlingException . For more
information, see Specifying Read and Write Requirements in the
Amazon DynamoDB Developer Guide .
– WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per second before Dy-
namoDB returns a ThrottlingException . For more information,
see Specifying Read and Write Requirements in the Amazon Dy-
namoDB Developer Guide .
• GlobalSecondaryIndexUpdates (list) – An array of one or more global
secondary indexes for the table. For each index in the array, you can re-
quest one action:
– Create - add a new global secondary index to the table.
– Update - modify the provisioned throughput settings of an existing
global secondary index.
– Delete - remove a global secondary index from the table.
For more information, see Managing Global Secondary Indexes in the
Amazon DynamoDB Developer Guide .
– (dict) –
Represents one of the following:
* A new global secondary index to be added to an existing table.
* New provisioned throughput parameters for an existing global
secondary index.
* An existing global secondary index to be removed from an
existing table.
* Update (dict) –
The name of an existing global secondary index, along with
new provisioned throughput settings to be applied to that in-
dex.
· IndexName (string) – [REQUIRED]
The name of the global secondary index to be updated.
· ProvisionedThroughput (dict) – [REQUIRED]
Represents the provisioned throughput settings for a
specified table or index. The settings can be modified
using the UpdateTable operation.
For current minimum and maximum provisioned
throughput values, see Limits in the Amazon Dy-
namoDB Developer Guide .
· ReadCapacityUnits (integer) – [REQUIRED]
The maximum number of strongly consistent reads
consumed per second before DynamoDB returns a
ThrottlingException . For more information, see Speci-
fying Read and Write Requirements in the Amazon Dy-
namoDB Developer Guide .
· WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per sec-
ond before DynamoDB returns a ThrottlingException
. For more information, see Specifying Read and Write
Requirements in the Amazon DynamoDB Developer
1068 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Guide .
* Create (dict) –
The parameters required for creating a global secondary index
on an existing table:
· IndexName
· KeySchema
· AttributeDefinitions
· Projection
· ProvisionedThroughput
· IndexName (string) – [REQUIRED]
The name of the global secondary index to be created.
· KeySchema (list) – [REQUIRED]
The key schema for the global secondary index.
· (dict) –
Represents a single element of a key schema. A key
schema specifies the attributes that make up the primary
key of a table, or the key attributes of an index.
A KeySchemaElement represents exactly one attribute
of the primary key. For example, a hash type primary
key would be represented by one KeySchemaElement .
A hash-and-range type primary key would require one
KeySchemaElement for the hash attribute, and another
KeySchemaElement for the range attribute.
· AttributeName (string) – [REQUIRED]
The name of a key attribute.
· KeyType (string) – [REQUIRED]
The attribute data, consisting of the data type and the
attribute value itself.
· Projection (dict) – [REQUIRED]
Represents attributes that are copied (projected) from
the table into an index. These are in addition to the
primary key attributes and index key attributes, which
are automatically projected.
· ProjectionType (string) –
The set of attributes that are projected into the index:
· KEYS_ONLY - Only the index and primary keys are
projected into the index.
· INCLUDE - Only the specified table attributes are pro-
jected into the index. The list of projected attributes are
in NonKeyAttributes .
· ALL - All of the table attributes are projected into the
index.
· NonKeyAttributes (list) –
Represents the non-key attribute names which will be
projected into the index.
For local secondary indexes, the total count of Non-
KeyAttributes summed across all of the local secondary
indexes, must not exceed 20. If you project the same
3.1. Services 1069
Boto3 Documentation, Release 1.1.4
attribute into two different indexes, this counts as two
distinct attributes when determining the total.
· (string) –
· ProvisionedThroughput (dict) – [REQUIRED]
Represents the provisioned throughput settings for a
specified table or index. The settings can be modified
using the UpdateTable operation.
For current minimum and maximum provisioned
throughput values, see Limits in the Amazon Dy-
namoDB Developer Guide .
· ReadCapacityUnits (integer) – [REQUIRED]
The maximum number of strongly consistent reads
consumed per second before DynamoDB returns a
ThrottlingException . For more information, see Speci-
fying Read and Write Requirements in the Amazon Dy-
namoDB Developer Guide .
· WriteCapacityUnits (integer) – [REQUIRED]
The maximum number of writes consumed per sec-
ond before DynamoDB returns a ThrottlingException
. For more information, see Specifying Read and Write
Requirements in the Amazon DynamoDB Developer
Guide .
* Delete (dict) –
The name of an existing global secondary index to be re-
moved.
· IndexName (string) – [REQUIRED]
The name of the global secondary index to be deleted.
• StreamSpecification (dict) – Represents the DynamoDB Streams config-
uration for the table.
Note: You will receive a ResourceInUseException if you attempt to en-
able a stream on a table that already has a stream, or if you attempt to
disable a stream on a table which does not have a stream.
– StreamEnabled (boolean) –
Indicates whether DynamoDB Streams is enabled (true) or disabled
(false) on the table.
– StreamViewType (string) –
The DynamoDB Streams settings for the table. These settings con-
sist of:
* StreamEnabled - Indicates whether DynamoDB Streams is
enabled (true) or disabled (false) on the table.
* StreamViewType - When an item in the table is modified,
StreamViewType determines what information is written to the
stream for this table. Valid values for StreamViewType are: *
KEYS_ONLY - Only the key attributes of the modified item
are written to the stream.
* NEW_IMAGE - The entire item, as it appears after it was
modified, is written to the stream.
1070 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* OLD_IMAGE - The entire item, as it appeared before it was
modified, is written to the stream.
* NEW_AND_OLD_IMAGES - Both the new and the old item
images of the item are written to the stream.
Return type dynamodb.Table
Returns Table resource
update_item(**kwargs)
Edits an existing item’s attributes, or adds a new item to the table if it does not already exist. You
can put, delete, or add attribute values. You can also perform a conditional update on an existing
item (insert a new attribute name-value pair if it doesn’t exist, or replace an existing name-value
pair if it has certain expected attribute values). If conditions are specified and the item does not
exist, then the operation fails and a new item is not created.
You can also return the item’s attribute values in the same UpdateItem operation using the Return-
Values parameter.
Request Syntax
response = table.update_item(
Key={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
},
AttributeUpdates={
'string': {
'Value': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])
'Action': 'ADD'|'PUT'|'DELETE'
}
},
Expected={
'string': {
'Value': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])
'Exists': True|False,
'ComparisonOperator': 'EQ'|'NE'|'IN'|'LE'|'LT'|'GE'|'GT'|'BETWEEN'|'NOT_NUL
'AttributeValueList': [
'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|set(
]
}
},
ConditionalOperator='AND'|'OR',
ReturnValues='NONE'|'ALL_OLD'|'UPDATED_OLD'|'ALL_NEW'|'UPDATED_NEW',
ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
ReturnItemCollectionMetrics='SIZE'|'NONE',
UpdateExpression='string',
ConditionExpression=Attr('myattribute').eq('myvalue'),
ExpressionAttributeNames={
'string': 'string'
},
ExpressionAttributeValues={
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set([123])|se
}
)
Parameters
• Key (dict) – [REQUIRED]
The primary key of the item to be updated. Each element consists of an
attribute name and a value for that attribute.
3.1. Services 1071
Boto3 Documentation, Release 1.1.4
For the primary key, you must provide all of the attributes. For example,
with a hash type primary key, you only need to provide the hash attribute.
For a hash-and-range type primary key, you must provide both the hash
attribute and the range attribute.
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
Warning: This is a legacy parameter, for backward compatib
New applications should use UpdateExpression instead. Do not c
bine legacy parameters and expression parameters in a single API
• AttributeUpdates (dict) –
otherwise, DynamoDB will return a ValidationException exceptio
This parameter can be used for modifying top-level attributes; h
ever, it does not support individual list or map elements.
The names of attributes to be modified, the action to perform on each, and
the new value for each. If you are updating an attribute that is an index
key attribute for any indexes on that table, the attribute type must match the
index key type defined in the AttributesDefinition of the table description.
You can use UpdateItem to update any nonkey attributes.
Attribute values cannot be null. String and Binary type attributes must
have lengths greater than zero. Set type attributes must not be empty.
Requests with empty values will be rejected with a ValidationException
exception.
Each AttributeUpdates element consists of an attribute name to modify,
along with the following:
– Value - The new value, if applicable, for this attribute.
– Action - A value that specifies how to perform the update. This ac-
tion is only valid for an existing attribute whose data type is Number
or is a set; do not use ADD for other data types. If an item with the
specified primary key is found in the table, the following values per-
form the following actions: * PUT - Adds the specified attribute to
the item. If the attribute already exists, it is replaced by the new
value.
– DELETE - Removes the attribute and its value, if no value is speci-
fied for DELETE . The data type of the specified value must match
the existing value’s data type. If a set of values is specified, then
those values are subtracted from the old set. For example, if the
attribute value was the set [a,b,c] and the DELETE action spec-
ifies [a,c] , then the final attribute value is [b] . Specifying an
empty set is an error.
– ADD - Adds the specified value to the item, if the attribute does not
already exist. If the attribute does exist, then the behavior of ADD de-
pends on the data type of the attribute: * If the existing attribute is a
number, and if Value is also a number, then Value is mathematically
added to the existing attribute. If Value is a negative number, then
it is subtracted from the existing attribute. .. note:: If you use ADD
to increment or decrement a number value for an item that doesn’t
exist before the update, DynamoDB uses 0 as the initial value. Sim-
ilarly, if you use ADD for an existing item to increment or decrement
an attribute value that doesn’t exist before the update, DynamoDB
uses 0 as the initial value. For example, suppose that the item you
1072 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
want to update doesn’t have an attribute named itemcount , but you
decide to ADD the number 3 to this attribute anyway. DynamoDB
will create the itemcount attribute, set its initial value to 0 , and fi-
nally add 3 to it. The result will be a new itemcount attribute, with
a value of 3 .
– If the existing data type is a set, and if Value is also a set, then Value
is appended to the existing set. For example, if the attribute value
is the set [1,2] , and the ADD action specified [3] , then the final
attribute value is [1,2,3] . An error occurs if an ADD action is
specified for a set attribute and the attribute type specified does not
match the existing set type. Both sets must have the same primitive
data type. For example, if the existing data type is a set of strings,
Value must also be a set of strings.
If no item with the specified key is found in the table, the following values
perform the following actions:
– PUT - Causes DynamoDB to create a new item with the specified
primary key, and then adds the attribute.
– DELETE - Nothing happens, because attributes cannot be deleted
from a nonexistent item. The operation succeeds, but DynamoDB
does not create a new item.
– ADD - Causes DynamoDB to create an item with the supplied pri-
mary key and number (or set of numbers) for the attribute value.
The only data types allowed are Number and Number Set.
If you provide any attributes that are part of an index key, then the data
types for those attributes must match those of the schema in the table’s
attribute definition.
– (string) –
* (dict) –
For the UpdateItem operation, represents the attributes to be
modified, the action to perform on each, and the new value
for each.
Note: You cannot use UpdateItem to update any primary key
attributes. Instead, you will need to delete the item, and then
use PutItem to create a new item with new attributes.
Attribute values cannot be null; string and binary type at-
tributes must have lengths greater than zero; and set type at-
tributes must not be empty. Requests with empty values will
be rejected with a ValidationException exception.
· Value (valid DynamoDB type) – - The value of the
attribute. The valid value types are listed in the Dy-
namoDB Reference Guide.
· Action (string) –
Specifies how to perform the update. Valid values are
PUT (default), DELETE , and ADD . The behavior de-
pends on whether the specified primary key already ex-
ists in the table.
If an item with the specified *Key* is
found in the table:
· PUT - Adds the specified attribute to the item. If the
attribute already exists, it is replaced by the new value.
· DELETE - If no value is specified, the attribute and
3.1. Services 1073
Boto3 Documentation, Release 1.1.4
its value are removed from the item. The data type of
the specified value must match the existing value’s data
type. If a set of values is specified, then those values
are subtracted from the old set. For example, if the at-
tribute value was the set [a,b,c] and the DELETE
action specified [a,c] , then the final attribute value
would be [b] . Specifying an empty set is an error.
· ADD - If the attribute does not already exist, then the
attribute and its values are added to the item. If the at-
tribute does exist, then the behavior of ADD depends on
the data type of the attribute: * If the existing attribute
is a number, and if Value is also a number, then the
Value is mathematically added to the existing attribute.
If Value is a negative number, then it is subtracted from
the existing attribute. .. note:: If you use ADD to in-
crement or decrement a number value for an item that
doesn’t exist before the update, DynamoDB uses 0 as
the initial value. In addition, if you use ADD to update
an existing item, and intend to increment or decrement
an attribute value which does not yet exist, DynamoDB
uses 0 as the initial value. For example, suppose that
the item you want to update does not yet have an at-
tribute named itemcount , but you decide to ADD the
number 3 to this attribute anyway, even though it cur-
rently does not exist. DynamoDB will create the item-
count attribute, set its initial value to 0 , and finally add
3 to it. The result will be a new itemcount attribute in
the item, with a value of 3 .
· If the existing data type is a set, and if the Value is also
a set, then the Value is added to the existing set. (This is
a set operation, not mathematical addition.) For exam-
ple, if the attribute value was the set [1,2] , and the
ADD action specified [3] , then the final attribute value
would be [1,2,3] . An error occurs if an Add ac-
tion is specified for a set attribute and the attribute type
specified does not match the existing set type. Both sets
must have the same primitive data type. For example, if
the existing data type is a set of strings, the Value must
also be a set of strings. The same holds true for number
sets and binary sets.
This action is only valid for an existing attribute whose
data type is number or is a set. Do not use ADD for any
other data types.
If no item with the specified *Key* is
found:
· PUT - DynamoDB creates a new item with the specified
primary key, and then adds the attribute.
· DELETE - Nothing happens; there is no attribute to
delete.
· ADD - DynamoDB creates an item with the supplied
primary key and number (or set of numbers) for the at-
tribute value. The only data types allowed are number
and number set; no other data types can be specified.
1074 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Warning: This is a legacy parameter, for backward compatibility.
New applications should use ConditionExpression instead. Do not
• Expected (dict) – combine legacy parameters and expression parameters in a single API
call; otherwise, DynamoDB will return a ValidationException excep-
tion.
A map of attribute/condition pairs. Expected provides a conditional block
for the UpdateItem operation.
Each element of Expected consists of an attribute name, a comparison op-
erator, and one or more values. DynamoDB compares the attribute with
the value(s) you supplied, using the comparison operator. For each Ex-
pected element, the result of the evaluation is either true or false.
If you specify more than one element in the Expected map, then by default
all of the conditions must evaluate to true. In other words, the conditions
are ANDed together. (You can use the ConditionalOperator parameter to
OR the conditions instead. If you do this, then at least one of the conditions
must evaluate to true, rather than all of them.)
If the Expected map evaluates to true, then the conditional operation suc-
ceeds; otherwise, it fails.
Expected contains the following:
– AttributeValueList - One or more values to evaluate against
the supplied attribute. The number of values in the list de-
pends on the ComparisonOperator being used. For type
Number, value comparisons are numeric. String value com-
parisons for greater than, equals, or less than are based on
ASCII character code values. For example, a is greater than
A , and a is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters .
For type Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values.
– ComparisonOperator - A comparator for evaluating attributes in
the AttributeValueList . When performing the comparison, Dy-
namoDB uses strongly consistent reads. The following comparison
operators are available: EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS | NOT_CONTAINS |
BEGINS_WITH | IN | BETWEEN The following are descrip-
tions of each comparison operator. * EQ : Equal. EQ is supported
for all datatypes, including lists and maps. AttributeValueList can
contain only one AttributeValue element of type String, Number,
Binary, String Set, Number Set, or Binary Set. If an item contains
an AttributeValue element of a different type than the one provided
in the request, the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
– NE : Not equal. NE is supported for all datatypes, including lists
and maps. AttributeValueList can contain only one AttributeValue
of type String, Number, Binary, String Set, Number Set, or Binary
Set. If an item contains an AttributeValue of a different type than the
one provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"}
does not equal {"NS":["6", "2", "1"]} .
3.1. Services 1075
Boto3 Documentation, Release 1.1.4
– LE : Less than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– LT : Less than. AttributeValueList can contain only one Attribute-
Value of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one
provided in the request, the value does not match. For example,
{"S":"6"} does not equal {"N":"6"} . Also, {"N":"6"}
does not compare to {"NS":["6", "2", "1"]} .
– GE : Greater than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– GT : Greater than. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type
than the one provided in the request, the value does not match.
For example, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6", "2", "1"]}
.
– NOT_NULL : The attribute exists. NOT_NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for
the existence of an attribute, not its data type. If the data type of
attribute “a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the attribute “a ”
exists; its data type is not relevant to the NOT_NULL comparison
operator.
– NULL : The attribute does not exist. NULL is supported for all
datatypes, including lists and maps. .. note::This operator tests for
the nonexistence of an attribute, not its data type. If the data type of
attribute “a ” is null, and you evaluate it using NULL , the result is
a Boolean false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
– CONTAINS : Checks for a subsequence, or value in a set. At-
tributeValueList can contain only one AttributeValue element of type
String, Number, or Binary (not a set type). If the target attribute of
the comparison is of type String, then the operator checks for a sub-
string match. If the target attribute of the comparison is of type
Binary, then the operator looks for a subsequence of the target that
matches the input. If the target attribute of the comparison is a set
(“SS ”, “NS ”, or “BS ”), then the operator evaluates to true if it
finds an exact match with any member of the set. CONTAINS is
supported for lists: When evaluating “a CONTAINS b ”, “a ” can
be a list; however, “b ” cannot be a set, a map, or a list.
– NOT_CONTAINS : Checks for absence of a subsequence, or ab-
sence of a value in a set. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
1076 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
type). If the target attribute of the comparison is a String, then the
operator checks for the absence of a substring match. If the target
attribute of the comparison is Binary, then the operator checks for
the absence of a subsequence of the target that matches the input.
If the target attribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does not find an exact
match with any member of the set. NOT_CONTAINS is supported
for lists: When evaluating “a NOT CONTAINS b ”, “a ” can be a
list; however, “b ” cannot be a set, a map, or a list.
– BEGINS_WITH : Checks for a prefix. AttributeValueList can con-
tain only one AttributeValue of type String or Binary (not a Number
or a set type). The target attribute of the comparison must be of type
String or Binary (not a Number or a set type).
– IN : Checks for matching elements within two sets. AttributeVal-
ueList can contain one or more AttributeValue elements of type
String, Number, or Binary (not a set type). These attributes are
compared against an existing set type attribute of an item. If any
elements of the input set are present in the item attribute, the ex-
pression evaluates to true.
– BETWEEN : Greater than or equal to the first value, and less than
or equal to the second value. AttributeValueList must contain two
AttributeValue elements of the same type, either String, Number, or
Binary (not a set type). A target attribute matches if the target value
is greater than, or equal to, the first element and less than, or equal
to, the second element. If an item contains an AttributeValue ele-
ment of a different type than the one provided in the request, the
value does not match. For example, {"S":"6"} does not com-
pare to {"N":"6"} . Also, {"N":"6"} does not compare to
{"NS":["6", "2", "1"]}
For usage examples of AttributeValueList and ComparisonOperator , see
Legacy Conditional Parameters in the Amazon DynamoDB Developer
Guide .
For backward compatibility with previous DynamoDB releases, the fol-
lowing parameters can be used instead of AttributeValueList and Compar-
isonOperator :
– Value - A value for DynamoDB to compare with an attribute.
– Exists - A Boolean value that causes DynamoDB to evaluate the
value before attempting the conditional operation: * If Exists is
true , DynamoDB will check to see if that attribute value already
exists in the table. If it is found, then the condition evaluates to true;
otherwise the condition evaluate to false.
– If Exists is false , DynamoDB assumes that the attribute value
does not exist in the table. If in fact the value does not exist, then the
assumption is valid and the condition evaluates to true. If the value
is found, despite the assumption that it does not exist, the condition
evaluates to false.
Note that the default value for Exists is true .
The Value and Exists parameters are incompatible with AttributeValueList
and ComparisonOperator . Note that if you use both sets of parameters at
once, DynamoDB will return a ValidationException exception.
Note: This parameter does not support attributes of type List or Map.
3.1. Services 1077
Boto3 Documentation, Release 1.1.4
– (string) –
* (dict) –
Represents a condition to be compared with an attribute value.
This condition can be used with DeleteItem , PutItem or Up-
dateItem operations; if the comparison evaluates to true, the
operation succeeds; if not, the operation fails. You can use
ExpectedAttributeValue in one of two different ways:
· Use AttributeValueList to specify one or more values to
compare against an attribute. Use ComparisonOpera-
tor to specify how you want to perform the comparison.
If the comparison evaluates to true, then the conditional
operation succeeds.
· Use Value to specify a value that DynamoDB will com-
pare against an attribute. If the values match, then Ex-
pectedAttributeValue evaluates to true and the condi-
tional operation succeeds. Optionally, you can also set
Exists to false, indicating that you do not expect to find
the attribute value in the table. In this case, the condi-
tional operation succeeds only if the comparison evalu-
ates to false.
Value and Exists are incompatible with AttributeValueList and
ComparisonOperator . Note that if you use both sets of pa-
rameters at once, DynamoDB will return a ValidationExcep-
tion exception.
· Value (valid DynamoDB type) – - The value of the
attribute. The valid value types are listed in the Dy-
namoDB Reference Guide.
· Exists (boolean) –
Causes DynamoDB to evaluate the value before at-
tempting a conditional operation:
· If Exists is true , DynamoDB will check to see if that
attribute value already exists in the table. If it is found,
then the operation succeeds. If it is not found, the op-
eration fails with a ConditionalCheckFailedException
.
· If Exists is false , DynamoDB assumes that the at-
tribute value does not exist in the table. If in fact the
value does not exist, then the assumption is valid and
the operation succeeds. If the value is found, despite
the assumption that it does not exist, the operation fails
with a ConditionalCheckFailedException .
The default setting for Exists is true . If you supply
a Value all by itself, DynamoDB assumes the attribute
exists: You don’t have to set Exists to true , because
it is implied.
DynamoDB returns a ValidationException if:
· Exists is true but there is no Value to check. (You
expect a value to exist, but don’t specify what that value
is.)
· Exists is false but you also provide a Value . (You
cannot expect an attribute to have a value, while also
expecting it not to exist.)
1078 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· ComparisonOperator (string) –
A comparator for evaluating attributes in the Attribute-
ValueList . For example, equals, greater than, less than,
etc.
The following comparison operators are available:
EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS |
NOT_CONTAINS | BEGINS_WITH | IN |
BETWEEN
The following are descriptions of each comparison op-
erator.
· EQ : Equal. EQ is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can contain
only one AttributeValue element of type String, Num-
ber, Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue element of a dif-
ferent type than the one provided in the request, the
value does not match. For example, {"S":"6"} does
not equal {"N":"6"} . Also, {"N":"6"} does not
equal {"NS":["6", "2", "1"]} .
· NE : Not equal. NE is supported for all datatypes, in-
cluding lists and maps. AttributeValueList can con-
tain only one AttributeValue of type String, Number,
Binary, String Set, Number Set, or Binary Set. If
an item contains an AttributeValue of a different type
than the one provided in the request, the value does
not match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not equal
{"NS":["6", "2", "1"]} .
· LE : Less than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
· LT : Less than. AttributeValueList can contain only one
AttributeValue of type String, Number, or Binary (not a
set type). If an item contains an AttributeValue element
of a different type than the one provided in the request,
the value does not match. For example, {"S":"6"}
does not equal {"N":"6"} . Also, {"N":"6"} does
not compare to {"NS":["6", "2", "1"]} .
· GE : Greater than or equal. AttributeValueList can con-
tain only one AttributeValue element of type String,
Number, or Binary (not a set type). If an item con-
tains an AttributeValue element of a different type than
the one provided in the request, the value does not
match. For example, {"S":"6"} does not equal
{"N":"6"} . Also, {"N":"6"} does not compare
to {"NS":["6", "2", "1"]} .
3.1. Services 1079
Boto3 Documentation, Release 1.1.4
· GT : Greater than. AttributeValueList can contain only
one AttributeValue element of type String, Number, or
Binary (not a set type). If an item contains an Attribute-
Value element of a different type than the one provided
in the request, the value does not match. For exam-
ple, {"S":"6"} does not equal {"N":"6"} . Also,
{"N":"6"} does not compare to {"NS":["6",
"2", "1"]} .
· NOT_NULL : The attribute exists. NOT_NULL is sup-
ported for all datatypes, including lists and maps. ..
note::This operator tests for the existence of an at-
tribute, not its data type. If the data type of attribute
“a ” is null, and you evaluate it using NOT_NULL , the
result is a Boolean true . This result is because the at-
tribute “a ” exists; its data type is not relevant to the
NOT_NULL comparison operator.
· NULL : The attribute does not exist. NULL is supported
for all datatypes, including lists and maps. .. note::This
operator tests for the nonexistence of an attribute, not
its data type. If the data type of attribute “a ” is null,
and you evaluate it using NULL , the result is a Boolean
false . This is because the attribute “a ” exists; its data
type is not relevant to the NULL comparison operator.
· CONTAINS : Checks for a subsequence, or value in a
set. AttributeValueList can contain only one Attribute-
Value element of type String, Number, or Binary (not
a set type). If the target attribute of the comparison is
of type String, then the operator checks for a substring
match. If the target attribute of the comparison is of
type Binary, then the operator looks for a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or “BS
”), then the operator evaluates to true if it finds an exact
match with any member of the set. CONTAINS is sup-
ported for lists: When evaluating “a CONTAINS b ”,
“a ” can be a list; however, “b ” cannot be a set, a map,
or a list.
· NOT_CONTAINS : Checks for absence of a subse-
quence, or absence of a value in a set. AttributeVal-
ueList can contain only one AttributeValue element of
type String, Number, or Binary (not a set type). If the
target attribute of the comparison is a String, then the
operator checks for the absence of a substring match.
If the target attribute of the comparison is Binary, then
the operator checks for the absence of a subsequence
of the target that matches the input. If the target at-
tribute of the comparison is a set (“SS ”, “NS ”, or
“BS ”), then the operator evaluates to true if it does
not find an exact match with any member of the set.
NOT_CONTAINS is supported for lists: When eval-
uating “a NOT CONTAINS b ”, “a ” can be a list;
however, “b ” cannot be a set, a map, or a list.
· BEGINS_WITH : Checks for a prefix. AttributeVal-
ueList can contain only one AttributeValue of type
1080 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
String or Binary (not a Number or a set type). The tar-
get attribute of the comparison must be of type String
or Binary (not a Number or a set type).
· IN : Checks for matching elements within two sets. At-
tributeValueList can contain one or more AttributeValue
elements of type String, Number, or Binary (not a set
type). These attributes are compared against an exist-
ing set type attribute of an item. If any elements of the
input set are present in the item attribute, the expression
evaluates to true.
· BETWEEN : Greater than or equal to the first value,
and less than or equal to the second value. Attribute-
ValueList must contain two AttributeValue elements of
the same type, either String, Number, or Binary (not
a set type). A target attribute matches if the target
value is greater than, or equal to, the first element and
less than, or equal to, the second element. If an item
contains an AttributeValue element of a different type
than the one provided in the request, the value does not
match. For example, {"S":"6"} does not compare
to {"N":"6"} . Also, {"N":"6"} does not com-
pare to {"NS":["6", "2", "1"]}
· AttributeValueList (list) –
One or more values to evaluate against the supplied at-
tribute. The number of values in the list depends on the
ComparisonOperator being used.
For type Number, value comparisons are numeric.
String value comparisons for greater than, equals,
or less than are based on ASCII character code
values. For example, a is greater than A , and a
is greater than B . For a list of code values, see
http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters
.
For Binary, DynamoDB treats each byte of the binary
data as unsigned when it compares binary values.
For information on specifying data types in JSON, see
JSON Data Format in the Amazon DynamoDB Devel-
oper Guide .
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
Warning: This is a legacy parameter, for backward com
New applications should use ConditionExpression instead
• ConditionalOperator (string) – combine legacy parameters and expression parameters in a s
call; otherwise, DynamoDB will return a ValidationExcepti
tion.
A logical operator to apply to the conditions in the Expected map:
– AND - If all of the conditions evaluate to true, then the entire map
evaluates to true.
3.1. Services 1081
Boto3 Documentation, Release 1.1.4
– OR - If at least one of the conditions evaluate to true, then the entire
map evaluates to true.
If you omit ConditionalOperator , then AND is the default.
The operation will succeed only if the entire map evaluates to true.
Note: This parameter does not support attributes of type List or Map.
• ReturnValues (string) – Use ReturnValues if you want to get the item
attributes as they appeared either before or after they were updated. For
UpdateItem , the valid values are:
– NONE - If ReturnValues is not specified, or if its value is NONE , then
nothing is returned. (This setting is the default for ReturnValues .)
– ALL_OLD - If UpdateItem overwrote an attribute name-value pair,
then the content of the old item is returned.
– UPDATED_OLD - The old versions of only the updated attributes
are returned.
– ALL_NEW - All of the attributes of the new version of the item are
returned.
– UPDATED_NEW - The new versions of only the updated attributes
are returned.
• ReturnConsumedCapacity (string) – Determines the level of detail about
provisioned throughput consumption that is returned in the response:
– INDEXES - The response includes the aggregate ConsumedCapac-
ity for the operation, together with ConsumedCapacity for each table
and secondary index that was accessed. Note that some operations,
such as GetItem and BatchGetItem , do not access any indexes at all.
In these cases, specifying INDEXES will only return ConsumedCa-
pacity information for table(s).
– TOTAL - The response includes only the aggregate ConsumedCa-
pacity for the operation.
– NONE - No ConsumedCapacity details are included in the response.
• ReturnItemCollectionMetrics (string) – Determines whether item col-
lection metrics are returned. If set to SIZE , the response includes statis-
tics about item collections, if any, that were modified during the operation
are returned in the response. If set to NONE (the default), no statistics are
returned.
• UpdateExpression (string) – An expression that defines one or more
attributes to be updated, the action to be performed on them, and new
value(s) for them.
The following action values are available for UpdateExpression .
– SET - Adds one or more attributes and values to an item. If any
of these attribute already exist, they are replaced by the new val-
ues. You can also use SET to add or subtract from an attribute
that is of type Number. For example: SET myNum = myNum +
:val SET supports the following functions: * if_not_exists
(path, operand) - if the item does not contain an attribute at
the specified path, then if_not_exists evaluates to operand;
otherwise, it evaluates to path. You can use this function to avoid
overwriting an attribute that may already be present in the item.
– list_append (operand, operand) - evaluates to a list
with a new element added to it. You can append the new element to
the start or the end of the list by reversing the order of the operands.
These function names are case-sensitive.
1082 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– REMOVE - Removes one or more attributes from an item.
– ADD - Adds the specified value to the item, if the attribute does not
already exist. If the attribute does exist, then the behavior of ADD de-
pends on the data type of the attribute: * If the existing attribute is a
number, and if Value is also a number, then Value is mathematically
added to the existing attribute. If Value is a negative number, then
it is subtracted from the existing attribute. .. note:: If you use ADD
to increment or decrement a number value for an item that doesn’t
exist before the update, DynamoDB uses 0 as the initial value. Sim-
ilarly, if you use ADD for an existing item to increment or decrement
an attribute value that doesn’t exist before the update, DynamoDB
uses 0 as the initial value. For example, suppose that the item you
want to update doesn’t have an attribute named itemcount , but you
decide to ADD the number 3 to this attribute anyway. DynamoDB
will create the itemcount attribute, set its initial value to 0 , and fi-
nally add 3 to it. The result will be a new itemcount attribute in the
item, with a value of 3 .
– If the existing data type is a set and if Value is also a set, then Value
is added to the existing set. For example, if the attribute value is
the set [1,2] , and the ADD action specified [3] , then the final
attribute value is [1,2,3] . An error occurs if an ADD action is
specified for a set attribute and the attribute type specified does not
match the existing set type. Both sets must have the same primitive
data type. For example, if the existing data type is a set of strings,
the Value must also be a set of strings.
Warning: The ADD action only supports Number and set data types.
In addition, ADD can only be used on top-level attributes, not nested
attributes.
– DELETE - Deletes an element from a set. If a set of values is speci-
fied, then those values are subtracted from the old set. For example,
if the attribute value was the set [a,b,c] and the DELETE action
specifies [a,c] , then the final attribute value is [b] . Specify-
ing an empty set is an error. .. warning::The DELETE action only
supports set data types. In addition, DELETE can only be used on
top-level attributes, not nested attributes.
You can have many actions in a single expression, such as the
following: SET a=:value1, b=:value2 DELETE :value3,
:value4, :value5
For more information on update expressions, see Modifying Items and
Attributes in the Amazon DynamoDB Developer Guide .
Note: UpdateExpression replaces the legacy AttributeUpdates parameter.
• ConditionExpression (condition from
boto3.dynamodb.conditions.Attr method) – The condi-
tion(s) an attribute(s) must meet. Valid conditions are listed in the
DynamoDB Reference Guide.
• ExpressionAttributeNames (dict) – One or more substitution tokens for
attribute names in an expression. The following are some use cases for
using ExpressionAttributeNames :
– To access an attribute whose name conflicts with a DynamoDB re-
served word.
– To create a placeholder for repeating occurrences of an attribute
3.1. Services 1083
Boto3 Documentation, Release 1.1.4
name in an expression.
– To prevent special characters in an attribute name from being mis-
interpreted in an expression.
Use the # character in an expression to dereference an attribute name. For
example, consider the following attribute name:
– Percentile
The name of this attribute conflicts with a reserved word, so it cannot be
used directly in an expression. (For the complete list of reserved words,
see Reserved Words in the Amazon DynamoDB Developer Guide ). To
work around this, you could specify the following for ExpressionAttribute-
Names :
– {"#P":"Percentile"}
You could then use this substitution in an expression, as in this example:
– #P = :val
Note: Tokens that begin with the : character are expression attribute
values , which are placeholders for the actual value at runtime.
For more information on expression attribute names, see Accessing Item
Attributes in the Amazon DynamoDB Developer Guide .
– (string) –
* (string) –
• ExpressionAttributeValues (dict) – One or more values that can be sub-
stituted in an expression.
Use the : (colon) character in an expression to dereference an attribute
value. For example, suppose that you wanted to check whether the value
of the ProductStatus attribute was one of the following:
Available | Backordered | Discontinued
You would first need to specify ExpressionAttributeValues as follows:
{ ":avail":{"S":"Available"},
":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }
You could then use these values in an expression, such as this:
ProductStatus IN (:avail, :back, :disc)
For more information on expression attribute values, see Specifying Con-
ditions in the Amazon DynamoDB Developer Guide .
– (string) –
* (valid DynamoDB type) – - The value of the attribute. The
valid value types are listed in the DynamoDB Reference
Guide.
Return type dict
Returns
Response Syntax
{
'Attributes': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|set(
},
'ConsumedCapacity': {
'TableName': 'string',
1084 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'CapacityUnits': 123.0,
'Table': {
'CapacityUnits': 123.0
},
'LocalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
},
'GlobalSecondaryIndexes': {
'string': {
'CapacityUnits': 123.0
}
}
},
'ItemCollectionMetrics': {
'ItemCollectionKey': {
'string': 'string'|123|Binary(b'bytes')|True|None|set(['string'])|
},
'SizeEstimateRangeGB': [
123.0,
]
}
}
Response Structure
• (dict) –
Represents the output of an UpdateItem operation.
– Attributes (dict) –
A map of attribute values as they appeared before the UpdateItem
operation. This map only appears if ReturnValues was specified as
something other than NONE in the request. Each element represents
one attribute.
* (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
– ConsumedCapacity (dict) –
The capacity units consumed by an operation. The data returned
includes the total provisioned throughput consumed, along with
statistics for the table and any indexes involved in the operation.
ConsumedCapacity is only returned if the request asked for it. For
more information, see Provisioned Throughput in the Amazon Dy-
namoDB Developer Guide .
* TableName (string) –
The name of the table that was affected by the operation.
* CapacityUnits (float) –
The total number of capacity units consumed by the opera-
tion.
* Table (dict) –
The amount of throughput consumed on the table affected by
the operation.
· CapacityUnits (float) –
3.1. Services 1085
Boto3 Documentation, Release 1.1.4
The total number of capacity units consumed on a table
or an index.
* LocalSecondaryIndexes (dict) –
The amount of throughput consumed on each local index af-
fected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
* GlobalSecondaryIndexes (dict) –
The amount of throughput consumed on each global index
affected by the operation.
· (string) –
· (dict) –
Represents the amount of provisioned throughput ca-
pacity consumed on a table or an index.
· CapacityUnits (float) –
The total number of capacity units consumed on a table
or an index.
– ItemCollectionMetrics (dict) –
Information about item collections, if any, that were affected by
the operation. ItemCollectionMetrics is only returned if the request
asked for it. If the table does not have any local secondary indexes,
this information is not returned in the response.
* ItemCollectionKey (dict) –
The hash key value of the item collection. This value is the
same as the hash key of the item.
· (string) –
· (valid DynamoDB type) – - The value of the attribute.
The valid value types are listed in the DynamoDB Ref-
erence Guide.
* SizeEstimateRangeGB (list) –
An estimate of item collection size, in gigabytes. This value
is a two-element array containing a lower bound and an upper
bound for the estimate. The estimate includes the size of all
the items in the table, plus the size of all attributes projected
into all of the local secondary indexes on that table. Use this
estimate to measure whether a local secondary index is ap-
proaching its size limit.
The estimate is subject to change over time; therefore, do not
rely on the precision or accuracy of the estimate.
· (float) –
DynamoDBStreams
1086 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Table of Contents
• DynamoDBStreams
– Client
Client
class DynamoDBStreams.Client
A low-level client representing Amazon DynamoDB Streams:
import boto3
client = boto3.client('dynamodbstreams')
These are the available methods:
•can_paginate()
•describe_stream()
•generate_presigned_url()
•get_paginator()
•get_records()
•get_shard_iterator()
•get_waiter()
•list_streams()
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
describe_stream(**kwargs)
Returns information about a stream, including the current status of the stream, its Amazon Resource Name
(ARN), the composition of its shards, and its corresponding DynamoDB table.
Note: You can call DescribeStream at a maximum rate of 10 times per second.
Each shard in the stream has a SequenceNumberRange associated with it. If the
SequenceNumberRange has a StartingSequenceNumber but no EndingSequenceNumber
, then the shard is still open (able to receive more stream records). If both StartingSequenceNumber
and EndingSequenceNumber are present, the that shared is closed and can no longer receive more
data.
Request Syntax
response = client.describe_stream(
StreamArn='string',
Limit=123,
ExclusiveStartShardId='string'
)
Parameters
3.1. Services 1087
Boto3 Documentation, Release 1.1.4
• StreamArn (string) – [REQUIRED]
The Amazon Resource Name (ARN) for the stream.
• Limit (integer) – The maximum number of shard objects to return. The upper
limit is 100.
• ExclusiveStartShardId (string) – The shard ID of the first item that
this operation will evaluate. Use the value that was returned for
LastEvaluatedShardId in the previous operation.
Return type dict
Returns
Response Syntax
{
'StreamDescription': {
'StreamArn': 'string',
'StreamLabel': 'string',
'StreamStatus': 'ENABLING'|'ENABLED'|'DISABLING'|'DISABLED',
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KEYS_ONLY'
'CreationRequestDateTime': datetime(2015, 1, 1),
'TableName': 'string',
'KeySchema': [
{
'AttributeName': 'string',
'KeyType': 'HASH'|'RANGE'
},
],
'Shards': [
{
'ShardId': 'string',
'SequenceNumberRange': {
'StartingSequenceNumber': 'string',
'EndingSequenceNumber': 'string'
},
'ParentShardId': 'string'
},
],
'LastEvaluatedShardId': 'string'
}
}
Response Structure
• (dict) –
Represents the output of a DescribeStream operation.
– StreamDescription (dict) –
A complete description of the stream, including its creation date and time,
the DynamoDB table associated with the stream, the shard IDs within the
stream, and the beginning and ending sequence numbers of stream records
within the shards.
* StreamArn (string) –
The Amazon Resource Name (ARN) for the stream.
* StreamLabel (string) –
A timestamp, in ISO 8601 format, for this stream.
Note that LatestStreamLabel is not a unique identifier for the stream,
because it is possible that a stream from another table might have the
1088 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
same timestamp. However, the combination of the following three
elements is guaranteed to be unique:
· the AWS customer ID.
· the table name
· the StreamLabel
* StreamStatus (string) –
Indicates the current status of the stream:
· ENABLING - Streams is currently being enabled on the Dy-
namoDB table.
· ENABLING - the stream is enabled.
· DISABLING - Streams is currently being disabled on the Dy-
namoDB table.
· DISABLED - the stream is disabled.
* StreamViewType (string) –
Indicates the format of the records within this stream:
· KEYS_ONLY - only the key attributes of items that were mod-
ified in the DynamoDB table.
· NEW_IMAGE - entire item from the table, as it appeared after
they were modified.
· OLD_IMAGE - entire item from the table, as it appeared be-
fore they were modified.
· NEW_AND_OLD_IMAGES - both the new and the old images
of the items from the table.
* CreationRequestDateTime (datetime) –
The date and time when the request to create this stream was issued.
* TableName (string) –
The DynamoDB table with which the stream is associated.
* KeySchema (list) –
The key attribute(s) of the stream’s DynamoDB table.
· (dict) –
Represents a single element of a key schema. A key schema
specifies the attributes that make up the primary key of a table,
or the key attributes of an index.
A KeySchemaElement represents exactly one attribute of the
primary key. For example, a hash type primary key would be
represented by one KeySchemaElement . A hash-and-range
type primary key would require one KeySchemaElement for
the hash attribute, and another KeySchemaElement for the
range attribute.
· AttributeName (string) –
The name of a key attribute.
· KeyType (string) –
The attribute data, consisting of the data type and the attribute
value itself.
* Shards (list) –
The shards that comprise the stream.
· (dict) –
A uniquely identified group of stream records within a stream.
3.1. Services 1089
Boto3 Documentation, Release 1.1.4
· ShardId (string) –
The system-generated identifier for this shard.
· SequenceNumberRange (dict) –
The range of possible sequence numbers for the shard.
· StartingSequenceNumber (string) –
The first sequence number.
· EndingSequenceNumber (string) –
The last sequence number.
· ParentShardId (string) –
The shard ID of the current shard’s parent.
* LastEvaluatedShardId (string) –
The shard ID of the item where the operation stopped, inclusive
of the previous result set. Use this value to start a new operation,
excluding this value in the new request.
If LastEvaluatedShardId is empty, then the “last page” of
results has been processed and there is currently no more data to be
retrieved.
If LastEvaluatedShardId is not empty, it does not necessar-
ily mean that there is more data in the result set. The only way
to know when you have reached the end of the result set is when
LastEvaluatedShardId is empty.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_records(**kwargs)
Retrieves the stream records from a given shard.
Specify a shard iterator using the ShardIterator parameter. The shard iterator specifies the position
in the shard from which you want to start reading stream records sequentially. If there are no stream
records available in the portion of the shard that the iterator points to, GetRecords returns an empty
list. Note that it might take multiple calls to get to a portion of the shard that contains stream records.
1090 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Note: GetRecordscan retrieve a maximum of 1 MB of data or 2000 stream records, whichever comes
first.
Request Syntax
response = client.get_records(
ShardIterator='string',
Limit=123
)
Parameters
• ShardIterator (string) – [REQUIRED]
A shard iterator that was retrieved from a previous GetShardIterator operation.
This iterator can be used to access the stream records in this shard.
• Limit (integer) – The maximum number of records to return from the shard. The
upper limit is 1000.
Return type dict
Returns
Response Syntax
{
'Records': [
{
'eventID': 'string',
'eventName': 'INSERT'|'MODIFY'|'REMOVE',
'eventVersion': 'string',
'eventSource': 'string',
'awsRegion': 'string',
'dynamodb': {
'Keys': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'NewImage': {
'string': {
3.1. Services 1091
Boto3 Documentation, Release 1.1.4
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'OldImage': {
'string': {
'S': 'string',
'N': 'string',
'B': b'bytes',
'SS': [
'string',
],
'NS': [
'string',
],
'BS': [
b'bytes',
],
'M': {
'string': {'... recursive ...'}
},
'L': [
{'... recursive ...'},
],
'NULL': True|False,
'BOOL': True|False
}
},
'SequenceNumber': 'string',
'SizeBytes': 123,
'StreamViewType': 'NEW_IMAGE'|'OLD_IMAGE'|'NEW_AND_OLD_IMAGES'|'KE
}
},
],
'NextShardIterator': 'string'
}
Response Structure
• (dict) –
Represents the output of a GetRecords operation.
1092 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– Records (list) –
The stream records from the shard, which were retrieved using the shard
iterator.
* (dict) –
A description of a unique event within a stream.
· eventID (string) –
A globally unique identifier for the event that was recorded in
this stream record.
· eventName (string) –
The type of data modification that was performed on the Dy-
namoDB table:
· INSERT - a new item was added to the table.
· MODIFY - one or more of the item’s attributes were updated.
· REMOVE - the item was deleted from the table
· eventVersion (string) –
The version number of the stream record format. Currently,
this is 1.0 .
· eventSource (string) –
The AWS service from which the stream record originated.
For DynamoDB Streams, this is aws:dynamodb .
· awsRegion (string) –
The region in which the GetRecords request was received.
· dynamodb (dict) –
The main body of the stream record, containing all of the
DynamoDB-specific fields.
· Keys (dict) –
The primary key attribute(s) for the DynamoDB item that was
modified.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
3.1. Services 1093
Boto3 Documentation, Release 1.1.4
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map data type.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List data type.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· NewImage (dict) –
The item in the DynamoDB table as it appeared after it was
modified.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
1094 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map data type.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List data type.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· OldImage (dict) –
The item in the DynamoDB table as it appeared before it was
modified.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
3.1. Services 1095
Boto3 Documentation, Release 1.1.4
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· S (string) –
A String data type.
· N (string) –
A Number data type.
· B (bytes) –
A Binary data type.
· SS (list) –
A String Set data type.
· (string) –
· NS (list) –
A Number Set data type.
· (string) –
· BS (list) –
A Binary Set data type.
· (bytes) –
· M (dict) –
A Map data type.
· (string) –
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· L (list) –
A List data type.
· (dict) –
Represents the data for an attribute. You can set one, and only
one, of the elements.
Each attribute in an item is a name-value pair. An attribute
can be single-valued or multi-valued set. For example, a book
item can have title and authors attributes. Each book has one
title but can have many authors. The multi-valued attribute is
a set; duplicate values are not allowed.
· NULL (boolean) –
A Null data type.
· BOOL (boolean) –
A Boolean data type.
· SequenceNumber (string) –
The sequence number of the stream record.
1096 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· SizeBytes (integer) –
The size of the stream record, in bytes.
· StreamViewType (string) –
The type of data from the modified DynamoDB item that was
captured in this stream record:
· KEYS_ONLY - only the key attributes of the modified item.
· NEW_IMAGE - the entire item, as it appears after it was mod-
ified.
· OLD_IMAGE - the entire item, as it appeared before it was
modified.
· NEW_AND_OLD_IMAGES — both the new and the old item
images of the item.
– NextShardIterator (string) –
The next position in the shard from which to start sequentially reading
stream records. If set to null , the shard has been closed and the re-
quested iterator will not return any more data.
get_shard_iterator(**kwargs)
Returns a shard iterator. A shard iterator provides information about how to retrieve the stream records
from within a shard. Use the shard iterator in a subsequent GetRecords request to read the stream
records from the shard.
Note: A shard iterator expires 15 minutes after it is returned to the requester.
Request Syntax
response = client.get_shard_iterator(
StreamArn='string',
ShardId='string',
ShardIteratorType='TRIM_HORIZON'|'LATEST'|'AT_SEQUENCE_NUMBER'|'AFTER_SEQUENCE_NUMBER',
SequenceNumber='string'
)
Parameters
• StreamArn (string) – [REQUIRED]
The Amazon Resource Name (ARN) for the stream.
• ShardId (string) – [REQUIRED]
The identifier of the shard. The iterator will be returned for this shard ID.
• ShardIteratorType (string) – [REQUIRED]
Determines how the shard iterator is used to start reading stream records from
the shard:
– AT_SEQUENCE_NUMBER - Start reading exactly from the position de-
noted by a specific sequence number.
– AFTER_SEQUENCE_NUMBER - Start reading right after the position de-
noted by a specific sequence number.
– TRIM_HORIZON - Start reading at the last (untrimmed) stream record,
which is the oldest record in the shard. In DynamoDB Streams, there is
a 24 hour limit on data retention. Stream records whose age exceeds this
limit are subject to removal (trimming) from the stream.
– LATEST - Start reading just after the most recent stream record in the
shard, so that you always read the most recent data in the shard.
3.1. Services 1097
Boto3 Documentation, Release 1.1.4
• SequenceNumber (string) – The sequence number of a stream record in the
shard from which to start reading.
Return type dict
Returns
Response Syntax
{
'ShardIterator': 'string'
}
Response Structure
• (dict) –
Represents the output of a GetShardIterator operation.
– ShardIterator (string) –
The position in the shard from which to start reading stream records se-
quentially. A shard iterator specifies this position using the sequence num-
ber of a stream record in a shard.
get_waiter(waiter_name)
list_streams(**kwargs)
Returns an array of stream ARNs associated with the current account and endpoint. If the TableName
parameter is present, then ListStreams will return only the streams ARNs for that table.
Note: You can call ListStreams at a maximum rate of 5 times per second.
Request Syntax
response = client.list_streams(
TableName='string',
Limit=123,
ExclusiveStartStreamArn='string'
)
Parameters
• TableName (string) – If this parameter is provided, then only the streams asso-
ciated with this table name are returned.
• Limit (integer) – The maximum number of streams to return. The upper limit is
100.
• ExclusiveStartStreamArn (string) – The ARN (Amazon Resource Name) of
the first item that this operation will evaluate. Use the value that was returned
for LastEvaluatedStreamArn in the previous operation.
Return type dict
Returns
Response Syntax
{
'Streams': [
{
'StreamArn': 'string',
'TableName': 'string',
'StreamLabel': 'string'
},
],
1098 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'LastEvaluatedStreamArn': 'string'
}
Response Structure
• (dict) –
Represents the output of a ListStreams operation.
– Streams (list) –
A list of stream descriptors associated with the current account and end-
point.
* (dict) –
Represents all of the data describing a particular stream.
· StreamArn (string) –
The Amazon Resource Name (ARN) for the stream.
· TableName (string) –
The DynamoDB table with which the stream is associated.
· StreamLabel (string) –
A timestamp, in ISO 8601 format, for this stream.
Note that LatestStreamLabel is not a unique identifier for the
stream, because it is possible that a stream from another table
might have the same timestamp. However, the combination
of the following three elements is guaranteed to be unique:
· the AWS customer ID.
· the table name
· the StreamLabel
– LastEvaluatedStreamArn (string) –
The stream ARN of the item where the operation stopped, inclusive of the
previous result set. Use this value to start a new operation, excluding this
value in the new request.
If LastEvaluatedStreamArn is empty, then the “last page” of re-
sults has been processed and there is no more data to be retrieved.
If LastEvaluatedStreamArn is not empty, it does not necessar-
ily mean that there is more data in the result set. The only way
to know when you have reached the end of the result set is when
LastEvaluatedStreamArn is empty.
EC2
3.1. Services 1099
Boto3 Documentation, Release 1.1.4
Table of Contents
• EC2
– Client
– Paginators
– Waiters
– Service Resource
– DhcpOptions
– Image
– Instance
– InternetGateway
– KeyPair
– NetworkAcl
– NetworkInterface
– PlacementGroup
– RouteTable
– RouteTableAssociation
– SecurityGroup
– Snapshot
– Subnet
– Tag
– Volume
– Vpc
– VpcPeeringConnection
Client
class EC2.Client
A low-level client representing Amazon Elastic Compute Cloud (EC2):
import boto3
client = boto3.client('ec2')
These are the available methods:
•accept_vpc_peering_connection()
•allocate_address()
•assign_private_ip_addresses()
•associate_address()
•associate_dhcp_options()
•associate_route_table()
•attach_classic_link_vpc()
•attach_internet_gateway()
•attach_network_interface()
•attach_volume()
•attach_vpn_gateway()
•authorize_security_group_egress()
•authorize_security_group_ingress()
•bundle_instance()
•can_paginate()
•cancel_bundle_task()
•cancel_conversion_task()
•cancel_export_task()
1100 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
•cancel_import_task()
•cancel_reserved_instances_listing()
•cancel_spot_fleet_requests()
•cancel_spot_instance_requests()
•confirm_product_instance()
•copy_image()
•copy_snapshot()
•create_customer_gateway()
•create_dhcp_options()
•create_flow_logs()
•create_image()
•create_instance_export_task()
•create_internet_gateway()
•create_key_pair()
•create_network_acl()
•create_network_acl_entry()
•create_network_interface()
•create_placement_group()
•create_reserved_instances_listing()
•create_route()
•create_route_table()
•create_security_group()
•create_snapshot()
•create_spot_datafeed_subscription()
•create_subnet()
•create_tags()
•create_volume()
•create_vpc()
•create_vpc_endpoint()
•create_vpc_peering_connection()
•create_vpn_connection()
•create_vpn_connection_route()
•create_vpn_gateway()
•delete_customer_gateway()
•delete_dhcp_options()
•delete_flow_logs()
•delete_internet_gateway()
•delete_key_pair()
•delete_network_acl()
•delete_network_acl_entry()
•delete_network_interface()
•delete_placement_group()
•delete_route()
•delete_route_table()
•delete_security_group()
•delete_snapshot()
•delete_spot_datafeed_subscription()
•delete_subnet()
•delete_tags()
•delete_volume()
•delete_vpc()
•delete_vpc_endpoints()
•delete_vpc_peering_connection()
•delete_vpn_connection()
3.1. Services 1101
Boto3 Documentation, Release 1.1.4
•delete_vpn_connection_route()
•delete_vpn_gateway()
•deregister_image()
•describe_account_attributes()
•describe_addresses()
•describe_availability_zones()
•describe_bundle_tasks()
•describe_classic_link_instances()
•describe_conversion_tasks()
•describe_customer_gateways()
•describe_dhcp_options()
•describe_export_tasks()
•describe_flow_logs()
•describe_image_attribute()
•describe_images()
•describe_import_image_tasks()
•describe_import_snapshot_tasks()
•describe_instance_attribute()
•describe_instance_status()
•describe_instances()
•describe_internet_gateways()
•describe_key_pairs()
•describe_moving_addresses()
•describe_network_acls()
•describe_network_interface_attribute()
•describe_network_interfaces()
•describe_placement_groups()
•describe_prefix_lists()
•describe_regions()
•describe_reserved_instances()
•describe_reserved_instances_listings()
•describe_reserved_instances_modifications()
•describe_reserved_instances_offerings()
•describe_route_tables()
•describe_security_groups()
•describe_snapshot_attribute()
•describe_snapshots()
•describe_spot_datafeed_subscription()
•describe_spot_fleet_instances()
•describe_spot_fleet_request_history()
•describe_spot_fleet_requests()
•describe_spot_instance_requests()
•describe_spot_price_history()
•describe_subnets()
•describe_tags()
•describe_volume_attribute()
•describe_volume_status()
•describe_volumes()
•describe_vpc_attribute()
•describe_vpc_classic_link()
•describe_vpc_endpoint_services()
•describe_vpc_endpoints()
•describe_vpc_peering_connections()
•describe_vpcs()
1102 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
•describe_vpn_connections()
•describe_vpn_gateways()
•detach_classic_link_vpc()
•detach_internet_gateway()
•detach_network_interface()
•detach_volume()
•detach_vpn_gateway()
•disable_vgw_route_propagation()
•disable_vpc_classic_link()
•disassociate_address()
•disassociate_route_table()
•enable_vgw_route_propagation()
•enable_volume_io()
•enable_vpc_classic_link()
•generate_presigned_url()
•get_console_output()
•get_paginator()
•get_password_data()
•get_waiter()
•import_image()
•import_instance()
•import_key_pair()
•import_snapshot()
•import_volume()
•modify_image_attribute()
•modify_instance_attribute()
•modify_network_interface_attribute()
•modify_reserved_instances()
•modify_snapshot_attribute()
•modify_subnet_attribute()
•modify_volume_attribute()
•modify_vpc_attribute()
•modify_vpc_endpoint()
•monitor_instances()
•move_address_to_vpc()
•purchase_reserved_instances_offering()
•reboot_instances()
•register_image()
•reject_vpc_peering_connection()
•release_address()
•replace_network_acl_association()
•replace_network_acl_entry()
•replace_route()
•replace_route_table_association()
•report_instance_status()
•request_spot_fleet()
•request_spot_instances()
•reset_image_attribute()
•reset_instance_attribute()
•reset_network_interface_attribute()
•reset_snapshot_attribute()
•restore_address_to_classic()
•revoke_security_group_egress()
•revoke_security_group_ingress()
3.1. Services 1103
Boto3 Documentation, Release 1.1.4
•run_instances()
•start_instances()
•stop_instances()
•terminate_instances()
•unassign_private_ip_addresses()
•unmonitor_instances()
accept_vpc_peering_connection(**kwargs)
Accept a VPC peering connection request. To accept a request, the VPC peering connection must
be in the pending-acceptance state, and you must be the owner of the peer VPC. Use the
DescribeVpcPeeringConnections request to view your outstanding VPC peering connection
requests.
Request Syntax
response = client.accept_vpc_peering_connection(
DryRun=True|False,
VpcPeeringConnectionId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcPeeringConnectionId (string) – The ID of the VPC peering connection.
Return type dict
Returns
Response Syntax
{
'VpcPeeringConnection': {
'AccepterVpcInfo': {
'CidrBlock': 'string',
'OwnerId': 'string',
'VpcId': 'string'
},
'ExpirationTime': datetime(2015, 1, 1),
'RequesterVpcInfo': {
'CidrBlock': 'string',
'OwnerId': 'string',
'VpcId': 'string'
},
'Status': {
'Code': 'initiating-request'|'pending-acceptance'|'active'|'deleted'|'
'Message': 'string'
},
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VpcPeeringConnectionId': 'string'
}
}
Response Structure
1104 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• (dict) –
– VpcPeeringConnection (dict) –
Information about the VPC peering connection.
* AccepterVpcInfo (dict) –
The information of the peer VPC.
· CidrBlock (string) –
The CIDR block for the VPC.
· OwnerId (string) –
The AWS account ID of the VPC owner.
· VpcId (string) –
The ID of the VPC.
* ExpirationTime (datetime) –
The time that an unaccepted VPC peering connection will expire.
* RequesterVpcInfo (dict) –
The information of the requester VPC.
· CidrBlock (string) –
The CIDR block for the VPC.
· OwnerId (string) –
The AWS account ID of the VPC owner.
· VpcId (string) –
The ID of the VPC.
* Status (dict) –
The status of the VPC peering connection.
· Code (string) –
The status of the VPC peering connection.
· Message (string) –
A message that provides more information about the status, if
applicable.
* Tags (list) –
Any tags assigned to the resource.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
* VpcPeeringConnectionId (string) –
The ID of the VPC peering connection.
3.1. Services 1105
Boto3 Documentation, Release 1.1.4
allocate_address(**kwargs)
Acquires an Elastic IP address.
An Elastic IP address is for use either in the EC2-Classic platform or in a VPC. For more information, see
Elastic IP Addresses in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.allocate_address(
DryRun=True|False,
Domain='vpc'|'standard'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Domain (string) – Set to vpc to allocate the address for use with instances in a
VPC.
Default: The address is for use with instances in EC2-Classic.
Return type dict
Returns
Response Syntax
{
'PublicIp': 'string',
'Domain': 'vpc'|'standard',
'AllocationId': 'string'
}
Response Structure
• (dict) –
– PublicIp (string) –
The Elastic IP address.
– Domain (string) –
Indicates whether this Elastic IP address is for use with instances in EC2-
Classic (standard ) or instances in a VPC (vpc ).
– AllocationId (string) –
[EC2-VPC] The ID that AWS assigns to represent the allocation of the
Elastic IP address for use with instances in a VPC.
assign_private_ip_addresses(**kwargs)
Assigns one or more secondary private IP addresses to the specified network interface. You can specify
one or more specific secondary IP addresses, or you can specify the number of secondary IP addresses to
be automatically assigned within the subnet’s CIDR block range. The number of secondary IP addresses
that you can assign to an instance varies by instance type. For information about instance types, see
Instance Types in the Amazon Elastic Compute Cloud User Guide . For more information about Elastic
IP addresses, see Elastic IP Addresses in the Amazon Elastic Compute Cloud User Guide .
AssignPrivateIpAddresses is available only in EC2-VPC.
Request Syntax
1106 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.assign_private_ip_addresses(
NetworkInterfaceId='string',
PrivateIpAddresses=[
'string',
],
SecondaryPrivateIpAddressCount=123,
AllowReassignment=True|False
)
Parameters
• NetworkInterfaceId (string) – [REQUIRED]
The ID of the network interface.
• PrivateIpAddresses (list) – One or more IP addresses to be assigned as a sec-
ondary private IP address to the network interface. You can’t specify this param-
eter when also specifying a number of secondary IP addresses.
If you don’t specify an IP address, Amazon EC2 automatically selects an IP
address within the subnet range.
– (string) –
• SecondaryPrivateIpAddressCount (integer) – The number of secondary IP ad-
dresses to assign to the network interface. You can’t specify this parameter when
also specifying private IP addresses.
• AllowReassignment (boolean) – Indicates whether to allow an IP address that
is already assigned to another network interface or instance to be reassigned to
the specified network interface.
Returns None
associate_address(**kwargs)
Associates an Elastic IP address with an instance or a network interface.
An Elastic IP address is for use in either the EC2-Classic platform or in a VPC. For more information, see
Elastic IP Addresses in the Amazon Elastic Compute Cloud User Guide .
[EC2-Classic, VPC in an EC2-VPC-only account] If the Elastic IP address is already associated with a
different instance, it is disassociated from that instance and associated with the specified instance.
[VPC in an EC2-Classic account] If you don’t specify a private IP address, the Elastic IP address is
associated with the primary IP address. If the Elastic IP address is already associated with a different
instance or a network interface, you get an error unless you allow reassociation.
This is an idempotent operation. If you perform the operation more than once, Amazon EC2 doesn’t
return an error.
Request Syntax
response = client.associate_address(
DryRun=True|False,
InstanceId='string',
PublicIp='string',
AllocationId='string',
NetworkInterfaceId='string',
PrivateIpAddress='string',
AllowReassociation=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
3.1. Services 1107
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – The ID of the instance. This is required for EC2-Classic.
For EC2-VPC, you can specify either the instance ID or the network interface
ID, but not both. The operation fails if you specify an instance ID unless exactly
one network interface is attached.
• PublicIp (string) – The Elastic IP address. This is required for EC2-Classic.
• AllocationId (string) – [EC2-VPC] The allocation ID. This is required for EC2-
VPC.
• NetworkInterfaceId (string) – [EC2-VPC] The ID of the network interface. If
the instance has more than one network interface, you must specify a network
interface ID.
• PrivateIpAddress (string) – [EC2-VPC] The primary or secondary private IP
address to associate with the Elastic IP address. If no private IP address is spec-
ified, the Elastic IP address is associated with the primary private IP address.
• AllowReassociation (boolean) – [EC2-VPC] Allows an Elastic IP address that
is already associated with an instance or network interface to be re-associated
with the specified instance or network interface. Otherwise, the operation fails.
Default: false
Return type dict
Returns
Response Syntax
{
'AssociationId': 'string'
}
Response Structure
• (dict) –
– AssociationId (string) –
[EC2-VPC] The ID that represents the association of the Elastic IP address
with an instance.
associate_dhcp_options(**kwargs)
Associates a set of DHCP options (that you’ve previously created) with the specified VPC, or associates
no DHCP options with the VPC.
After you associate the options with the VPC, any existing instances and all new instances that you launch
in that VPC use the options. You don’t need to restart or relaunch the instances. They automatically pick
up the changes within a few hours, depending on how frequently the instance renews its DHCP lease. You
can explicitly renew the lease using the operating system on the instance.
For more information, see DHCP Options Sets in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.associate_dhcp_options(
DryRun=True|False,
DhcpOptionsId='string',
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
1108 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• DhcpOptionsId (string) – [REQUIRED]
The ID of the DHCP options set, or default to associate no DHCP options
with the VPC.
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Returns None
associate_route_table(**kwargs)
Associates a subnet with a route table. The subnet and route table must be in the same VPC. This associ-
ation causes traffic originating from the subnet to be routed according to the routes in the route table. The
action returns an association ID, which you need in order to disassociate the route table from the subnet
later. A route table can be associated with multiple subnets.
For more information about route tables, see Route Tables in the Amazon Virtual Private Cloud User
Guide .
Request Syntax
response = client.associate_route_table(
DryRun=True|False,
SubnetId='string',
RouteTableId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SubnetId (string) – [REQUIRED]
The ID of the subnet.
• RouteTableId (string) – [REQUIRED]
The ID of the route table.
Return type dict
Returns
Response Syntax
{
'AssociationId': 'string'
}
Response Structure
• (dict) –
– AssociationId (string) –
The route table association ID (needed to disassociate the route table).
attach_classic_link_vpc(**kwargs)
Links an EC2-Classic instance to a ClassicLink-enabled VPC through one or more of the VPC’s security
groups. You cannot link an EC2-Classic instance to more than one VPC at a time. You can only link
an instance that’s in the running state. An instance is automatically unlinked from a VPC when it’s
stopped - you can link it to the VPC again when you restart it.
3.1. Services 1109
Boto3 Documentation, Release 1.1.4
After you’ve linked an instance, you cannot change the VPC security groups that are associated with it.
To change the security groups, you must first unlink the instance, and then link it again.
Linking your instance to a VPC is sometimes referred to as attaching your instance.
Request Syntax
response = client.attach_classic_link_vpc(
DryRun=True|False,
InstanceId='string',
VpcId='string',
Groups=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of an EC2-Classic instance to link to the ClassicLink-enabled VPC.
• VpcId (string) – [REQUIRED]
The ID of a ClassicLink-enabled VPC.
• Groups (list) – [REQUIRED]
The ID of one or more of the VPC’s security groups. You cannot specify security
groups from a different VPC.
– (string) –
Return type dict
Returns
Response Syntax
{
'Return': True|False
}
Response Structure
• (dict) –
– Return (boolean) –
Returns true if the request succeeds; otherwise, it returns an error.
attach_internet_gateway(**kwargs)
Attaches an Internet gateway to a VPC, enabling connectivity between the Internet and the VPC. For more
information about your VPC and Internet gateway, see the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.attach_internet_gateway(
DryRun=True|False,
InternetGatewayId='string',
VpcId='string'
)
Parameters
1110 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InternetGatewayId (string) – [REQUIRED]
The ID of the Internet gateway.
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Returns None
attach_network_interface(**kwargs)
Attaches a network interface to an instance.
Request Syntax
response = client.attach_network_interface(
DryRun=True|False,
NetworkInterfaceId='string',
InstanceId='string',
DeviceIndex=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkInterfaceId (string) – [REQUIRED]
The ID of the network interface.
• InstanceId (string) – [REQUIRED]
The ID of the instance.
• DeviceIndex (integer) – [REQUIRED]
The index of the device for the network interface attachment.
Return type dict
Returns
Response Syntax
{
'AttachmentId': 'string'
}
Response Structure
• (dict) –
– AttachmentId (string) –
The ID of the network interface attachment.
attach_volume(**kwargs)
Attaches an EBS volume to a running or stopped instance and exposes it to the instance with the specified
device name.
Encrypted EBS volumes may only be attached to instances that support Amazon EBS encryption. For
more information, see Amazon EBS Encryption in the Amazon Elastic Compute Cloud User Guide .
3.1. Services 1111
Boto3 Documentation, Release 1.1.4
For a list of supported device names, see Attaching an EBS Volume to an Instance . Any device names
that aren’t reserved for instance store volumes can be used for EBS volumes. For more information, see
Amazon EC2 Instance Store in the Amazon Elastic Compute Cloud User Guide .
If a volume has an AWS Marketplace product code:
•The volume can be attached only to a stopped instance.
•AWS Marketplace product codes are copied from the volume to the instance.
•You must be subscribed to the product.
•The instance type and operating system of the instance must support the product. For example, you
can’t detach a volume from a Windows instance and attach it to a Linux instance.
For an overview of the AWS Marketplace, see Introducing AWS Marketplace .
For more information about EBS volumes, see Attaching Amazon EBS Volumes in the Amazon Elastic
Compute Cloud User Guide .
Request Syntax
response = client.attach_volume(
DryRun=True|False,
VolumeId='string',
InstanceId='string',
Device='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeId (string) – [REQUIRED]
The ID of the EBS volume. The volume and instance must be within the same
Availability Zone.
• InstanceId (string) – [REQUIRED]
The ID of the instance.
• Device (string) – [REQUIRED]
The device name to expose to the instance (for example, /dev/sdh or xvdh ).
Return type dict
Returns
Response Syntax
{
'VolumeId': 'string',
'InstanceId': 'string',
'Device': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
}
Response Structure
• (dict) –
Information about the volume attachment.
– VolumeId (string) –
The ID of the volume.
1112 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– InstanceId (string) –
The ID of the instance.
– Device (string) –
The device name.
– State (string) –
The attachment state of the volume.
– AttachTime (datetime) –
The time stamp when the attachment initiated.
– DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance termination.
attach_vpn_gateway(**kwargs)
Attaches a virtual private gateway to a VPC. For more information, see Adding a Hardware Virtual Private
Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.attach_vpn_gateway(
DryRun=True|False,
VpnGatewayId='string',
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpnGatewayId (string) – [REQUIRED]
The ID of the virtual private gateway.
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Return type dict
Returns
Response Syntax
{
'VpcAttachment': {
'VpcId': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached'
}
}
Response Structure
• (dict) –
– VpcAttachment (dict) –
Information about the attachment.
* VpcId (string) –
The ID of the VPC.
3.1. Services 1113
Boto3 Documentation, Release 1.1.4
* State (string) –
The current state of the attachment.
authorize_security_group_egress(**kwargs)
Adds one or more egress rules to a security group for use with a VPC. Specifically, this action permits
instances to send traffic to one or more destination CIDR IP address ranges, or to one or more destination
security groups for the same VPC.
Warning: You can have up to 50 rules per security group (covering both ingress and egress rules).
A security group is for use with instances either in the EC2-Classic platform or in a specific VPC. This
action doesn’t apply to security groups for use in EC2-Classic. For more information, see Security Groups
for Your VPC in the Amazon Virtual Private Cloud User Guide .
Each rule consists of the protocol (for example, TCP), plus either a CIDR range or a source group. For the
TCP and UDP protocols, you must also specify the destination port or port range. For the ICMP protocol,
you must also specify the ICMP type and code. You can use -1 for the type or code to mean all types or
all codes.
Rule changes are propagated to affected instances as quickly as possible. However, a small delay might
occur.
Request Syntax
response = client.authorize_security_group_egress(
DryRun=True|False,
GroupId='string',
SourceSecurityGroupName='string',
SourceSecurityGroupOwnerId='string',
IpProtocol='string',
FromPort=123,
ToPort=123,
CidrIp='string',
IpPermissions=[
{
'IpProtocol': 'string',
'FromPort': 123,
'ToPort': 123,
'UserIdGroupPairs': [
{
'UserId': 'string',
'GroupName': 'string',
'GroupId': 'string'
},
],
'IpRanges': [
{
'CidrIp': 'string'
},
],
'PrefixListIds': [
{
'PrefixListId': 'string'
},
]
},
1114 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupId (string) – [REQUIRED]
The ID of the security group.
• SourceSecurityGroupName (string) – The name of a destination security
group. To authorize outbound access to a destination security group, we rec-
ommend that you use a set of IP permissions instead.
• SourceSecurityGroupOwnerId (string) – The AWS account number for a des-
tination security group. To authorize outbound access to a destination security
group, we recommend that you use a set of IP permissions instead.
• IpProtocol (string) – The IP protocol name (tcp , udp , icmp ) or number (see
Protocol Numbers ). Use -1 to specify all.
• FromPort (integer) – The start of port range for the TCP and UDP protocols, or
an ICMP type number. For the ICMP type number, use -1 to specify all ICMP
types.
• ToPort (integer) – The end of port range for the TCP and UDP protocols, or an
ICMP code number. For the ICMP code number, use -1 to specify all ICMP
codes for the ICMP type.
• CidrIp (string) – The CIDR IP address range. You can’t specify this parameter
when specifying a source security group.
• IpPermissions (list) – A set of IP permissions. You can’t specify a destination
security group and a CIDR IP address range.
– (dict) –
Describes a security group rule.
* IpProtocol (string) –
The protocol.
When you call DescribeSecurityGroups , the protocol value returned
is the number. Exception: For TCP, UDP, and ICMP, the value re-
turned is the name (for example, tcp , udp , or icmp ). For a list
of protocol numbers, see Protocol Numbers . (VPC only) When you
call AuthorizeSecurityGroupIngress , you can use -1 to specify all.
* FromPort (integer) –
The start of port range for the TCP and UDP protocols, or an ICMP
type number. A value of -1 indicates all ICMP types.
* ToPort (integer) –
The end of port range for the TCP and UDP protocols, or an ICMP
code. A value of -1 indicates all ICMP codes for the specified
ICMP type.
* UserIdGroupPairs (list) –
One or more security group and AWS account ID pairs.
· (dict) –
Describes a security group and AWS account ID pair.
· UserId (string) –
3.1. Services 1115
Boto3 Documentation, Release 1.1.4
The ID of an AWS account. EC2-Classic only.
· GroupName (string) –
The name of the security group. In a request, use this parame-
ter for a security group in EC2-Classic or a default VPC only.
For a security group in a nondefault VPC, use GroupId .
· GroupId (string) –
The ID of the security group.
* IpRanges (list) –
One or more IP ranges.
· (dict) –
Describes an IP range.
· CidrIp (string) –
The CIDR range. You can either specify a CIDR range or a
source security group, not both.
* PrefixListIds (list) –
(Valid for AuthorizeSecurityGroupEgress , RevokeSecurity-
GroupEgress and DescribeSecurityGroups only) One or more
prefix list IDs for an AWS service. In an AuthorizeSecurity-
GroupEgress request, this is the AWS service that you want to
access through a VPC endpoint from instances associated with the
security group.
· (dict) –
The ID of the prefix.
· PrefixListId (string) –
The ID of the prefix.
Returns None
authorize_security_group_ingress(**kwargs)
Adds one or more ingress rules to a security group.
Warning: EC2-Classic: You can have up to 100 rules per group.
EC2-VPC: You can have up to 50 rules per group (covering both ingress and egress rules).
Rule changes are propagated to instances within the security group as quickly as possible. However, a
small delay might occur.
[EC2-Classic] This action gives one or more CIDR IP address ranges permission to access a security
group in your account, or gives one or more security groups (called the source groups ) permission to
access a security group for your account. A source group can be for your own AWS account, or another.
[EC2-VPC] This action gives one or more CIDR IP address ranges permission to access a security group
in your VPC, or gives one or more other security groups (called the source groups ) permission to access
a security group for your VPC. The security groups must all be for the same VPC.
Request Syntax
response = client.authorize_security_group_ingress(
DryRun=True|False,
GroupName='string',
GroupId='string',
SourceSecurityGroupName='string',
SourceSecurityGroupOwnerId='string',
1116 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
IpProtocol='string',
FromPort=123,
ToPort=123,
CidrIp='string',
IpPermissions=[
{
'IpProtocol': 'string',
'FromPort': 123,
'ToPort': 123,
'UserIdGroupPairs': [
{
'UserId': 'string',
'GroupName': 'string',
'GroupId': 'string'
},
],
'IpRanges': [
{
'CidrIp': 'string'
},
],
'PrefixListIds': [
{
'PrefixListId': 'string'
},
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupName (string) – [EC2-Classic, default VPC] The name of the security
group.
• GroupId (string) – The ID of the security group. Required for a nondefault
VPC.
• SourceSecurityGroupName (string) – [EC2-Classic, default VPC] The name
of the source security group. You can’t specify this parameter in combination
with the following parameters: the CIDR IP address range, the start of the port
range, the IP protocol, and the end of the port range. For EC2-VPC, the source
security group must be in the same VPC.
• SourceSecurityGroupOwnerId (string) – [EC2-Classic, default VPC] The
AWS account number for the source security group. For EC2-VPC, the source
security group must be in the same VPC. You can’t specify this parameter in
combination with the following parameters: the CIDR IP address range, the IP
protocol, the start of the port range, and the end of the port range. Creates rules
that grant full ICMP, UDP, and TCP access. To create a rule with a specific IP
protocol and port range, use a set of IP permissions instead.
• IpProtocol (string) – The IP protocol name (tcp , udp , icmp ) or number (see
Protocol Numbers ). (VPC only) Use -1 to specify all.
• FromPort (integer) – The start of port range for the TCP and UDP protocols, or
an ICMP type number. For the ICMP type number, use -1 to specify all ICMP
types.
3.1. Services 1117
Boto3 Documentation, Release 1.1.4
• ToPort (integer) – The end of port range for the TCP and UDP protocols, or an
ICMP code number. For the ICMP code number, use -1 to specify all ICMP
codes for the ICMP type.
• CidrIp (string) – The CIDR IP address range. You can’t specify this parameter
when specifying a source security group.
• IpPermissions (list) – A set of IP permissions. Can be used to specify multiple
rules in a single command.
– (dict) –
Describes a security group rule.
* IpProtocol (string) –
The protocol.
When you call DescribeSecurityGroups , the protocol value returned
is the number. Exception: For TCP, UDP, and ICMP, the value re-
turned is the name (for example, tcp , udp , or icmp ). For a list
of protocol numbers, see Protocol Numbers . (VPC only) When you
call AuthorizeSecurityGroupIngress , you can use -1 to specify all.
* FromPort (integer) –
The start of port range for the TCP and UDP protocols, or an ICMP
type number. A value of -1 indicates all ICMP types.
* ToPort (integer) –
The end of port range for the TCP and UDP protocols, or an ICMP
code. A value of -1 indicates all ICMP codes for the specified
ICMP type.
* UserIdGroupPairs (list) –
One or more security group and AWS account ID pairs.
· (dict) –
Describes a security group and AWS account ID pair.
· UserId (string) –
The ID of an AWS account. EC2-Classic only.
· GroupName (string) –
The name of the security group. In a request, use this parame-
ter for a security group in EC2-Classic or a default VPC only.
For a security group in a nondefault VPC, use GroupId .
· GroupId (string) –
The ID of the security group.
* IpRanges (list) –
One or more IP ranges.
· (dict) –
Describes an IP range.
· CidrIp (string) –
The CIDR range. You can either specify a CIDR range or a
source security group, not both.
* PrefixListIds (list) –
(Valid for AuthorizeSecurityGroupEgress , RevokeSecurity-
GroupEgress and DescribeSecurityGroups only) One or more
prefix list IDs for an AWS service. In an AuthorizeSecurity-
GroupEgress request, this is the AWS service that you want to
1118 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
access through a VPC endpoint from instances associated with the
security group.
· (dict) –
The ID of the prefix.
· PrefixListId (string) –
The ID of the prefix.
Returns None
bundle_instance(**kwargs)
Bundles an Amazon instance store-backed Windows instance.
During bundling, only the root device volume (C:) is bundled. Data on other instance store volumes is not
preserved.
Note: This action is not applicable for Linux/Unix instances or Windows instances that are backed by
Amazon EBS.
For more information, see Creating an Instance Store-Backed Windows AMI .
Request Syntax
response = client.bundle_instance(
DryRun=True|False,
InstanceId='string',
Storage={
'S3': {
'Bucket': 'string',
'Prefix': 'string',
'AWSAccessKeyId': 'string',
'UploadPolicy': b'bytes',
'UploadPolicySignature': 'string'
}
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the instance to bundle.
Type: String
Default: None
Required: Yes
• Storage (dict) – [REQUIRED]
The bucket in which to store the AMI. You can specify a bucket that you already
own or a new bucket that Amazon EC2 creates on your behalf. If you specify a
bucket that belongs to someone else, Amazon EC2 returns an error.
– S3 (dict) –
An Amazon S3 storage location.
3.1. Services 1119
Boto3 Documentation, Release 1.1.4
* Bucket (string) –
The bucket in which to store the AMI. You can specify a bucket
that you already own or a new bucket that Amazon EC2 creates on
your behalf. If you specify a bucket that belongs to someone else,
Amazon EC2 returns an error.
* Prefix (string) –
The beginning of the file name of the AMI.
* AWSAccessKeyId (string) –
The access key ID of the owner of the bucket. Before you specify
a value for your access key ID, review and follow the guidance in
Best Practices for Managing AWS Access Keys .
* UploadPolicy (bytes) –
A Base64-encoded Amazon S3 upload policy that gives Amazon
EC2 permission to upload items into Amazon S3 on your behalf.
* UploadPolicySignature (string) –
The signature of the Base64 encoded JSON document.
Return type dict
Returns
Response Syntax
{
'BundleTask': {
'InstanceId': 'string',
'BundleId': 'string',
'State': 'pending'|'waiting-for-shutdown'|'bundling'|'storing'|'cancelling
'StartTime': datetime(2015, 1, 1),
'UpdateTime': datetime(2015, 1, 1),
'Storage': {
'S3': {
'Bucket': 'string',
'Prefix': 'string',
'AWSAccessKeyId': 'string',
'UploadPolicy': b'bytes',
'UploadPolicySignature': 'string'
}
},
'Progress': 'string',
'BundleTaskError': {
'Code': 'string',
'Message': 'string'
}
}
}
Response Structure
• (dict) –
– BundleTask (dict) –
Information about the bundle task.
* InstanceId (string) –
The ID of the instance associated with this bundle task.
* BundleId (string) –
1120 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The ID of the bundle task.
* State (string) –
The state of the task.
* StartTime (datetime) –
The time this task started.
* UpdateTime (datetime) –
The time of the most recent update for the task.
* Storage (dict) –
The Amazon S3 storage locations.
· S3 (dict) –
An Amazon S3 storage location.
· Bucket (string) –
The bucket in which to store the AMI. You can specify a
bucket that you already own or a new bucket that Amazon
EC2 creates on your behalf. If you specify a bucket that be-
longs to someone else, Amazon EC2 returns an error.
· Prefix (string) –
The beginning of the file name of the AMI.
· AWSAccessKeyId (string) –
The access key ID of the owner of the bucket. Before you
specify a value for your access key ID, review and follow the
guidance in Best Practices for Managing AWS Access Keys .
· UploadPolicy (bytes) –
A Base64-encoded Amazon S3 upload policy that gives Ama-
zon EC2 permission to upload items into Amazon S3 on your
behalf.
· UploadPolicySignature (string) –
The signature of the Base64 encoded JSON document.
* Progress (string) –
The level of task completion, as a percent (for example, 20%).
* BundleTaskError (dict) –
If the task fails, a description of the error.
· Code (string) –
The error code.
· Message (string) –
The error message.
can_paginate(operation_name)
Check if an operation can be paginated.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Returns True if the operation can be paginated, False otherwise.
cancel_bundle_task(**kwargs)
Cancels a bundling operation for an instance store-backed Windows instance.
3.1. Services 1121
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.cancel_bundle_task(
DryRun=True|False,
BundleId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• BundleId (string) – [REQUIRED]
The ID of the bundle task.
Return type dict
Returns
Response Syntax
{
'BundleTask': {
'InstanceId': 'string',
'BundleId': 'string',
'State': 'pending'|'waiting-for-shutdown'|'bundling'|'storing'|'cancelling
'StartTime': datetime(2015, 1, 1),
'UpdateTime': datetime(2015, 1, 1),
'Storage': {
'S3': {
'Bucket': 'string',
'Prefix': 'string',
'AWSAccessKeyId': 'string',
'UploadPolicy': b'bytes',
'UploadPolicySignature': 'string'
}
},
'Progress': 'string',
'BundleTaskError': {
'Code': 'string',
'Message': 'string'
}
}
}
Response Structure
• (dict) –
– BundleTask (dict) –
Information about the bundle task.
* InstanceId (string) –
The ID of the instance associated with this bundle task.
* BundleId (string) –
The ID of the bundle task.
* State (string) –
The state of the task.
1122 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* StartTime (datetime) –
The time this task started.
* UpdateTime (datetime) –
The time of the most recent update for the task.
* Storage (dict) –
The Amazon S3 storage locations.
· S3 (dict) –
An Amazon S3 storage location.
· Bucket (string) –
The bucket in which to store the AMI. You can specify a
bucket that you already own or a new bucket that Amazon
EC2 creates on your behalf. If you specify a bucket that be-
longs to someone else, Amazon EC2 returns an error.
· Prefix (string) –
The beginning of the file name of the AMI.
· AWSAccessKeyId (string) –
The access key ID of the owner of the bucket. Before you
specify a value for your access key ID, review and follow the
guidance in Best Practices for Managing AWS Access Keys .
· UploadPolicy (bytes) –
A Base64-encoded Amazon S3 upload policy that gives Ama-
zon EC2 permission to upload items into Amazon S3 on your
behalf.
· UploadPolicySignature (string) –
The signature of the Base64 encoded JSON document.
* Progress (string) –
The level of task completion, as a percent (for example, 20%).
* BundleTaskError (dict) –
If the task fails, a description of the error.
· Code (string) –
The error code.
· Message (string) –
The error message.
cancel_conversion_task(**kwargs)
Cancels an active conversion task. The task can be the import of an instance or volume. The action
removes all artifacts of the conversion, including a partially uploaded volume or instance. If the conversion
is complete or is in the process of transferring the final disk image, the command fails and returns an
exception.
For more information, see Using the Command Line Tools to Import Your Virtual Machine to Amazon
EC2 in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.cancel_conversion_task(
DryRun=True|False,
ConversionTaskId='string',
3.1. Services 1123
Boto3 Documentation, Release 1.1.4
ReasonMessage='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ConversionTaskId (string) – [REQUIRED]
The ID of the conversion task.
• ReasonMessage (string) – The reason for canceling the conversion task.
Returns None
cancel_export_task(**kwargs)
Cancels an active export task. The request removes all artifacts of the export, including any partially-
created Amazon S3 objects. If the export task is complete or is in the process of transferring the final disk
image, the command fails and returns an error.
Request Syntax
response = client.cancel_export_task(
ExportTaskId='string'
)
Parameters ExportTaskId (string) – [REQUIRED]
The ID of the export task. This is the ID returned by
CreateInstanceExportTask .
Returns None
cancel_import_task(**kwargs)
Cancels an in-process import virtual machine or import snapshot task.
Request Syntax
response = client.cancel_import_task(
DryRun=True|False,
ImportTaskId='string',
CancelReason='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImportTaskId (string) – The ID of the import image or import snapshot task to
be canceled.
• CancelReason (string) – The reason for canceling the task.
Return type dict
Returns
Response Syntax
{
'ImportTaskId': 'string',
'State': 'string',
1124 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'PreviousState': 'string'
}
Response Structure
• (dict) –
– ImportTaskId (string) –
The ID of the task being canceled.
– State (string) –
The current state of the task being canceled.
– PreviousState (string) –
The current state of the task being canceled.
cancel_reserved_instances_listing(**kwargs)
Cancels the specified Reserved Instance listing in the Reserved Instance Marketplace.
For more information, see Reserved Instance Marketplace in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
response = client.cancel_reserved_instances_listing(
ReservedInstancesListingId='string'
)
Parameters ReservedInstancesListingId (string) – [REQUIRED]
The ID of the Reserved Instance listing.
Return type dict
Returns
Response Syntax
{
'ReservedInstancesListings': [
{
'ReservedInstancesListingId': 'string',
'ReservedInstancesId': 'string',
'CreateDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'Status': 'active'|'pending'|'cancelled'|'closed',
'StatusMessage': 'string',
'InstanceCounts': [
{
'State': 'available'|'sold'|'cancelled'|'pending',
'InstanceCount': 123
},
],
'PriceSchedules': [
{
'Term': 123,
'Price': 123.0,
'CurrencyCode': 'USD',
'Active': True|False
},
],
'Tags': [
{
3.1. Services 1125
Boto3 Documentation, Release 1.1.4
'Key': 'string',
'Value': 'string'
},
],
'ClientToken': 'string'
},
]
}
Response Structure
• (dict) –
– ReservedInstancesListings (list) –
The Reserved Instance listing.
* (dict) –
Describes a Reserved Instance listing.
· ReservedInstancesListingId (string) –
The ID of the Reserved Instance listing.
· ReservedInstancesId (string) –
The ID of the Reserved Instance.
· CreateDate (datetime) –
The time the listing was created.
· UpdateDate (datetime) –
The last modified timestamp of the listing.
· Status (string) –
The status of the Reserved Instance listing.
· StatusMessage (string) –
The reason for the current status of the Reserved Instance list-
ing. The response can be blank.
· InstanceCounts (list) –
The number of instances in this state.
· (dict) –
Describes a Reserved Instance listing state.
· State (string) –
The states of the listed Reserved Instances.
· InstanceCount (integer) –
The number of listed Reserved Instances in the state specified
by the state .
· PriceSchedules (list) –
The price of the Reserved Instance listing.
· (dict) –
Describes the price for a Reserved Instance.
· Term (integer) –
The number of months remaining in the reservation. For ex-
ample, 2 is the second to the last month before the capacity
reservation expires.
· Price (float) –
1126 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The fixed price for the term.
· CurrencyCode (string) –
The currency for transacting the Reserved Instance resale. At
this time, the only supported currency is USD .
· Active (boolean) –
The current price schedule, as determined by the term remain-
ing for the Reserved Instance in the listing.
A specific price schedule is always in effect, but only one
price schedule can be active at any time. Take, for exam-
ple, a Reserved Instance listing that has five months remain-
ing in its term. When you specify price schedules for five
months and two months, this means that schedule 1, covering
the first three months of the remaining term, will be active
during months 5, 4, and 3. Then schedule 2, covering the last
two months of the term, will be active for months 2 and 1.
· Tags (list) –
Any tags assigned to the resource.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· ClientToken (string) –
A unique, case-sensitive key supplied by the client to ensure
that the request is idempotent. For more information, see En-
suring Idempotency .
cancel_spot_fleet_requests(**kwargs)
Cancels the specified Spot fleet requests.
Request Syntax
response = client.cancel_spot_fleet_requests(
DryRun=True|False,
SpotFleetRequestIds=[
'string',
],
TerminateInstances=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
3.1. Services 1127
Boto3 Documentation, Release 1.1.4
• SpotFleetRequestIds (list) – [REQUIRED]
The IDs of the Spot fleet requests.
– (string) –
• TerminateInstances (boolean) – [REQUIRED]
Indicates whether to terminate instances for a Spot fleet request if it is canceled
successfully.
Return type dict
Returns
Response Syntax
{
'UnsuccessfulFleetRequests': [
{
'SpotFleetRequestId': 'string',
'Error': {
'Code': 'fleetRequestIdDoesNotExist'|'fleetRequestIdMalformed'|'fl
'Message': 'string'
}
},
],
'SuccessfulFleetRequests': [
{
'SpotFleetRequestId': 'string',
'CurrentSpotFleetRequestState': 'submitted'|'active'|'cancelled'|'fail
'PreviousSpotFleetRequestState': 'submitted'|'active'|'cancelled'|'fai
},
]
}
Response Structure
• (dict) –
Contains the output of CancelSpotFleetRequests.
– UnsuccessfulFleetRequests (list) –
Information about the Spot fleet requests that are not successfully can-
celed.
* (dict) –
Describes a Spot fleet request that was not successfully canceled.
· SpotFleetRequestId (string) –
The ID of the Spot fleet request.
· Error (dict) –
The error.
· Code (string) –
The error code.
· Message (string) –
The description for the error code.
– SuccessfulFleetRequests (list) –
Information about the Spot fleet requests that are successfully canceled.
* (dict) –
Describes a Spot fleet request that was successfully canceled.
1128 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· SpotFleetRequestId (string) –
The ID of the Spot fleet request.
· CurrentSpotFleetRequestState (string) –
The current state of the Spot fleet request.
· PreviousSpotFleetRequestState (string) –
The previous state of the Spot fleet request.
cancel_spot_instance_requests(**kwargs)
Cancels one or more Spot instance requests. Spot instances are instances that Amazon EC2 starts on your
behalf when the bid price that you specify exceeds the current Spot price. Amazon EC2 periodically sets
the Spot price based on available Spot instance capacity and current Spot instance requests. For more
information, see Spot Instance Requests in the Amazon Elastic Compute Cloud User Guide .
Warning: Canceling a Spot instance request does not terminate running Spot instances associated
with the request.
Request Syntax
response = client.cancel_spot_instance_requests(
DryRun=True|False,
SpotInstanceRequestIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SpotInstanceRequestIds (list) – [REQUIRED]
One or more Spot instance request IDs.
– (string) –
Return type dict
Returns
Response Syntax
{
'CancelledSpotInstanceRequests': [
{
'SpotInstanceRequestId': 'string',
'State': 'active'|'open'|'closed'|'cancelled'|'completed'
},
]
}
Response Structure
• (dict) –
Contains the output of CancelSpotInstanceRequests.
– CancelledSpotInstanceRequests (list) –
One or more Spot instance requests.
3.1. Services 1129
Boto3 Documentation, Release 1.1.4
* (dict) –
Describes a request to cancel a Spot instance.
· SpotInstanceRequestId (string) –
The ID of the Spot instance request.
· State (string) –
The state of the Spot instance request.
confirm_product_instance(**kwargs)
Determines whether a product code is associated with an instance. This action can only be used by the
owner of the product code. It is useful when a product code owner needs to verify whether another user’s
instance is eligible for support.
Request Syntax
response = client.confirm_product_instance(
DryRun=True|False,
ProductCode='string',
InstanceId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ProductCode (string) – [REQUIRED]
The product code. This must be a product code that you own.
• InstanceId (string) – [REQUIRED]
The ID of the instance.
Return type dict
Returns
Response Syntax
{
'OwnerId': 'string',
'Return': True|False
}
Response Structure
• (dict) –
– OwnerId (string) –
The AWS account ID of the instance owner. This is only present if the
product code is attached to the instance.
– Return (boolean) –
The return value of the request. Returns true if the specified product
code is owned by the requester and associated with the specified instance.
copy_image(**kwargs)
Initiates the copy of an AMI from the specified source region to the current region. You specify the
destination region by using its endpoint when making the request. AMIs that use encrypted EBS snapshots
cannot be copied with this method.
For more information, see Copying AMIs in the Amazon Elastic Compute Cloud User Guide .
1130 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.copy_image(
DryRun=True|False,
SourceRegion='string',
SourceImageId='string',
Name='string',
Description='string',
ClientToken='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SourceRegion (string) – [REQUIRED]
The name of the region that contains the AMI to copy.
• SourceImageId (string) – [REQUIRED]
The ID of the AMI to copy.
• Name (string) – [REQUIRED]
The name of the new AMI in the destination region.
• Description (string) – A description for the new AMI in the destination region.
• ClientToken (string) – Unique, case-sensitive identifier you provide to ensure
idempotency of the request. For more information, see How to Ensure Idempo-
tency in the Amazon Elastic Compute Cloud User Guide .
Return type dict
Returns
Response Syntax
{
'ImageId': 'string'
}
Response Structure
• (dict) –
– ImageId (string) –
The ID of the new AMI.
copy_snapshot(**kwargs)
Copies a point-in-time snapshot of an EBS volume and stores it in Amazon S3. You can copy the snapshot
within the same region or from one region to another. You can use the snapshot to create EBS volumes
or Amazon Machine Images (AMIs). The snapshot is copied to the regional endpoint that you send the
HTTP request to.
Copies of encrypted EBS snapshots remain encrypted. Copies of unencrypted snapshots remain unen-
crypted, unless the Encrypted flag is specified during the snapshot copy operation. By default, en-
crypted snapshot copies use the default AWS Key Management Service (AWS KMS) customer master
key (CMK); however, you can specify a non-default CMK with the KmsKeyId parameter.
For more information, see Copying an Amazon EBS Snapshot in the Amazon Elastic Compute Cloud
User Guide .
Request Syntax
3.1. Services 1131
Boto3 Documentation, Release 1.1.4
response = client.copy_snapshot(
DryRun=True|False,
SourceRegion='string',
SourceSnapshotId='string',
Description='string',
Encrypted=True|False,
KmsKeyId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SourceRegion (string) – [REQUIRED]
The ID of the region that contains the snapshot to be copied.
• SourceSnapshotId (string) – [REQUIRED]
The ID of the EBS snapshot to copy.
• Description (string) – A description for the EBS snapshot.
• DestinationRegion (string) – The destination region to use in the
PresignedUrl parameter of a snapshot copy operation. This parameter is
only valid for specifying the destination region in a PresignedUrl parame-
ter, where it is required.
Note: CopySnapshot sends the snapshot copy to the regional endpoint that
you send the HTTP request to, such as ec2.us-east-1.amazonaws.com
(in the AWS CLI, this is specified with the --region parameter or the default
region in your AWS configuration file).
Please note that this parameter is automatically populated if it is not
provided. Including this parameter is not required
• PresignedUrl (string) – The pre-signed URL that facilitates copying an en-
crypted snapshot. This parameter is only required when copying an encrypted
snapshot with the Amazon EC2 Query API; it is available as an optional pa-
rameter in all other cases. The PresignedUrl should use the snapshot
source endpoint, the CopySnapshot action, and include the SourceRegion
, SourceSnapshotId , and DestinationRegion parameters. The
PresignedUrl must be signed using AWS Signature Version 4. Because EBS
snapshots are stored in Amazon S3, the signing algorithm for this parameter uses
the same logic that is described in Authenticating Requests by Using Query Pa-
rameters (AWS Signature Version 4) in the Amazon Simple Storage Service API
Reference . An invalid or improperly signed PresignedUrl will cause the
copy operation to fail asynchronously, and the snapshot will move to an error
state.
Please note that this parameter is automatically populated if it is not
provided. Including this parameter is not required
• Encrypted (boolean) – Specifies whether the destination snapshot should be
encrypted. There is no way to create an unencrypted snapshot copy from an
encrypted snapshot; however, you can encrypt a copy of an unencrypted snapshot
with this flag. The default CMK for EBS is used unless a non-default AWS Key
Management Service (AWS KMS) CMK is specified with KmsKeyId . For
more information, see Amazon EBS Encryption in the Amazon Elastic Compute
Cloud User Guide .
• KmsKeyId (string) – The full ARN of the AWS Key Management Service
1132 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
(AWS KMS) CMK to use when creating the snapshot copy. This parame-
ter is only required if you want to use a non-default CMK; if this parameter
is not specified, the default CMK for EBS is used. The ARN contains the
arn:aws:kms namespace, followed by the region of the CMK, the AWS ac-
count ID of the CMK owner, the key namespace, and then the CMK ID. For ex-
ample, arn:aws:kms:us-east-1 :012345678910 :key/abcd1234-a123-456a-a12b-
a123b4cd56ef . The specified CMK must exist in the region that the snapshot is
being copied to. If a KmsKeyId is specified, the Encrypted flag must also be
set.
Return type dict
Returns
Response Syntax
{
'SnapshotId': 'string'
}
Response Structure
• (dict) –
– SnapshotId (string) –
The ID of the new snapshot.
create_customer_gateway(**kwargs)
Provides information to AWS about your VPN customer gateway device. The customer gateway is the
appliance at your end of the VPN connection. (The device on the AWS side of the VPN connection is
the virtual private gateway.) You must provide the Internet-routable IP address of the customer gateway’s
external interface. The IP address must be static and can’t be behind a device performing network address
translation (NAT).
For devices that use Border Gateway Protocol (BGP), you can also provide the device’s BGP Autonomous
System Number (ASN). You can use an existing ASN assigned to your network. If you don’t have an ASN
already, you can use a private ASN (in the 64512 - 65534 range).
Note: Amazon EC2 supports all 2-byte ASN numbers in the range of 1 - 65534, with the exception
of 7224, which is reserved in the us-east-1 region, and 9059, which is reserved in the eu-west-1
region.
For more information about VPN customer gateways, see Adding a Hardware Virtual Private Gateway to
Your VPC in the Amazon Virtual Private Cloud User Guide .
Warning: You cannot create more than one customer gateway with the same VPN type, IP address,
and BGP ASN parameter values. If you run an identical request more than one time, the first request
creates the customer gateway, and subsequent requests return information about the existing customer
gateway. The subsequent requests do not create new customer gateway resources.
Request Syntax
response = client.create_customer_gateway(
DryRun=True|False,
Type='ipsec.1',
PublicIp='string',
BgpAsn=123
)
Parameters
3.1. Services 1133
Boto3 Documentation, Release 1.1.4
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Type (string) – [REQUIRED]
The type of VPN connection that this customer gateway supports (ipsec.1 ).
• PublicIp (string) – [REQUIRED]
The Internet-routable IP address for the customer gateway’s outside interface.
The address must be static.
• BgpAsn (integer) – [REQUIRED]
For devices that support BGP, the customer gateway’s BGP ASN.
Default: 65000
Return type dict
Returns
Response Syntax
{
'CustomerGateway': {
'CustomerGatewayId': 'string',
'State': 'string',
'Type': 'string',
'IpAddress': 'string',
'BgpAsn': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
– CustomerGateway (dict) –
Information about the customer gateway.
* CustomerGatewayId (string) –
The ID of the customer gateway.
* State (string) –
The current state of the customer gateway (pending |
available | deleting | deleted ).
* Type (string) –
The type of VPN connection the customer gateway supports
(ipsec.1 ).
* IpAddress (string) –
The Internet-routable IP address of the customer gateway’s outside
interface.
* BgpAsn (string) –
The customer gateway’s Border Gateway Protocol (BGP) Au-
tonomous System Number (ASN).
1134 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Tags (list) –
Any tags assigned to the customer gateway.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
create_dhcp_options(**kwargs)
Creates a set of DHCP options for your VPC. After creating the set, you must associate it with the VPC,
causing all existing and new instances that you launch in the VPC to use this set of DHCP options. The
following are the individual DHCP options you can specify. For more information about the options, see
RFC 2132 .
•domain-name-servers - The IP addresses of up to four domain name servers, or
AmazonProvidedDNS . The default DHCP option set specifies AmazonProvidedDNS . If
specifying more than one domain name server, specify the IP addresses in a single parameter, sep-
arated by commas.
•domain-name - If you’re using AmazonProvidedDNS in us-east-1 , specify
ec2.internal . If you’re using AmazonProvidedDNS in another region, specify
region.compute.internal (for example, ap-northeast-1.compute.internal ).
Otherwise, specify a domain name (for example, MyCompany.com ). Important : Some Linux
operating systems accept multiple domain names separated by spaces. However, Windows and
other Linux operating systems treat the value as a single domain, which results in unexpected
behavior. If your DHCP options set is associated with a VPC that has instances with multiple
operating systems, specify only one domain name.
•ntp-servers - The IP addresses of up to four Network Time Protocol (NTP) servers.
•netbios-name-servers - The IP addresses of up to four NetBIOS name servers.
•netbios-node-type - The NetBIOS node type (1, 2, 4, or 8). We recommend that you specify
2 (broadcast and multicast are not currently supported). For more information about these node
types, see RFC 2132 .
Your VPC automatically starts out with a set of DHCP options that includes only a DNS server that we
provide (AmazonProvidedDNS). If you create a set of options, and if your VPC has an Internet gateway,
make sure to set the domain-name-servers option either to AmazonProvidedDNS or to a domain
name server of your choice. For more information about DHCP options, see DHCP Options Sets in the
Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.create_dhcp_options(
DryRun=True|False,
DhcpConfigurations=[
{
'Key': 'string',
'Values': [
'string',
]
},
3.1. Services 1135
Boto3 Documentation, Release 1.1.4
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• DhcpConfigurations (list) – [REQUIRED]
A DHCP configuration option.
– (dict) –
* Key (string) –
* Values (list) –
· (string) –
Return type dict
Returns
Response Syntax
{
'DhcpOptions': {
'DhcpOptionsId': 'string',
'DhcpConfigurations': [
{
'Key': 'string',
'Values': [
{
'Value': 'string'
},
]
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
– DhcpOptions (dict) –
A set of DHCP options.
* DhcpOptionsId (string) –
The ID of the set of DHCP options.
* DhcpConfigurations (list) –
One or more DHCP options in the set.
· (dict) –
Describes a DHCP configuration option.
· Key (string) –
The name of a DHCP option.
1136 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Values (list) –
One or more values for the DHCP option.
· (dict) –
The value to use for a resource attribute.
· Value (string) –
Valid values are case-sensitive and vary by action.
* Tags (list) –
Any tags assigned to the DHCP options set.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
create_flow_logs(**kwargs)
Creates one or more flow logs to capture IP traffic for a specific network interface, subnet, or VPC. Flow
logs are delivered to a specified log group in Amazon CloudWatch Logs. If you specify a VPC or subnet
in the request, a log stream is created in CloudWatch Logs for each network interface in the subnet or
VPC. Log streams can include information about accepted and rejected traffic to a network interface. You
can view the data in your log streams using Amazon CloudWatch Logs.
In your request, you must also specify an IAM role that has permission to publish logs to CloudWatch
Logs.
Request Syntax
response = client.create_flow_logs(
ResourceIds=[
'string',
],
ResourceType='VPC'|'Subnet'|'NetworkInterface',
TrafficType='ACCEPT'|'REJECT'|'ALL',
LogGroupName='string',
DeliverLogsPermissionArn='string',
ClientToken='string'
)
Parameters
• ResourceIds (list) – [REQUIRED]
One or more subnet, network interface, or VPC IDs.
– (string) –
• ResourceType (string) – [REQUIRED]
The type of resource on which to create the flow log.
• TrafficType (string) – [REQUIRED]
The type of traffic to log.
3.1. Services 1137
Boto3 Documentation, Release 1.1.4
• LogGroupName (string) – [REQUIRED]
The name of the CloudWatch log group.
• DeliverLogsPermissionArn (string) – [REQUIRED]
The ARN for the IAM role that’s used to post flow logs to a CloudWatch Logs
log group.
• ClientToken (string) – Unique, case-sensitive identifier you provide to ensure
the idempotency of the request. For more information, see How to Ensure Idem-
potency .
Return type dict
Returns
Response Syntax
{
'FlowLogIds': [
'string',
],
'ClientToken': 'string',
'Unsuccessful': [
{
'ResourceId': 'string',
'Error': {
'Code': 'string',
'Message': 'string'
}
},
]
}
Response Structure
• (dict) –
– FlowLogIds (list) –
The IDs of the flow logs.
* (string) –
– ClientToken (string) –
Unique, case-sensitive identifier you provide to ensure the idempotency of
the request.
– Unsuccessful (list) –
Information about the flow logs that could not be created successfully.
* (dict) –
Information about items that were not successfully processed in a
batch call.
· ResourceId (string) –
The ID of the resource.
· Error (dict) –
Information about the error.
· Code (string) –
The error code.
· Message (string) –
The error message accompanying the error code.
1138 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
create_image(**kwargs)
Creates an Amazon EBS-backed AMI from an Amazon EBS-backed instance that is either running or
stopped.
If you customized your instance with instance store volumes or EBS volumes in addition to the root device
volume, the new AMI contains block device mapping information for those volumes. When you launch
an instance from this new AMI, the instance automatically launches with those additional volumes.
For more information, see Creating Amazon EBS-Backed Linux AMIs in the Amazon Elastic Compute
Cloud User Guide .
Request Syntax
response = client.create_image(
DryRun=True|False,
InstanceId='string',
Name='string',
Description='string',
NoReboot=True|False,
BlockDeviceMappings=[
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the instance.
• Name (string) – [REQUIRED]
A name for the new image.
Constraints: 3-128 alphanumeric characters, parentheses (()), square brackets
([]), spaces ( ), periods (.), slashes (/), dashes (-), single quotes (‘), at-signs (@),
or underscores(_)
• Description (string) – A description for the new image.
• NoReboot (boolean) – By default, this parameter is set to false , which means
Amazon EC2 attempts to shut down the instance cleanly before image creation
and then reboots the instance. When the parameter is set to true , Amazon EC2
doesn’t shut down the instance before creating the image. When this option is
used, file system integrity on the created image can’t be guaranteed.
• BlockDeviceMappings (list) – Information about one or more block device
mappings.
3.1. Services 1139
Boto3 Documentation, Release 1.1.4
– (dict) –
Describes a block device mapping.
* VirtualName (string) –
The virtual device name (ephemeral N). Instance store volumes
are numbered starting from 0. An instance type with 2 available in-
stance store volumes can specify mappings for ephemeral0 and
ephemeral1 .The number of available instance store volumes de-
pends on the instance type. After you connect to the instance, you
must mount the volume.
Constraints: For M3 instances, you must specify instance store vol-
umes in the block device mapping for the instance. When you
launch an M3 instance, we ignore any instance store volumes spec-
ified in the block device mapping for the AMI.
* DeviceName (string) –
The device name exposed to the instance (for example, /dev/sdh
or xvdh ).
* Ebs (dict) –
Parameters used to automatically set up EBS volumes when the in-
stance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
1140 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
* NoDevice (string) –
Suppresses the specified device included in the block device map-
ping of the AMI.
Return type dict
Returns
Response Syntax
{
'ImageId': 'string'
}
Response Structure
• (dict) –
– ImageId (string) –
The ID of the new AMI.
create_instance_export_task(**kwargs)
Exports a running or stopped instance to an S3 bucket.
For information about the supported operating systems, image formats, and known limitations for the
types of instances you can export, see Exporting EC2 Instances in the Amazon Elastic Compute Cloud
User Guide .
Request Syntax
response = client.create_instance_export_task(
Description='string',
InstanceId='string',
TargetEnvironment='citrix'|'vmware'|'microsoft',
ExportToS3Task={
'DiskImageFormat': 'VMDK'|'RAW'|'VHD',
'ContainerFormat': 'ova',
'S3Bucket': 'string',
'S3Prefix': 'string'
}
)
Parameters
• Description (string) – A description for the conversion task or the resource being
exported. The maximum length is 255 bytes.
• InstanceId (string) – [REQUIRED]
The ID of the instance.
• TargetEnvironment (string) – The target virtualization environment.
• ExportToS3Task (dict) – The format and location for an instance export task.
3.1. Services 1141
Boto3 Documentation, Release 1.1.4
– DiskImageFormat (string) –
The format for the exported image.
– ContainerFormat (string) –
The container format used to combine disk images with metadata (such as
OVF). If absent, only the disk image is exported.
– S3Bucket (string) –
The S3 bucket for the destination image. The destination bucket must
exist and grant WRITE and READ_ACP permissions to the AWS account
[email protected] .
– S3Prefix (string) –
The image is written to a single object in the S3 bucket at the S3 key
s3prefix + exportTaskId + ‘.’ + diskImageFormat.
Return type dict
Returns
Response Syntax
{
'ExportTask': {
'ExportTaskId': 'string',
'Description': 'string',
'State': 'active'|'cancelling'|'cancelled'|'completed',
'StatusMessage': 'string',
'InstanceExportDetails': {
'InstanceId': 'string',
'TargetEnvironment': 'citrix'|'vmware'|'microsoft'
},
'ExportToS3Task': {
'DiskImageFormat': 'VMDK'|'RAW'|'VHD',
'ContainerFormat': 'ova',
'S3Bucket': 'string',
'S3Key': 'string'
}
}
}
Response Structure
• (dict) –
– ExportTask (dict) –
Information about the instance export task.
* ExportTaskId (string) –
The ID of the export task.
* Description (string) –
A description of the resource being exported.
* State (string) –
The state of the export task.
* StatusMessage (string) –
The status message related to the export task.
* InstanceExportDetails (dict) –
Information about the instance to export.
1142 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· InstanceId (string) –
The ID of the resource being exported.
· TargetEnvironment (string) –
The target virtualization environment.
* ExportToS3Task (dict) –
Information about the export task.
· DiskImageFormat (string) –
The format for the exported image.
· ContainerFormat (string) –
The container format used to combine disk images with meta-
data (such as OVF). If absent, only the disk image is exported.
· S3Bucket (string) –
The S3 bucket for the destination image. The
destination bucket must exist and grant WRITE
and READ_ACP permissions to the AWS account
[email protected] .
· S3Key (string) –
The encryption key for your S3 bucket.
create_internet_gateway(**kwargs)
Creates an Internet gateway for use with a VPC. After creating the Internet gateway, you attach it to a
VPC using AttachInternetGateway .
For more information about your VPC and Internet gateway, see the Amazon Virtual Private Cloud User
Guide .
Request Syntax
response = client.create_internet_gateway(
DryRun=True|False
)
Parameters DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If you have
the required permissions, the error response is DryRunOperation . Otherwise, it is
UnauthorizedOperation .
Return type dict
Returns
Response Syntax
{
'InternetGateway': {
'InternetGatewayId': 'string',
'Attachments': [
{
'VpcId': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached'
},
],
'Tags': [
{
'Key': 'string',
3.1. Services 1143
Boto3 Documentation, Release 1.1.4
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
– InternetGateway (dict) –
Information about the Internet gateway.
* InternetGatewayId (string) –
The ID of the Internet gateway.
* Attachments (list) –
Any VPCs attached to the Internet gateway.
· (dict) –
Describes the attachment of a VPC to an Internet gateway.
· VpcId (string) –
The ID of the VPC.
· State (string) –
The current state of the attachment.
* Tags (list) –
Any tags assigned to the Internet gateway.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
create_key_pair(**kwargs)
Creates a 2048-bit RSA key pair with the specified name. Amazon EC2 stores the public key and displays
the private key for you to save to a file. The private key is returned as an unencrypted PEM encoded
PKCS#8 private key. If a key with the specified name already exists, Amazon EC2 returns an error.
You can have up to five thousand key pairs per region.
The key pair returned to you is available only in the region in which you create it. To create a key pair
that is available in all regions, use ImportKeyPair .
For more information about key pairs, see Key Pairs in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.create_key_pair(
DryRun=True|False,
KeyName='string'
)
1144 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• KeyName (string) – [REQUIRED]
A unique name for the key pair.
Constraints: Up to 255 ASCII characters
Return type dict
Returns
Response Syntax
{
'KeyName': 'string',
'KeyFingerprint': 'string',
'KeyMaterial': 'string'
}
Response Structure
• (dict) –
Information about the key pair.
– KeyName (string) –
The name of the key pair.
– KeyFingerprint (string) –
The SHA-1 digest of the DER encoded private key.
– KeyMaterial (string) –
An unencrypted PEM encoded RSA private key.
create_network_acl(**kwargs)
Creates a network ACL in a VPC. Network ACLs provide an optional layer of security (in addition to
security groups) for the instances in your VPC.
For more information about network ACLs, see Network ACLs in the Amazon Virtual Private Cloud User
Guide .
Request Syntax
response = client.create_network_acl(
DryRun=True|False,
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Return type dict
Returns
Response Syntax
3.1. Services 1145
Boto3 Documentation, Release 1.1.4
{
'NetworkAcl': {
'NetworkAclId': 'string',
'VpcId': 'string',
'IsDefault': True|False,
'Entries': [
{
'RuleNumber': 123,
'Protocol': 'string',
'RuleAction': 'allow'|'deny',
'Egress': True|False,
'CidrBlock': 'string',
'IcmpTypeCode': {
'Type': 123,
'Code': 123
},
'PortRange': {
'From': 123,
'To': 123
}
},
],
'Associations': [
{
'NetworkAclAssociationId': 'string',
'NetworkAclId': 'string',
'SubnetId': 'string'
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
– NetworkAcl (dict) –
Information about the network ACL.
* NetworkAclId (string) –
The ID of the network ACL.
* VpcId (string) –
The ID of the VPC for the network ACL.
* IsDefault (boolean) –
Indicates whether this is the default network ACL for the VPC.
* Entries (list) –
One or more entries (rules) in the network ACL.
· (dict) –
Describes an entry in a network ACL.
· RuleNumber (integer) –
1146 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The rule number for the entry. ACL entries are processed in
ascending order by rule number.
· Protocol (string) –
The protocol. A value of -1 means all protocols.
· RuleAction (string) –
Indicates whether to allow or deny the traffic that matches the
rule.
· Egress (boolean) –
Indicates whether the rule is an egress rule (applied to traffic
leaving the subnet).
· CidrBlock (string) –
The network range to allow or deny, in CIDR notation.
· IcmpTypeCode (dict) –
ICMP protocol: The ICMP type and code.
· Type (integer) –
The ICMP code. A value of -1 means all codes for the speci-
fied ICMP type.
· Code (integer) –
The ICMP type. A value of -1 means all types.
· PortRange (dict) –
TCP or UDP protocols: The range of ports the rule applies to.
· From (integer) –
The first port in the range.
· To (integer) –
The last port in the range.
* Associations (list) –
Any associations between the network ACL and one or more sub-
nets
· (dict) –
Describes an association between a network ACL and a sub-
net.
· NetworkAclAssociationId (string) –
The ID of the association between a network ACL and a sub-
net.
· NetworkAclId (string) –
The ID of the network ACL.
· SubnetId (string) –
The ID of the subnet.
* Tags (list) –
Any tags assigned to the network ACL.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
3.1. Services 1147
Boto3 Documentation, Release 1.1.4
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
create_network_acl_entry(**kwargs)
Creates an entry (a rule) in a network ACL with the specified rule number. Each network ACL has a
set of numbered ingress rules and a separate set of numbered egress rules. When determining whether
a packet should be allowed in or out of a subnet associated with the ACL, we process the entries in the
ACL according to the rule numbers, in ascending order. Each network ACL has a set of ingress rules and
a separate set of egress rules.
We recommend that you leave room between the rule numbers (for example, 100, 110, 120, ...), and not
number them one right after the other (for example, 101, 102, 103, ...). This makes it easier to add a rule
between existing ones without having to renumber the rules.
After you add an entry, you can’t modify it; you must either replace it, or create an entry and delete the
old one.
For more information about network ACLs, see Network ACLs in the Amazon Virtual Private Cloud User
Guide .
Request Syntax
response = client.create_network_acl_entry(
DryRun=True|False,
NetworkAclId='string',
RuleNumber=123,
Protocol='string',
RuleAction='allow'|'deny',
Egress=True|False,
CidrBlock='string',
IcmpTypeCode={
'Type': 123,
'Code': 123
},
PortRange={
'From': 123,
'To': 123
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkAclId (string) – [REQUIRED]
The ID of the network ACL.
• RuleNumber (integer) – [REQUIRED]
The rule number for the entry (for example, 100). ACL entries are processed in
ascending order by rule number.
Constraints: Positive integer from 1 to 32766
1148 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• Protocol (string) – [REQUIRED]
The protocol. A value of -1 means all protocols.
• RuleAction (string) – [REQUIRED]
Indicates whether to allow or deny the traffic that matches the rule.
• Egress (boolean) – [REQUIRED]
Indicates whether this is an egress rule (rule is applied to traffic leaving the sub-
net).
• CidrBlock (string) – [REQUIRED]
The network range to allow or deny, in CIDR notation (for example
172.16.0.0/24 ).
• IcmpTypeCode (dict) – ICMP protocol: The ICMP type and code. Required if
specifying ICMP for the protocol.
– Type (integer) –
The ICMP code. A value of -1 means all codes for the specified ICMP
type.
– Code (integer) –
The ICMP type. A value of -1 means all types.
• PortRange (dict) – TCP or UDP protocols: The range of ports the rule applies
to.
– From (integer) –
The first port in the range.
– To (integer) –
The last port in the range.
Returns None
create_network_interface(**kwargs)
Creates a network interface in the specified subnet.
For more information about network interfaces, see Elastic Network Interfaces in the Amazon Elastic
Compute Cloud User Guide .
Request Syntax
response = client.create_network_interface(
SubnetId='string',
Description='string',
PrivateIpAddress='string',
Groups=[
'string',
],
PrivateIpAddresses=[
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
SecondaryPrivateIpAddressCount=123,
DryRun=True|False
)
Parameters
• SubnetId (string) – [REQUIRED]
3.1. Services 1149
Boto3 Documentation, Release 1.1.4
The ID of the subnet to associate with the network interface.
• Description (string) – A description for the network interface.
• PrivateIpAddress (string) – The primary private IP address of the network in-
terface. If you don’t specify an IP address, Amazon EC2 selects one for you from
the subnet range. If you specify an IP address, you cannot indicate any IP ad-
dresses specified in privateIpAddresses as primary (only one IP address
can be designated as primary).
• Groups (list) – The IDs of one or more security groups.
– (string) –
• PrivateIpAddresses (list) – One or more private IP addresses.
– (dict) –
Describes a secondary private IP address for a network interface.
* PrivateIpAddress (string) – [REQUIRED]
The private IP addresses.
* Primary (boolean) –
Indicates whether the private IP address is the primary private IP
address. Only one IP address can be designated as primary.
• SecondaryPrivateIpAddressCount (integer) – The number of secondary pri-
vate IP addresses to assign to a network interface. When you specify a number
of secondary IP addresses, Amazon EC2 selects these IP addresses within the
subnet range. You can’t specify this option and specify more than one private IP
address using privateIpAddresses .
The number of IP addresses you can assign to a network interface varies by
instance type. For more information, see Private IP Addresses Per ENI Per In-
stance Type in the Amazon Elastic Compute Cloud User Guide .
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
Return type dict
Returns
Response Syntax
{
'NetworkInterface': {
'NetworkInterfaceId': 'string',
'SubnetId': 'string',
'VpcId': 'string',
'AvailabilityZone': 'string',
'Description': 'string',
'OwnerId': 'string',
'RequesterId': 'string',
'RequesterManaged': True|False,
'Status': 'available'|'attaching'|'in-use'|'detaching',
'MacAddress': 'string',
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'SourceDestCheck': True|False,
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
1150 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'Attachment': {
'AttachmentId': 'string',
'InstanceId': 'string',
'InstanceOwnerId': 'string',
'DeviceIndex': 123,
'Status': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
},
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string',
'AllocationId': 'string',
'AssociationId': 'string'
},
'TagSet': [
{
'Key': 'string',
'Value': 'string'
},
],
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'Primary': True|False,
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string',
'AllocationId': 'string',
'AssociationId': 'string'
}
},
]
}
}
Response Structure
• (dict) –
– NetworkInterface (dict) –
Information about the network interface.
* NetworkInterfaceId (string) –
The ID of the network interface.
* SubnetId (string) –
The ID of the subnet.
* VpcId (string) –
The ID of the VPC.
* AvailabilityZone (string) –
The Availability Zone.
* Description (string) –
A description.
3.1. Services 1151
Boto3 Documentation, Release 1.1.4
* OwnerId (string) –
The AWS account ID of the owner of the network interface.
* RequesterId (string) –
The ID of the entity that launched the instance on your behalf (for
example, AWS Management Console or Auto Scaling).
* RequesterManaged (boolean) –
Indicates whether the network interface is being managed by AWS.
* Status (string) –
The status of the network interface.
* MacAddress (string) –
The MAC address.
* PrivateIpAddress (string) –
The IP address of the network interface within the subnet.
* PrivateDnsName (string) –
The private DNS name.
* SourceDestCheck (boolean) –
Indicates whether traffic to or from the instance is validated.
* Groups (list) –
Any security groups for the network interface.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
* Attachment (dict) –
The network interface attachment.
· AttachmentId (string) –
The ID of the network interface attachment.
· InstanceId (string) –
The ID of the instance.
· InstanceOwnerId (string) –
The AWS account ID of the owner of the instance.
· DeviceIndex (integer) –
The device index of the network interface attachment on the
instance.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The timestamp indicating when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the network interface is deleted when the
instance is terminated.
1152 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Association (dict) –
The association information for an Elastic IP associated with the
network interface.
· PublicIp (string) –
The address of the Elastic IP address bound to the network
interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the Elastic IP address owner.
· AllocationId (string) –
The allocation ID.
· AssociationId (string) –
The association ID.
* TagSet (list) –
Any tags assigned to the network interface.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
* PrivateIpAddresses (list) –
The private IP addresses associated with the network interface.
· (dict) –
Describes the private IP address of a network interface.
· PrivateIpAddress (string) –
The private IP address.
· PrivateDnsName (string) –
The private DNS name.
· Primary (boolean) –
Indicates whether this IP address is the primary private IP ad-
dress of the network interface.
· Association (dict) –
The association information for an Elastic IP address associ-
ated with the network interface.
· PublicIp (string) –
The address of the Elastic IP address bound to the network
interface.
3.1. Services 1153
Boto3 Documentation, Release 1.1.4
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the Elastic IP address owner.
· AllocationId (string) –
The allocation ID.
· AssociationId (string) –
The association ID.
create_placement_group(**kwargs)
Creates a placement group that you launch cluster instances into. You must give the group a name that’s
unique within the scope of your account.
For more information about placement groups and cluster instances, see Cluster Instances in the Amazon
Elastic Compute Cloud User Guide .
Request Syntax
response = client.create_placement_group(
DryRun=True|False,
GroupName='string',
Strategy='cluster'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupName (string) – [REQUIRED]
A name for the placement group.
Constraints: Up to 255 ASCII characters
• Strategy (string) – [REQUIRED]
The placement strategy.
Returns None
create_reserved_instances_listing(**kwargs)
Creates a listing for Amazon EC2 Reserved Instances to be sold in the Reserved Instance Marketplace.
You can submit one Reserved Instance listing at a time. To get a list of your Reserved Instances, you can
use the DescribeReservedInstances operation.
The Reserved Instance Marketplace matches sellers who want to resell Reserved Instance capacity that
they no longer need with buyers who want to purchase additional capacity. Reserved Instances bought
and sold through the Reserved Instance Marketplace work like any other Reserved Instances.
To sell your Reserved Instances, you must first register as a seller in the Reserved Instance Marketplace.
After completing the registration process, you can create a Reserved Instance Marketplace listing of some
or all of your Reserved Instances, and specify the upfront price to receive for them. Your Reserved
Instance listings then become available for purchase. To view the details of your Reserved Instance
listing, you can use the DescribeReservedInstancesListings operation.
For more information, see Reserved Instance Marketplace in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
1154 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.create_reserved_instances_listing(
ReservedInstancesId='string',
InstanceCount=123,
PriceSchedules=[
{
'Term': 123,
'Price': 123.0,
'CurrencyCode': 'USD'
},
],
ClientToken='string'
)
Parameters
• ReservedInstancesId (string) – [REQUIRED]
The ID of the active Reserved Instance.
• InstanceCount (integer) – [REQUIRED]
The number of instances that are a part of a Reserved Instance account to be
listed in the Reserved Instance Marketplace. This number should be less than or
equal to the instance count associated with the Reserved Instance ID specified in
this call.
• PriceSchedules (list) – [REQUIRED]
A list specifying the price of the Reserved Instance for each month remaining in
the Reserved Instance term.
– (dict) –
Describes the price for a Reserved Instance.
* Term (integer) –
The number of months remaining in the reservation. For example,
2 is the second to the last month before the capacity reservation
expires.
* Price (float) –
The fixed price for the term.
* CurrencyCode (string) –
The currency for transacting the Reserved Instance resale. At this
time, the only supported currency is USD .
• ClientToken (string) – [REQUIRED]
Unique, case-sensitive identifier you provide to ensure idempotency of your list-
ings. This helps avoid duplicate listings. For more information, see Ensuring
Idempotency .
Return type dict
Returns
Response Syntax
{
'ReservedInstancesListings': [
{
'ReservedInstancesListingId': 'string',
'ReservedInstancesId': 'string',
'CreateDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
3.1. Services 1155
Boto3 Documentation, Release 1.1.4
'Status': 'active'|'pending'|'cancelled'|'closed',
'StatusMessage': 'string',
'InstanceCounts': [
{
'State': 'available'|'sold'|'cancelled'|'pending',
'InstanceCount': 123
},
],
'PriceSchedules': [
{
'Term': 123,
'Price': 123.0,
'CurrencyCode': 'USD',
'Active': True|False
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'ClientToken': 'string'
},
]
}
Response Structure
• (dict) –
– ReservedInstancesListings (list) –
Information about the Reserved Instances listing.
* (dict) –
Describes a Reserved Instance listing.
· ReservedInstancesListingId (string) –
The ID of the Reserved Instance listing.
· ReservedInstancesId (string) –
The ID of the Reserved Instance.
· CreateDate (datetime) –
The time the listing was created.
· UpdateDate (datetime) –
The last modified timestamp of the listing.
· Status (string) –
The status of the Reserved Instance listing.
· StatusMessage (string) –
The reason for the current status of the Reserved Instance list-
ing. The response can be blank.
· InstanceCounts (list) –
The number of instances in this state.
· (dict) –
Describes a Reserved Instance listing state.
1156 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· State (string) –
The states of the listed Reserved Instances.
· InstanceCount (integer) –
The number of listed Reserved Instances in the state specified
by the state .
· PriceSchedules (list) –
The price of the Reserved Instance listing.
· (dict) –
Describes the price for a Reserved Instance.
· Term (integer) –
The number of months remaining in the reservation. For ex-
ample, 2 is the second to the last month before the capacity
reservation expires.
· Price (float) –
The fixed price for the term.
· CurrencyCode (string) –
The currency for transacting the Reserved Instance resale. At
this time, the only supported currency is USD .
· Active (boolean) –
The current price schedule, as determined by the term remain-
ing for the Reserved Instance in the listing.
A specific price schedule is always in effect, but only one
price schedule can be active at any time. Take, for exam-
ple, a Reserved Instance listing that has five months remain-
ing in its term. When you specify price schedules for five
months and two months, this means that schedule 1, covering
the first three months of the remaining term, will be active
during months 5, 4, and 3. Then schedule 2, covering the last
two months of the term, will be active for months 2 and 1.
· Tags (list) –
Any tags assigned to the resource.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· ClientToken (string) –
A unique, case-sensitive key supplied by the client to ensure
that the request is idempotent. For more information, see En-
suring Idempotency .
3.1. Services 1157
Boto3 Documentation, Release 1.1.4
create_route(**kwargs)
Creates a route in a route table within a VPC.
You must specify one of the following targets: Internet gateway or virtual private gateway, NAT instance,
VPC peering connection, or network interface.
When determining how to route traffic, we use the route with the most specific match. For example, let’s
say the traffic is destined for 192.0.2.3 , and the route table includes the following two routes:
•192.0.2.0/24 (goes to some target A)
•192.0.2.0/28 (goes to some target B)
Both routes apply to the traffic destined for 192.0.2.3 . However, the second route in the list covers a
smaller number of IP addresses and is therefore more specific, so we use that route to determine where to
target the traffic.
For more information about route tables, see Route Tables in the Amazon Virtual Private Cloud User
Guide .
Request Syntax
response = client.create_route(
DryRun=True|False,
RouteTableId='string',
DestinationCidrBlock='string',
GatewayId='string',
InstanceId='string',
NetworkInterfaceId='string',
VpcPeeringConnectionId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• RouteTableId (string) – [REQUIRED]
The ID of the route table for the route.
• DestinationCidrBlock (string) – [REQUIRED]
The CIDR address block used for the destination match. Routing decisions are
based on the most specific match.
• GatewayId (string) – The ID of an Internet gateway or virtual private gateway
attached to your VPC.
• InstanceId (string) – The ID of a NAT instance in your VPC. The operation fails
if you specify an instance ID unless exactly one network interface is attached.
• NetworkInterfaceId (string) – The ID of a network interface.
• VpcPeeringConnectionId (string) – The ID of a VPC peering connection.
Return type dict
Returns
Response Syntax
{
'Return': True|False
}
Response Structure
• (dict) –
1158 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– Return (boolean) –
Returns true if the request succeeds; otherwise, it returns an error.
create_route_table(**kwargs)
Creates a route table for the specified VPC. After you create a route table, you can add routes and associate
the table with a subnet.
For more information about route tables, see Route Tables in the Amazon Virtual Private Cloud User
Guide .
Request Syntax
response = client.create_route_table(
DryRun=True|False,
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Return type dict
Returns
Response Syntax
{
'RouteTable': {
'RouteTableId': 'string',
'VpcId': 'string',
'Routes': [
{
'DestinationCidrBlock': 'string',
'DestinationPrefixListId': 'string',
'GatewayId': 'string',
'InstanceId': 'string',
'InstanceOwnerId': 'string',
'NetworkInterfaceId': 'string',
'VpcPeeringConnectionId': 'string',
'State': 'active'|'blackhole',
'Origin': 'CreateRouteTable'|'CreateRoute'|'EnableVgwRoutePropagat
},
],
'Associations': [
{
'RouteTableAssociationId': 'string',
'RouteTableId': 'string',
'SubnetId': 'string',
'Main': True|False
},
],
'Tags': [
{
'Key': 'string',
3.1. Services 1159
Boto3 Documentation, Release 1.1.4
'Value': 'string'
},
],
'PropagatingVgws': [
{
'GatewayId': 'string'
},
]
}
}
Response Structure
• (dict) –
– RouteTable (dict) –
Information about the route table.
* RouteTableId (string) –
The ID of the route table.
* VpcId (string) –
The ID of the VPC.
* Routes (list) –
The routes in the route table.
· (dict) –
Describes a route in a route table.
· DestinationCidrBlock (string) –
The CIDR block used for the destination match.
· DestinationPrefixListId (string) –
The prefix of the AWS service.
· GatewayId (string) –
The ID of a gateway attached to your VPC.
· InstanceId (string) –
The ID of a NAT instance in your VPC.
· InstanceOwnerId (string) –
The AWS account ID of the owner of the instance.
· NetworkInterfaceId (string) –
The ID of the network interface.
· VpcPeeringConnectionId (string) –
The ID of the VPC peering connection.
· State (string) –
The state of the route. The blackhole state indicates that
the route’s target isn’t available (for example, the specified
gateway isn’t attached to the VPC, or the specified NAT in-
stance has been terminated).
· Origin (string) –
Describes how the route was created.
· CreateRouteTable indicates that route was automati-
cally created when the route table was created.
1160 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· CreateRoute indicates that the route was manually added
to the route table.
· EnableVgwRoutePropagation indicates that the route
was propagated by route propagation.
* Associations (list) –
The associations between the route table and one or more subnets.
· (dict) –
Describes an association between a route table and a subnet.
· RouteTableAssociationId (string) –
The ID of the association between a route table and a subnet.
· RouteTableId (string) –
The ID of the route table.
· SubnetId (string) –
The ID of the subnet. A subnet ID is not returned for an im-
plicit association.
· Main (boolean) –
Indicates whether this is the main route table.
* Tags (list) –
Any tags assigned to the route table.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
* PropagatingVgws (list) –
Any virtual private gateway (VGW) propagating routes.
· (dict) –
Describes a virtual private gateway propagating route.
· GatewayId (string) –
The ID of the virtual private gateway (VGW).
create_security_group(**kwargs)
Creates a security group.
A security group is for use with instances either in the EC2-Classic platform or in a specific VPC. For
more information, see Amazon EC2 Security Groups in the Amazon Elastic Compute Cloud User Guide
and Security Groups for Your VPC in the Amazon Virtual Private Cloud User Guide .
Warning: EC2-Classic: You can have up to 500 security groups.
EC2-VPC: You can create up to 100 security groups per VPC.
3.1. Services 1161
Boto3 Documentation, Release 1.1.4
When you create a security group, you specify a friendly name of your choice. You can have a security
group for use in EC2-Classic with the same name as a security group for use in a VPC. However, you
can’t have two security groups for use in EC2-Classic with the same name or two security groups for use
in a VPC with the same name.
You have a default security group for use in EC2-Classic and a default security group for use in your
VPC. If you don’t specify a security group when you launch an instance, the instance is launched into the
appropriate default security group. A default security group includes a default rule that grants instances
unrestricted network access to each other.
You can add or remove rules from your security groups using AuthorizeSecurityGroupIngress , Autho-
rizeSecurityGroupEgress , RevokeSecurityGroupIngress , and RevokeSecurityGroupEgress .
Request Syntax
response = client.create_security_group(
DryRun=True|False,
GroupName='string',
Description='string',
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupName (string) – [REQUIRED]
The name of the security group.
Constraints: Up to 255 characters in length
Constraints for EC2-Classic: ASCII characters
Constraints for EC2-VPC: a-z, A-Z, 0-9, spaces, and ._-:/()#,@[]+=;{}!$*
• Description (string) – [REQUIRED]
A description for the security group. This is informational only.
Constraints: Up to 255 characters in length
Constraints for EC2-Classic: ASCII characters
Constraints for EC2-VPC: a-z, A-Z, 0-9, spaces, and ._-:/()#,@[]+=;{}!$*
• VpcId (string) – [EC2-VPC] The ID of the VPC. Required for EC2-VPC.
Return type dict
Returns
Response Syntax
{
'GroupId': 'string'
}
Response Structure
• (dict) –
– GroupId (string) –
The ID of the security group.
1162 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
create_snapshot(**kwargs)
Creates a snapshot of an EBS volume and stores it in Amazon S3. You can use snapshots for backups, to
make copies of EBS volumes, and to save data before shutting down an instance.
When a snapshot is created, any AWS Marketplace product codes that are associated with the source
volume are propagated to the snapshot.
You can take a snapshot of an attached volume that is in use. However, snapshots only capture data that
has been written to your EBS volume at the time the snapshot command is issued; this may exclude any
data that has been cached by any applications or the operating system. If you can pause any file systems
on the volume long enough to take a snapshot, your snapshot should be complete. However, if you cannot
pause all file writes to the volume, you should unmount the volume from within the instance, issue the
snapshot command, and then remount the volume to ensure a consistent and complete snapshot. You may
remount and use your volume while the snapshot status is pending .
To create a snapshot for EBS volumes that serve as root devices, you should stop the instance before
taking the snapshot.
Snapshots that are taken from encrypted volumes are automatically encrypted. Volumes that are created
from encrypted snapshots are also automatically encrypted. Your encrypted volumes and any associated
snapshots always remain protected.
For more information, see Amazon Elastic Block Store and Amazon EBS Encryption in the Amazon
Elastic Compute Cloud User Guide .
Request Syntax
response = client.create_snapshot(
DryRun=True|False,
VolumeId='string',
Description='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeId (string) – [REQUIRED]
The ID of the EBS volume.
• Description (string) – A description for the snapshot.
Return type dict
Returns
Response Syntax
{
'SnapshotId': 'string',
'VolumeId': 'string',
'State': 'pending'|'completed'|'error',
'StateMessage': 'string',
'StartTime': datetime(2015, 1, 1),
'Progress': 'string',
'OwnerId': 'string',
'Description': 'string',
'VolumeSize': 123,
'OwnerAlias': 'string',
'Tags': [
3.1. Services 1163
Boto3 Documentation, Release 1.1.4
{
'Key': 'string',
'Value': 'string'
},
],
'Encrypted': True|False,
'KmsKeyId': 'string',
'DataEncryptionKeyId': 'string'
}
Response Structure
• (dict) –
Information about the snapshot.
– SnapshotId (string) –
The ID of the snapshot. Each snapshot receives a unique identifier when
it is created.
– VolumeId (string) –
The ID of the volume that was used to create the snapshot.
– State (string) –
The snapshot state.
– StateMessage (string) –
Encrypted Amazon EBS snapshots are copied asynchronously. If a snap-
shot copy operation fails (for example, if the proper AWS Key Manage-
ment Service (AWS KMS) permissions are not obtained) this field displays
error state details to help you diagnose why the error occurred. This pa-
rameter is only returned by the DescribeSnapshots API operation.
– StartTime (datetime) –
The time stamp when the snapshot was initiated.
– Progress (string) –
The progress of the snapshot, as a percentage.
– OwnerId (string) –
The AWS account ID of the EBS snapshot owner.
– Description (string) –
The description for the snapshot.
– VolumeSize (integer) –
The size of the volume, in GiB.
– OwnerAlias (string) –
The AWS account alias (for example, amazon , self ) or AWS account
ID that owns the snapshot.
– Tags (list) –
Any tags assigned to the snapshot.
* (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
1164 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
– Encrypted (boolean) –
Indicates whether the snapshot is encrypted.
– KmsKeyId (string) –
The full ARN of the AWS Key Management Service (AWS KMS) cus-
tomer master key (CMK) that was used to protect the volume encryption
key for the parent volume.
– DataEncryptionKeyId (string) –
The data encryption key identifier for the snapshot. This value is a unique
identifier that corresponds to the data encryption key that was used to en-
crypt the original volume or snapshot copy. Because data encryption keys
are inherited by volumes created from snapshots, and vice versa, if snap-
shots share the same data encryption key identifier, then they belong to
the same volume/snapshot lineage. This parameter is only returned by the
DescribeSnapshots API operation.
create_spot_datafeed_subscription(**kwargs)
Creates a data feed for Spot instances, enabling you to view Spot instance usage logs. You can create one
data feed per AWS account. For more information, see Spot Instance Data Feed in the Amazon Elastic
Compute Cloud User Guide .
Request Syntax
response = client.create_spot_datafeed_subscription(
DryRun=True|False,
Bucket='string',
Prefix='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Bucket (string) – [REQUIRED]
The Amazon S3 bucket in which to store the Spot instance data feed.
• Prefix (string) – A prefix for the data feed file names.
Return type dict
Returns
Response Syntax
{
'SpotDatafeedSubscription': {
'OwnerId': 'string',
'Bucket': 'string',
'Prefix': 'string',
'State': 'Active'|'Inactive',
'Fault': {
'Code': 'string',
3.1. Services 1165
Boto3 Documentation, Release 1.1.4
'Message': 'string'
}
}
}
Response Structure
• (dict) –
Contains the output of CreateSpotDatafeedSubscription.
– SpotDatafeedSubscription (dict) –
The Spot instance data feed subscription.
* OwnerId (string) –
The AWS account ID of the account.
* Bucket (string) –
The Amazon S3 bucket where the Spot instance data feed is located.
* Prefix (string) –
The prefix that is prepended to data feed files.
* State (string) –
The state of the Spot instance data feed subscription.
* Fault (dict) –
The fault codes for the Spot instance request, if any.
· Code (string) –
The reason code for the Spot instance state change.
· Message (string) –
The message for the Spot instance state change.
create_subnet(**kwargs)
Creates a subnet in an existing VPC.
When you create each subnet, you provide the VPC ID and the CIDR block you want for the subnet. After
you create a subnet, you can’t change its CIDR block. The subnet’s CIDR block can be the same as the
VPC’s CIDR block (assuming you want only a single subnet in the VPC), or a subset of the VPC’s CIDR
block. If you create more than one subnet in a VPC, the subnets’ CIDR blocks must not overlap. The
smallest subnet (and VPC) you can create uses a /28 netmask (16 IP addresses), and the largest uses a /16
netmask (65,536 IP addresses).
Warning: AWS reserves both the first four and the last IP address in each subnet’s CIDR block.
They’re not available for use.
If you add more than one subnet to a VPC, they’re set up in a star topology with a logical router in the
middle.
If you launch an instance in a VPC using an Amazon EBS-backed AMI, the IP address doesn’t change
if you stop and restart the instance (unlike a similar instance launched outside a VPC, which gets a new
IP address when restarted). It’s therefore possible to have a subnet with no running instances (they’re all
stopped), but no remaining IP addresses available.
For more information about subnets, see Your VPC and Subnets in the Amazon Virtual Private Cloud
User Guide .
Request Syntax
1166 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.create_subnet(
DryRun=True|False,
VpcId='string',
CidrBlock='string',
AvailabilityZone='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – [REQUIRED]
The ID of the VPC.
• CidrBlock (string) – [REQUIRED]
The network range for the subnet, in CIDR notation. For example,
10.0.0.0/24 .
• AvailabilityZone (string) – The Availability Zone for the subnet.
Default: Amazon EC2 selects one for you (recommended).
Return type dict
Returns
Response Syntax
{
'Subnet': {
'SubnetId': 'string',
'State': 'pending'|'available',
'VpcId': 'string',
'CidrBlock': 'string',
'AvailableIpAddressCount': 123,
'AvailabilityZone': 'string',
'DefaultForAz': True|False,
'MapPublicIpOnLaunch': True|False,
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
– Subnet (dict) –
Information about the subnet.
* SubnetId (string) –
The ID of the subnet.
* State (string) –
The current state of the subnet.
* VpcId (string) –
3.1. Services 1167
Boto3 Documentation, Release 1.1.4
The ID of the VPC the subnet is in.
* CidrBlock (string) –
The CIDR block assigned to the subnet.
* AvailableIpAddressCount (integer) –
The number of unused IP addresses in the subnet. Note that the IP
addresses for any stopped instances are considered unavailable.
* AvailabilityZone (string) –
The Availability Zone of the subnet.
* DefaultForAz (boolean) –
Indicates whether this is the default subnet for the Availability Zone.
* MapPublicIpOnLaunch (boolean) –
Indicates whether instances launched in this subnet receive a public
IP address.
* Tags (list) –
Any tags assigned to the subnet.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
create_tags(**kwargs)
Adds or overwrites one or more tags for the specified Amazon EC2 resource or resources. Each resource
can have a maximum of 10 tags. Each tag consists of a key and optional value. Tag keys must be unique
per resource.
For more information about tags, see Tagging Your Resources in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
response = client.create_tags(
DryRun=True|False,
Resources=[
'string',
],
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
Parameters
1168 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Resources (list) – [REQUIRED]
The IDs of one or more resources to tag. For example, ami-1a2b3c4d.
– (string) –
• Tags (list) – [REQUIRED]
One or more tags. The value parameter is required, but if you don’t want the
tag to have a value, specify the parameter with no value, and we set the value to
an empty string.
– (dict) –
Describes a tag.
* Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of
127 Unicode characters. May not begin with aws:
* Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of
255 Unicode characters.
Returns None
create_volume(**kwargs)
Creates an EBS volume that can be attached to an instance in the same Availability Zone. The volume is
created in the regional endpoint that you send the HTTP request to. For more information see Regions
and Endpoints .
You can create a new empty volume or restore a volume from an EBS snapshot. Any AWS Marketplace
product codes from the snapshot are propagated to the volume.
You can create encrypted volumes with the Encrypted parameter. Encrypted volumes may only be
attached to instances that support Amazon EBS encryption. Volumes that are created from encrypted
snapshots are also automatically encrypted. For more information, see Amazon EBS Encryption in the
Amazon Elastic Compute Cloud User Guide .
For more information, see Creating or Restoring an Amazon EBS Volume in the Amazon Elastic Compute
Cloud User Guide .
Request Syntax
response = client.create_volume(
DryRun=True|False,
Size=123,
SnapshotId='string',
AvailabilityZone='string',
VolumeType='standard'|'io1'|'gp2',
Iops=123,
Encrypted=True|False,
KmsKeyId='string'
)
Parameters
3.1. Services 1169
Boto3 Documentation, Release 1.1.4
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Size (integer) – The size of the volume, in GiBs.
Constraints: 1-1024 for standard volumes, 1-16384 for gp2 volumes,
and 4-16384 for io1 volumes. If you specify a snapshot, the volume size
must be equal to or larger than the snapshot size.
Default: If you’re creating the volume from a snapshot and don’t specify a vol-
ume size, the default is the snapshot size.
• SnapshotId (string) – The snapshot from which to create the volume.
• AvailabilityZone (string) – [REQUIRED]
The Availability Zone in which to create the volume. Use DescribeAvailability-
Zones to list the Availability Zones that are currently available to you.
• VolumeType (string) – The volume type. This can be gp2 for General Purpose
(SSD) volumes, io1 for Provisioned IOPS (SSD) volumes, or standard for
Magnetic volumes.
Default: standard
• Iops (integer) – Only valid for Provisioned IOPS (SSD) volumes. The number of
I/O operations per second (IOPS) to provision for the volume, with a maximum
ratio of 30 IOPS/GiB.
Constraint: Range is 100 to 20000 for Provisioned IOPS (SSD) volumes
• Encrypted (boolean) – Specifies whether the volume should be encrypted. En-
crypted Amazon EBS volumes may only be attached to instances that support
Amazon EBS encryption. Volumes that are created from encrypted snapshots
are automatically encrypted. There is no way to create an encrypted volume
from an unencrypted snapshot or vice versa. If your AMI uses encrypted vol-
umes, you can only launch it on supported instance types. For more information,
see Amazon EBS Encryption in the Amazon Elastic Compute Cloud User Guide
.
• KmsKeyId (string) – The full ARN of the AWS Key Management Service (AWS
KMS) customer master key (CMK) to use when creating the encrypted volume.
This parameter is only required if you want to use a non-default CMK; if this
parameter is not specified, the default CMK for EBS is used. The ARN contains
the arn:aws:kms namespace, followed by the region of the CMK, the AWS
account ID of the CMK owner, the key namespace, and then the CMK ID.
For example, arn:aws:kms:us-east-1 :012345678910 :key/abcd1234-a123-456a-
a12b-a123b4cd56ef . If a KmsKeyId is specified, the Encrypted flag must
also be set.
Return type dict
Returns
Response Syntax
{
'VolumeId': 'string',
'Size': 123,
'SnapshotId': 'string',
'AvailabilityZone': 'string',
'State': 'creating'|'available'|'in-use'|'deleting'|'deleted'|'error',
'CreateTime': datetime(2015, 1, 1),
'Attachments': [
1170 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'VolumeId': 'string',
'InstanceId': 'string',
'Device': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False,
'KmsKeyId': 'string'
}
Response Structure
• (dict) –
Information about the volume.
– VolumeId (string) –
The ID of the volume.
– Size (integer) –
The size of the volume, in GiBs.
– SnapshotId (string) –
The snapshot from which the volume was created, if applicable.
– AvailabilityZone (string) –
The Availability Zone for the volume.
– State (string) –
The volume state.
– CreateTime (datetime) –
The time stamp when volume creation was initiated.
– Attachments (list) –
Information about the volume attachments.
* (dict) –
Describes volume attachment details.
· VolumeId (string) –
The ID of the volume.
· InstanceId (string) –
The ID of the instance.
· Device (string) –
The device name.
· State (string) –
The attachment state of the volume.
3.1. Services 1171
Boto3 Documentation, Release 1.1.4
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
– Tags (list) –
Any tags assigned to the volume.
* (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
– VolumeType (string) –
The volume type. This can be gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, or standard for Magnetic
volumes.
– Iops (integer) –
The number of I/O operations per second (IOPS) that the volume sup-
ports. For Provisioned IOPS (SSD) volumes, this represents the number
of IOPS that are provisioned for the volume. For General Purpose (SSD)
volumes, this represents the baseline performance of the volume and the
rate at which the volume accumulates I/O credits for bursting. For more
information on General Purpose (SSD) baseline performance, I/O cred-
its, and bursting, see Amazon EBS Volume Types in the Amazon Elastic
Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS (SSD) volumes
and 3 to 10000 for General Purpose (SSD) volumes.
Condition: This parameter is required for requests to create io1 volumes;
it is not used in requests to create standard or gp2 volumes.
– Encrypted (boolean) –
Indicates whether the volume will be encrypted.
– KmsKeyId (string) –
The full ARN of the AWS Key Management Service (AWS KMS) cus-
tomer master key (CMK) that was used to protect the volume encryption
key for the volume.
create_vpc(**kwargs)
Creates a VPC with the specified CIDR block.
The smallest VPC you can create uses a /28 netmask (16 IP addresses), and the largest uses a /16 netmask
(65,536 IP addresses). To help you decide how big to make your VPC, see Your VPC and Subnets in the
Amazon Virtual Private Cloud User Guide .
1172 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
By default, each instance you launch in the VPC has the default DHCP options, which includes only a
default DNS server that we provide (AmazonProvidedDNS). For more information about DHCP options,
see DHCP Options Sets in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.create_vpc(
DryRun=True|False,
CidrBlock='string',
InstanceTenancy='default'|'dedicated'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• CidrBlock (string) – [REQUIRED]
The network range for the VPC, in CIDR notation. For example,
10.0.0.0/16 .
• InstanceTenancy (string) – The supported tenancy options for instances
launched into the VPC. A value of default means that instances can be
launched with any tenancy; a value of dedicated means all instances launched
into the VPC are launched as dedicated tenancy instances regardless of the ten-
ancy assigned to the instance at launch. Dedicated tenancy instances run on
single-tenant hardware.
Default: default
Return type dict
Returns
Response Syntax
{
'Vpc': {
'VpcId': 'string',
'State': 'pending'|'available',
'CidrBlock': 'string',
'DhcpOptionsId': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'InstanceTenancy': 'default'|'dedicated',
'IsDefault': True|False
}
}
Response Structure
• (dict) –
– Vpc (dict) –
Information about the VPC.
* VpcId (string) –
The ID of the VPC.
3.1. Services 1173
Boto3 Documentation, Release 1.1.4
* State (string) –
The current state of the VPC.
* CidrBlock (string) –
The CIDR block for the VPC.
* DhcpOptionsId (string) –
The ID of the set of DHCP options you’ve associated with the VPC
(or default if the default options are associated with the VPC).
* Tags (list) –
Any tags assigned to the VPC.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
* InstanceTenancy (string) –
The allowed tenancy of instances launched into the VPC.
* IsDefault (boolean) –
Indicates whether the VPC is the default VPC.
create_vpc_endpoint(**kwargs)
Creates a VPC endpoint for a specified AWS service. An endpoint enables you to create a private connec-
tion between your VPC and another AWS service in your account. You can specify an endpoint policy
to attach to the endpoint that will control access to the service from your VPC. You can also specify the
VPC route tables that use the endpoint.
Currently, only endpoints to Amazon S3 are supported.
Request Syntax
response = client.create_vpc_endpoint(
DryRun=True|False,
VpcId='string',
ServiceName='string',
PolicyDocument='string',
RouteTableIds=[
'string',
],
ClientToken='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
1174 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• VpcId (string) – [REQUIRED]
The ID of the VPC in which the endpoint will be used.
• ServiceName (string) – [REQUIRED]
The AWS service name, in the form com.amazonaws.*region*
.*service* . To get a list of available services, use the DescribeVpcEnd-
pointServices request.
• PolicyDocument (string) – A policy to attach to the endpoint that controls access
to the service. The policy must be in valid JSON format. If this parameter is not
specified, we attach a default policy that allows full access to the service.
• RouteTableIds (list) – One or more route table IDs.
– (string) –
• ClientToken (string) – Unique, case-sensitive identifier you provide to ensure
the idempotency of the request. For more information, see How to Ensure Idem-
potency .
Return type dict
Returns
Response Syntax
{
'VpcEndpoint': {
'VpcEndpointId': 'string',
'VpcId': 'string',
'ServiceName': 'string',
'State': 'Pending'|'Available'|'Deleting'|'Deleted',
'PolicyDocument': 'string',
'RouteTableIds': [
'string',
],
'CreationTimestamp': datetime(2015, 1, 1)
},
'ClientToken': 'string'
}
Response Structure
• (dict) –
– VpcEndpoint (dict) –
Information about the endpoint.
* VpcEndpointId (string) –
The ID of the VPC endpoint.
* VpcId (string) –
The ID of the VPC to which the endpoint is associated.
* ServiceName (string) –
The name of the AWS service to which the endpoint is associated.
* State (string) –
The state of the VPC endpoint.
* PolicyDocument (string) –
The policy document associated with the endpoint.
* RouteTableIds (list) –
One or more route tables associated with the endpoint.
· (string) –
3.1. Services 1175
Boto3 Documentation, Release 1.1.4
* CreationTimestamp (datetime) –
The date and time the VPC endpoint was created.
– ClientToken (string) –
Unique, case-sensitive identifier you provide to ensure the idempotency of
the request.
create_vpc_peering_connection(**kwargs)
Requests a VPC peering connection between two VPCs: a requester VPC that you own and a peer VPC
with which to create the connection. The peer VPC can belong to another AWS account. The requester
VPC and peer VPC cannot have overlapping CIDR blocks.
The owner of the peer VPC must accept the peering request to activate the peering connection. The VPC
peering connection request expires after 7 days, after which it cannot be accepted or rejected.
A CreateVpcPeeringConnection request between VPCs with overlapping CIDR blocks results in
the VPC peering connection having a status of failed .
Request Syntax
response = client.create_vpc_peering_connection(
DryRun=True|False,
VpcId='string',
PeerVpcId='string',
PeerOwnerId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – The ID of the requester VPC.
• PeerVpcId (string) – The ID of the VPC with which you are creating the VPC
peering connection.
• PeerOwnerId (string) – The AWS account ID of the owner of the peer VPC.
Default: Your AWS account ID
Return type dict
Returns
Response Syntax
{
'VpcPeeringConnection': {
'AccepterVpcInfo': {
'CidrBlock': 'string',
'OwnerId': 'string',
'VpcId': 'string'
},
'ExpirationTime': datetime(2015, 1, 1),
'RequesterVpcInfo': {
'CidrBlock': 'string',
'OwnerId': 'string',
'VpcId': 'string'
},
'Status': {
'Code': 'initiating-request'|'pending-acceptance'|'active'|'deleted'|'
1176 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Message': 'string'
},
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VpcPeeringConnectionId': 'string'
}
}
Response Structure
• (dict) –
– VpcPeeringConnection (dict) –
Information about the VPC peering connection.
* AccepterVpcInfo (dict) –
The information of the peer VPC.
· CidrBlock (string) –
The CIDR block for the VPC.
· OwnerId (string) –
The AWS account ID of the VPC owner.
· VpcId (string) –
The ID of the VPC.
* ExpirationTime (datetime) –
The time that an unaccepted VPC peering connection will expire.
* RequesterVpcInfo (dict) –
The information of the requester VPC.
· CidrBlock (string) –
The CIDR block for the VPC.
· OwnerId (string) –
The AWS account ID of the VPC owner.
· VpcId (string) –
The ID of the VPC.
* Status (dict) –
The status of the VPC peering connection.
· Code (string) –
The status of the VPC peering connection.
· Message (string) –
A message that provides more information about the status, if
applicable.
* Tags (list) –
Any tags assigned to the resource.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
3.1. Services 1177
Boto3 Documentation, Release 1.1.4
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
* VpcPeeringConnectionId (string) –
The ID of the VPC peering connection.
create_vpn_connection(**kwargs)
Creates a VPN connection between an existing virtual private gateway and a VPN customer gateway. The
only supported connection type is ipsec.1 .
The response includes information that you need to give to your network administrator to configure your
customer gateway.
Warning: We strongly recommend that you use HTTPS when calling this operation because the
response contains sensitive cryptographic information for configuring your customer gateway.
If you decide to shut down your VPN connection for any reason and later create a new VPN connection,
you must reconfigure your customer gateway with the new information returned from this call.
For more information about VPN connections, see Adding a Hardware Virtual Private Gateway to Your
VPC in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.create_vpn_connection(
DryRun=True|False,
Type='string',
CustomerGatewayId='string',
VpnGatewayId='string',
Options={
'StaticRoutesOnly': True|False
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Type (string) – [REQUIRED]
The type of VPN connection (ipsec.1 ).
• CustomerGatewayId (string) – [REQUIRED]
The ID of the customer gateway.
• VpnGatewayId (string) – [REQUIRED]
The ID of the virtual private gateway.
• Options (dict) – Indicates whether the VPN connection requires static routes. If
you are creating a VPN connection for a device that does not support BGP, you
must specify true .
Default: false
1178 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– StaticRoutesOnly (boolean) –
Indicates whether the VPN connection uses static routes only. Static routes
must be used for devices that don’t support BGP.
Return type dict
Returns
Response Syntax
{
'VpnConnection': {
'VpnConnectionId': 'string',
'State': 'pending'|'available'|'deleting'|'deleted',
'CustomerGatewayConfiguration': 'string',
'Type': 'ipsec.1',
'CustomerGatewayId': 'string',
'VpnGatewayId': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VgwTelemetry': [
{
'OutsideIpAddress': 'string',
'Status': 'UP'|'DOWN',
'LastStatusChange': datetime(2015, 1, 1),
'StatusMessage': 'string',
'AcceptedRouteCount': 123
},
],
'Options': {
'StaticRoutesOnly': True|False
},
'Routes': [
{
'DestinationCidrBlock': 'string',
'Source': 'Static',
'State': 'pending'|'available'|'deleting'|'deleted'
},
]
}
}
Response Structure
• (dict) –
– VpnConnection (dict) –
Information about the VPN connection.
* VpnConnectionId (string) –
The ID of the VPN connection.
* State (string) –
The current state of the VPN connection.
* CustomerGatewayConfiguration (string) –
The configuration information for the VPN connection’s customer
gateway (in the native XML format). This element is always present
3.1. Services 1179
Boto3 Documentation, Release 1.1.4
in the CreateVpnConnection response; however, it’s present in the
DescribeVpnConnections response only if the VPN connection is in
the pending or available state.
* Type (string) –
The type of VPN connection.
* CustomerGatewayId (string) –
The ID of the customer gateway at your end of the VPN connection.
* VpnGatewayId (string) –
The ID of the virtual private gateway at the AWS side of the VPN
connection.
* Tags (list) –
Any tags assigned to the VPN connection.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
* VgwTelemetry (list) –
Information about the VPN tunnel.
· (dict) –
Describes telemetry for a VPN tunnel.
· OutsideIpAddress (string) –
The Internet-routable IP address of the virtual private gate-
way’s outside interface.
· Status (string) –
The status of the VPN tunnel.
· LastStatusChange (datetime) –
The date and time of the last change in status.
· StatusMessage (string) –
If an error occurs, a description of the error.
· AcceptedRouteCount (integer) –
The number of accepted routes.
* Options (dict) –
The VPN connection options.
· StaticRoutesOnly (boolean) –
Indicates whether the VPN connection uses static routes only.
Static routes must be used for devices that don’t support BGP.
* Routes (list) –
The static routes associated with the VPN connection.
1180 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes a static route for a VPN connection.
· DestinationCidrBlock (string) –
The CIDR block associated with the local subnet of the cus-
tomer data center.
· Source (string) –
Indicates how the routes were provided.
· State (string) –
The current state of the static route.
create_vpn_connection_route(**kwargs)
Creates a static route associated with a VPN connection between an existing virtual private gateway and
a VPN customer gateway. The static route allows traffic to be routed from the virtual private gateway to
the VPN customer gateway.
For more information about VPN connections, see Adding a Hardware Virtual Private Gateway to Your
VPC in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.create_vpn_connection_route(
VpnConnectionId='string',
DestinationCidrBlock='string'
)
Parameters
• VpnConnectionId (string) – [REQUIRED]
The ID of the VPN connection.
• DestinationCidrBlock (string) – [REQUIRED]
The CIDR block associated with the local subnet of the customer network.
Returns None
create_vpn_gateway(**kwargs)
Creates a virtual private gateway. A virtual private gateway is the endpoint on the VPC side of your VPN
connection. You can create a virtual private gateway before creating the VPC itself.
For more information about virtual private gateways, see Adding a Hardware Virtual Private Gateway to
Your VPC in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.create_vpn_gateway(
DryRun=True|False,
Type='ipsec.1',
AvailabilityZone='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Type (string) – [REQUIRED]
The type of VPN connection this virtual private gateway supports.
3.1. Services 1181
Boto3 Documentation, Release 1.1.4
• AvailabilityZone (string) – The Availability Zone for the virtual private gateway.
Return type dict
Returns
Response Syntax
{
'VpnGateway': {
'VpnGatewayId': 'string',
'State': 'pending'|'available'|'deleting'|'deleted',
'Type': 'ipsec.1',
'AvailabilityZone': 'string',
'VpcAttachments': [
{
'VpcId': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached'
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
– VpnGateway (dict) –
Information about the virtual private gateway.
* VpnGatewayId (string) –
The ID of the virtual private gateway.
* State (string) –
The current state of the virtual private gateway.
* Type (string) –
The type of VPN connection the virtual private gateway supports.
* AvailabilityZone (string) –
The Availability Zone where the virtual private gateway was cre-
ated.
* VpcAttachments (list) –
Any VPCs attached to the virtual private gateway.
· (dict) –
Describes an attachment between a virtual private gateway
and a VPC.
· VpcId (string) –
The ID of the VPC.
· State (string) –
The current state of the attachment.
* Tags (list) –
Any tags assigned to the virtual private gateway.
1182 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
delete_customer_gateway(**kwargs)
Deletes the specified customer gateway. You must delete the VPN connection before you can delete the
customer gateway.
Request Syntax
response = client.delete_customer_gateway(
DryRun=True|False,
CustomerGatewayId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• CustomerGatewayId (string) – [REQUIRED]
The ID of the customer gateway.
Returns None
delete_dhcp_options(**kwargs)
Deletes the specified set of DHCP options. You must disassociate the set of DHCP options before you
can delete it. You can disassociate the set of DHCP options by associating either a new set of options or
the default set of options with the VPC.
Request Syntax
response = client.delete_dhcp_options(
DryRun=True|False,
DhcpOptionsId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• DhcpOptionsId (string) – [REQUIRED]
The ID of the DHCP options set.
Returns None
3.1. Services 1183
Boto3 Documentation, Release 1.1.4
delete_flow_logs(**kwargs)
Deletes one or more flow logs.
Request Syntax
response = client.delete_flow_logs(
FlowLogIds=[
'string',
]
)
Parameters FlowLogIds (list) – [REQUIRED]
One or more flow log IDs.
• (string) –
Return type dict
Returns
Response Syntax
{
'Unsuccessful': [
{
'ResourceId': 'string',
'Error': {
'Code': 'string',
'Message': 'string'
}
},
]
}
Response Structure
• (dict) –
– Unsuccessful (list) –
Information about the flow logs that could not be deleted successfully.
* (dict) –
Information about items that were not successfully processed in a
batch call.
· ResourceId (string) –
The ID of the resource.
· Error (dict) –
Information about the error.
· Code (string) –
The error code.
· Message (string) –
The error message accompanying the error code.
delete_internet_gateway(**kwargs)
Deletes the specified Internet gateway. You must detach the Internet gateway from the VPC before you
can delete it.
Request Syntax
1184 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.delete_internet_gateway(
DryRun=True|False,
InternetGatewayId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InternetGatewayId (string) – [REQUIRED]
The ID of the Internet gateway.
Returns None
delete_key_pair(**kwargs)
Deletes the specified key pair, by removing the public key from Amazon EC2.
Request Syntax
response = client.delete_key_pair(
DryRun=True|False,
KeyName='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• KeyName (string) – [REQUIRED]
The name of the key pair.
Returns None
delete_network_acl(**kwargs)
Deletes the specified network ACL. You can’t delete the ACL if it’s associated with any subnets. You
can’t delete the default network ACL.
Request Syntax
response = client.delete_network_acl(
DryRun=True|False,
NetworkAclId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkAclId (string) – [REQUIRED]
The ID of the network ACL.
Returns None
delete_network_acl_entry(**kwargs)
Deletes the specified ingress or egress entry (rule) from the specified network ACL.
3.1. Services 1185
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.delete_network_acl_entry(
DryRun=True|False,
NetworkAclId='string',
RuleNumber=123,
Egress=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkAclId (string) – [REQUIRED]
The ID of the network ACL.
• RuleNumber (integer) – [REQUIRED]
The rule number of the entry to delete.
• Egress (boolean) – [REQUIRED]
Indicates whether the rule is an egress rule.
Returns None
delete_network_interface(**kwargs)
Deletes the specified network interface. You must detach the network interface before you can delete it.
Request Syntax
response = client.delete_network_interface(
DryRun=True|False,
NetworkInterfaceId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkInterfaceId (string) – [REQUIRED]
The ID of the network interface.
Returns None
delete_placement_group(**kwargs)
Deletes the specified placement group. You must terminate all instances in the placement group before
you can delete the placement group. For more information about placement groups and cluster instances,
see Cluster Instances in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.delete_placement_group(
DryRun=True|False,
GroupName='string'
)
Parameters
1186 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupName (string) – [REQUIRED]
The name of the placement group.
Returns None
delete_route(**kwargs)
Deletes the specified route from the specified route table.
Request Syntax
response = client.delete_route(
DryRun=True|False,
RouteTableId='string',
DestinationCidrBlock='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• RouteTableId (string) – [REQUIRED]
The ID of the route table.
• DestinationCidrBlock (string) – [REQUIRED]
The CIDR range for the route. The value you specify must match the CIDR for
the route exactly.
Returns None
delete_route_table(**kwargs)
Deletes the specified route table. You must disassociate the route table from any subnets before you can
delete it. You can’t delete the main route table.
Request Syntax
response = client.delete_route_table(
DryRun=True|False,
RouteTableId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• RouteTableId (string) – [REQUIRED]
The ID of the route table.
Returns None
delete_security_group(**kwargs)
Deletes a security group.
3.1. Services 1187
Boto3 Documentation, Release 1.1.4
If you attempt to delete a security group that is associated with an instance, or is referenced
by another security group, the operation fails with InvalidGroup.InUse in EC2-Classic or
DependencyViolation in EC2-VPC.
Request Syntax
response = client.delete_security_group(
DryRun=True|False,
GroupName='string',
GroupId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupName (string) – [EC2-Classic, default VPC] The name of the security
group. You can specify either the security group name or the security group ID.
• GroupId (string) – The ID of the security group. Required for a nondefault
VPC.
Returns None
delete_snapshot(**kwargs)
Deletes the specified snapshot.
When you make periodic snapshots of a volume, the snapshots are incremental, and only the blocks on
the device that have changed since your last snapshot are saved in the new snapshot. When you delete
a snapshot, only the data not needed for any other snapshot is removed. So regardless of which prior
snapshots have been deleted, all active snapshots will have access to all the information needed to restore
the volume.
You cannot delete a snapshot of the root device of an EBS volume used by a registered AMI. You must
first de-register the AMI before you can delete the snapshot.
For more information, see Deleting an Amazon EBS Snapshot in the Amazon Elastic Compute Cloud
User Guide .
Request Syntax
response = client.delete_snapshot(
DryRun=True|False,
SnapshotId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SnapshotId (string) – [REQUIRED]
The ID of the EBS snapshot.
Returns None
delete_spot_datafeed_subscription(**kwargs)
Deletes the data feed for Spot instances.
Request Syntax
1188 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.delete_spot_datafeed_subscription(
DryRun=True|False
)
Parameters DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If you have
the required permissions, the error response is DryRunOperation . Otherwise, it is
UnauthorizedOperation .
Returns None
delete_subnet(**kwargs)
Deletes the specified subnet. You must terminate all running instances in the subnet before you can delete
the subnet.
Request Syntax
response = client.delete_subnet(
DryRun=True|False,
SubnetId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SubnetId (string) – [REQUIRED]
The ID of the subnet.
Returns None
delete_tags(**kwargs)
Deletes the specified set of tags from the specified set of resources. This call is designed to follow a
DescribeTags request.
For more information about tags, see Tagging Your Resources in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
response = client.delete_tags(
DryRun=True|False,
Resources=[
'string',
],
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
3.1. Services 1189
Boto3 Documentation, Release 1.1.4
• Resources (list) – [REQUIRED]
The ID of the resource. For example, ami-1a2b3c4d. You can specify more than
one resource ID.
– (string) –
• Tags (list) – One or more tags to delete. If you omit the value parameter, we
delete the tag regardless of its value. If you specify this parameter with an empty
string as the value, we delete the key only if its value is an empty string.
– (dict) –
Describes a tag.
* Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maximum of
127 Unicode characters. May not begin with aws:
* Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maximum of
255 Unicode characters.
Returns None
delete_volume(**kwargs)
Deletes the specified EBS volume. The volume must be in the available state (not attached to an
instance).
Note: The volume may remain in the deleting state for several minutes.
For more information, see Deleting an Amazon EBS Volume in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
response = client.delete_volume(
DryRun=True|False,
VolumeId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeId (string) – [REQUIRED]
The ID of the volume.
Returns None
delete_vpc(**kwargs)
Deletes the specified VPC. You must detach or delete all gateways and resources that are associated with
the VPC before you can delete it. For example, you must terminate all instances running in the VPC, delete
all security groups associated with the VPC (except the default one), delete all route tables associated with
the VPC (except the default one), and so on.
Request Syntax
1190 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.delete_vpc(
DryRun=True|False,
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Returns None
delete_vpc_endpoints(**kwargs)
Deletes one or more specified VPC endpoints. Deleting the endpoint also deletes the endpoint routes in
the route tables that were associated with the endpoint.
Request Syntax
response = client.delete_vpc_endpoints(
DryRun=True|False,
VpcEndpointIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcEndpointIds (list) – [REQUIRED]
One or more endpoint IDs.
– (string) –
Return type dict
Returns
Response Syntax
{
'Unsuccessful': [
{
'ResourceId': 'string',
'Error': {
'Code': 'string',
'Message': 'string'
}
},
]
}
Response Structure
• (dict) –
3.1. Services 1191
Boto3 Documentation, Release 1.1.4
– Unsuccessful (list) –
Information about the endpoints that were not successfully deleted.
* (dict) –
Information about items that were not successfully processed in a
batch call.
· ResourceId (string) –
The ID of the resource.
· Error (dict) –
Information about the error.
· Code (string) –
The error code.
· Message (string) –
The error message accompanying the error code.
delete_vpc_peering_connection(**kwargs)
Deletes a VPC peering connection. Either the owner of the requester VPC or the owner of the peer VPC
can delete the VPC peering connection if it’s in the active state. The owner of the requester VPC can
delete a VPC peering connection in the pending-acceptance state.
Request Syntax
response = client.delete_vpc_peering_connection(
DryRun=True|False,
VpcPeeringConnectionId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcPeeringConnectionId (string) – [REQUIRED]
The ID of the VPC peering connection.
Return type dict
Returns
Response Syntax
{
'Return': True|False
}
Response Structure
• (dict) –
– Return (boolean) –
Returns true if the request succeeds; otherwise, it returns an error.
delete_vpn_connection(**kwargs)
Deletes the specified VPN connection.
If you’re deleting the VPC and its associated components, we recommend that you detach the virtual
private gateway from the VPC and delete the VPC before deleting the VPN connection. If you believe
that the tunnel credentials for your VPN connection have been compromised, you can delete the VPN
1192 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
connection and create a new one that has new keys, without needing to delete the VPC or virtual private
gateway. If you create a new VPN connection, you must reconfigure the customer gateway using the new
configuration information returned with the new VPN connection ID.
Request Syntax
response = client.delete_vpn_connection(
DryRun=True|False,
VpnConnectionId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpnConnectionId (string) – [REQUIRED]
The ID of the VPN connection.
Returns None
delete_vpn_connection_route(**kwargs)
Deletes the specified static route associated with a VPN connection between an existing virtual private
gateway and a VPN customer gateway. The static route allows traffic to be routed from the virtual private
gateway to the VPN customer gateway.
Request Syntax
response = client.delete_vpn_connection_route(
VpnConnectionId='string',
DestinationCidrBlock='string'
)
Parameters
• VpnConnectionId (string) – [REQUIRED]
The ID of the VPN connection.
• DestinationCidrBlock (string) – [REQUIRED]
The CIDR block associated with the local subnet of the customer network.
Returns None
delete_vpn_gateway(**kwargs)
Deletes the specified virtual private gateway. We recommend that before you delete a virtual private
gateway, you detach it from the VPC and delete the VPN connection. Note that you don’t need to delete
the virtual private gateway if you plan to delete and recreate the VPN connection between your VPC and
your network.
Request Syntax
response = client.delete_vpn_gateway(
DryRun=True|False,
VpnGatewayId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
3.1. Services 1193
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpnGatewayId (string) – [REQUIRED]
The ID of the virtual private gateway.
Returns None
deregister_image(**kwargs)
Deregisters the specified AMI. After you deregister an AMI, it can’t be used to launch new instances.
This command does not delete the AMI.
Request Syntax
response = client.deregister_image(
DryRun=True|False,
ImageId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageId (string) – [REQUIRED]
The ID of the AMI.
Returns None
describe_account_attributes(**kwargs)
Describes attributes of your AWS account. The following are the supported account attributes:
•supported-platforms : Indicates whether your account can launch instances into EC2-
Classic and EC2-VPC, or only into EC2-VPC.
•default-vpc : The ID of the default VPC for your account, or none .
•max-instances : The maximum number of On-Demand instances that you can run.
•vpc-max-security-groups-per-interface : The maximum number of security groups
that you can assign to a network interface.
•max-elastic-ips : The maximum number of Elastic IP addresses that you can allocate for use
with EC2-Classic.
•vpc-max-elastic-ips : The maximum number of Elastic IP addresses that you can allocate
for use with EC2-VPC.
Request Syntax
response = client.describe_account_attributes(
DryRun=True|False,
AttributeNames=[
'supported-platforms'|'default-vpc',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• AttributeNames (list) – One or more account attribute names.
– (string) –
Return type dict
1194 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'AccountAttributes': [
{
'AttributeName': 'string',
'AttributeValues': [
{
'AttributeValue': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– AccountAttributes (list) –
Information about one or more account attributes.
* (dict) –
Describes an account attribute.
· AttributeName (string) –
The name of the account attribute.
· AttributeValues (list) –
One or more values for the account attribute.
· (dict) –
Describes a value of an account attribute.
· AttributeValue (string) –
The value of the attribute.
describe_addresses(**kwargs)
Describes one or more of your Elastic IP addresses.
An Elastic IP address is for use in either the EC2-Classic platform or in a VPC. For more information, see
Elastic IP Addresses in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.describe_addresses(
DryRun=True|False,
PublicIps=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
AllocationIds=[
'string',
3.1. Services 1195
Boto3 Documentation, Release 1.1.4
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• PublicIps (list) – [EC2-Classic] One or more Elastic IP addresses.
Default: Describes all your Elastic IP addresses.
– (string) –
• Filters (list) – One or more filters. Filter names and values are case-sensitive.
– allocation-id - [EC2-VPC] The allocation ID for the address.
– association-id - [EC2-VPC] The association ID for the address.
– domain - Indicates whether the address is for use in EC2-Classic
(standard ) or in a VPC (vpc ).
– instance-id - The ID of the instance the address is associated with, if
any.
– network-interface-id - [EC2-VPC] The ID of the network inter-
face that the address is associated with, if any.
– network-interface-owner-id - The AWS account ID of the
owner.
– private-ip-address - [EC2-VPC] The private IP address associated
with the Elastic IP address.
– public-ip - The Elastic IP address.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• AllocationIds (list) – [EC2-VPC] One or more allocation IDs.
Default: Describes all your Elastic IP addresses.
– (string) –
Return type dict
Returns
Response Syntax
{
'Addresses': [
{
'InstanceId': 'string',
'PublicIp': 'string',
'AllocationId': 'string',
'AssociationId': 'string',
'Domain': 'vpc'|'standard',
'NetworkInterfaceId': 'string',
'NetworkInterfaceOwnerId': 'string',
1196 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'PrivateIpAddress': 'string'
},
]
}
Response Structure
• (dict) –
– Addresses (list) –
Information about one or more Elastic IP addresses.
* (dict) –
Describes an Elastic IP address.
· InstanceId (string) –
The ID of the instance that the address is associated with (if
any).
· PublicIp (string) –
The Elastic IP address.
· AllocationId (string) –
The ID representing the allocation of the address for use with
EC2-VPC.
· AssociationId (string) –
The ID representing the association of the address with an
instance in a VPC.
· Domain (string) –
Indicates whether this Elastic IP address is for use with in-
stances in EC2-Classic (standard ) or instances in a VPC
(vpc ).
· NetworkInterfaceId (string) –
The ID of the network interface.
· NetworkInterfaceOwnerId (string) –
The ID of the AWS account that owns the network interface.
· PrivateIpAddress (string) –
The private IP address associated with the Elastic IP address.
describe_availability_zones(**kwargs)
Describes one or more of the Availability Zones that are available to you. The results include zones only
for the region you’re currently using. If there is an event impacting an Availability Zone, you can use this
request to view the state and any provided message for that Availability Zone.
For more information, see Regions and Availability Zones in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
response = client.describe_availability_zones(
DryRun=True|False,
ZoneNames=[
'string',
],
Filters=[
{
'Name': 'string',
3.1. Services 1197
Boto3 Documentation, Release 1.1.4
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ZoneNames (list) – The names of one or more Availability Zones.
– (string) –
• Filters (list) – One or more filters.
– message - Information about the Availability Zone.
– region-name - The name of the region for the Availability Zone (for
example, us-east-1 ).
– state - The state of the Availability Zone (available | impaired |
unavailable ).
– zone-name - The name of the Availability Zone (for example,
us-east-1a ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'AvailabilityZones': [
{
'ZoneName': 'string',
'State': 'available',
'RegionName': 'string',
'Messages': [
{
'Message': 'string'
},
]
},
]
}
Response Structure
• (dict) –
1198 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– AvailabilityZones (list) –
Information about one or more Availability Zones.
* (dict) –
Describes an Availability Zone.
· ZoneName (string) –
The name of the Availability Zone.
· State (string) –
The state of the Availability Zone (available | impaired
| unavailable ).
· RegionName (string) –
The name of the region.
· Messages (list) –
Any messages about the Availability Zone.
· (dict) –
Describes a message about an Availability Zone.
· Message (string) –
The message about the Availability Zone.
describe_bundle_tasks(**kwargs)
Describes one or more of your bundling tasks.
Note: Completed bundle tasks are listed for only a limited time. If your bundle task is no longer in the
list, you can still register an AMI from it. Just use RegisterImage with the Amazon S3 bucket name
and image manifest name you provided to the bundle task.
Request Syntax
response = client.describe_bundle_tasks(
DryRun=True|False,
BundleIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• BundleIds (list) – One or more bundle task IDs.
Default: Describes all your bundle tasks.
– (string) –
• Filters (list) – One or more filters.
3.1. Services 1199
Boto3 Documentation, Release 1.1.4
– bundle-id - The ID of the bundle task.
– error-code - If the task failed, the error code returned.
– error-message - If the task failed, the error message returned.
– instance-id - The ID of the instance.
– progress - The level of task completion, as a percentage (for example,
20%).
– s3-bucket - The Amazon S3 bucket to store the AMI.
– s3-prefix - The beginning of the AMI name.
– start-time - The time the task started (for example, 2013-09-
15T17:15:20.000Z).
– state - The state of the task (pending | waiting-for-shutdown
| bundling | storing | cancelling | complete | failed ).
– update-time - The time of the most recent update for the task.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'BundleTasks': [
{
'InstanceId': 'string',
'BundleId': 'string',
'State': 'pending'|'waiting-for-shutdown'|'bundling'|'storing'|'cancel
'StartTime': datetime(2015, 1, 1),
'UpdateTime': datetime(2015, 1, 1),
'Storage': {
'S3': {
'Bucket': 'string',
'Prefix': 'string',
'AWSAccessKeyId': 'string',
'UploadPolicy': b'bytes',
'UploadPolicySignature': 'string'
}
},
'Progress': 'string',
'BundleTaskError': {
'Code': 'string',
'Message': 'string'
}
},
]
}
Response Structure
• (dict) –
1200 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– BundleTasks (list) –
Information about one or more bundle tasks.
* (dict) –
Describes a bundle task.
· InstanceId (string) –
The ID of the instance associated with this bundle task.
· BundleId (string) –
The ID of the bundle task.
· State (string) –
The state of the task.
· StartTime (datetime) –
The time this task started.
· UpdateTime (datetime) –
The time of the most recent update for the task.
· Storage (dict) –
The Amazon S3 storage locations.
· S3 (dict) –
An Amazon S3 storage location.
· Bucket (string) –
The bucket in which to store the AMI. You can specify a
bucket that you already own or a new bucket that Amazon
EC2 creates on your behalf. If you specify a bucket that be-
longs to someone else, Amazon EC2 returns an error.
· Prefix (string) –
The beginning of the file name of the AMI.
· AWSAccessKeyId (string) –
The access key ID of the owner of the bucket. Before you
specify a value for your access key ID, review and follow the
guidance in Best Practices for Managing AWS Access Keys .
· UploadPolicy (bytes) –
A Base64-encoded Amazon S3 upload policy that gives Ama-
zon EC2 permission to upload items into Amazon S3 on your
behalf.
· UploadPolicySignature (string) –
The signature of the Base64 encoded JSON document.
· Progress (string) –
The level of task completion, as a percent (for example, 20%).
· BundleTaskError (dict) –
If the task fails, a description of the error.
· Code (string) –
The error code.
· Message (string) –
The error message.
3.1. Services 1201
Boto3 Documentation, Release 1.1.4
describe_classic_link_instances(**kwargs)
Describes one or more of your linked EC2-Classic instances. This request only returns information about
EC2-Classic instances linked to a VPC through ClassicLink; you cannot use this request to return infor-
mation about other instances.
Request Syntax
response = client.describe_classic_link_instances(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs. Must be instances linked to a
VPC through ClassicLink.
– (string) –
• Filters (list) – One or more filters.
– group-id - The ID of a VPC security group that’s associated with the
instance.
– instance-id - The ID of the instance.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-id - The ID of the VPC that the instance is linked to.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
1202 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to retrieve the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
IDs parameter in the same request.
Constraint: If the value is greater than 1000, we return only 1000 items.
Return type dict
Returns
Response Syntax
{
'Instances': [
{
'InstanceId': 'string',
'VpcId': 'string',
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– Instances (list) –
Information about one or more linked EC2-Classic instances.
* (dict) –
Describes a linked EC2-Classic instance.
· InstanceId (string) –
The ID of the instance.
· VpcId (string) –
The ID of the VPC.
· Groups (list) –
A list of security groups.
· (dict) –
Describes a security group.
· GroupName (string) –
3.1. Services 1203
Boto3 Documentation, Release 1.1.4
The name of the security group.
· GroupId (string) –
The ID of the security group.
· Tags (list) –
Any tags assigned to the instance.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return.
describe_conversion_tasks(**kwargs)
Describes one or more of your conversion tasks. For more information, see Using the Command Line
Tools to Import Your Virtual Machine to Amazon EC2 in the Amazon Elastic Compute Cloud User Guide
.
Request Syntax
response = client.describe_conversion_tasks(
DryRun=True|False,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
ConversionTaskIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Filters (list) – One or more filters.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
1204 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• ConversionTaskIds (list) – One or more conversion task IDs.
– (string) –
Return type dict
Returns
Response Syntax
{
'ConversionTasks': [
{
'ConversionTaskId': 'string',
'ExpirationTime': 'string',
'ImportInstance': {
'Volumes': [
{
'BytesConverted': 123,
'AvailabilityZone': 'string',
'Image': {
'Format': 'VMDK'|'RAW'|'VHD',
'Size': 123,
'ImportManifestUrl': 'string',
'Checksum': 'string'
},
'Volume': {
'Size': 123,
'Id': 'string'
},
'Status': 'string',
'StatusMessage': 'string',
'Description': 'string'
},
],
'InstanceId': 'string',
'Platform': 'Windows',
'Description': 'string'
},
'ImportVolume': {
'BytesConverted': 123,
'AvailabilityZone': 'string',
'Description': 'string',
'Image': {
'Format': 'VMDK'|'RAW'|'VHD',
'Size': 123,
'ImportManifestUrl': 'string',
'Checksum': 'string'
},
'Volume': {
'Size': 123,
'Id': 'string'
}
},
'State': 'active'|'cancelling'|'cancelled'|'completed',
3.1. Services 1205
Boto3 Documentation, Release 1.1.4
'StatusMessage': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– ConversionTasks (list) –
Information about the conversion tasks.
* (dict) –
Describes a conversion task.
· ConversionTaskId (string) –
The ID of the conversion task.
· ExpirationTime (string) –
The time when the task expires. If the upload isn’t complete
before the expiration time, we automatically cancel the task.
· ImportInstance (dict) –
If the task is for importing an instance, this contains informa-
tion about the import instance task.
· Volumes (list) –
One or more volumes.
· (dict) –
Describes an import volume task.
· BytesConverted (integer) –
The number of bytes converted so far.
· AvailabilityZone (string) –
The Availability Zone where the resulting instance will reside.
· Image (dict) –
The image.
· Format (string) –
The disk image format.
· Size (integer) –
The size of the disk image, in GiB.
· ImportManifestUrl (string) –
A presigned URL for the import manifest stored in Amazon
S3. For information about creating a presigned URL for an
Amazon S3 object, read the “Query String Request Authen-
tication Alternative” section of the Authenticating REST Re-
quests topic in the Amazon Simple Storage Service Developer
Guide .
· Checksum (string) –
1206 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The checksum computed for the disk image.
· Volume (dict) –
The volume.
· Size (integer) –
The size of the volume, in GiB.
· Id (string) –
The volume identifier.
· Status (string) –
The status of the import of this particular disk image.
· StatusMessage (string) –
The status information or errors related to the disk image.
· Description (string) –
A description of the task.
· InstanceId (string) –
The ID of the instance.
· Platform (string) –
The instance operating system.
· Description (string) –
A description of the task.
· ImportVolume (dict) –
If the task is for importing a volume, this contains information
about the import volume task.
· BytesConverted (integer) –
The number of bytes converted so far.
· AvailabilityZone (string) –
The Availability Zone where the resulting volume will reside.
· Description (string) –
The description you provided when starting the import vol-
ume task.
· Image (dict) –
The image.
· Format (string) –
The disk image format.
· Size (integer) –
The size of the disk image, in GiB.
· ImportManifestUrl (string) –
A presigned URL for the import manifest stored in Amazon
S3. For information about creating a presigned URL for an
Amazon S3 object, read the “Query String Request Authen-
tication Alternative” section of the Authenticating REST Re-
quests topic in the Amazon Simple Storage Service Developer
Guide .
· Checksum (string) –
The checksum computed for the disk image.
3.1. Services 1207
Boto3 Documentation, Release 1.1.4
· Volume (dict) –
The volume.
· Size (integer) –
The size of the volume, in GiB.
· Id (string) –
The volume identifier.
· State (string) –
The state of the conversion task.
· StatusMessage (string) –
The status message related to the conversion task.
· Tags (list) –
Any tags assigned to the task.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
describe_customer_gateways(**kwargs)
Describes one or more of your VPN customer gateways.
For more information about VPN customer gateways, see Adding a Hardware Virtual Private Gateway to
Your VPC in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.describe_customer_gateways(
DryRun=True|False,
CustomerGatewayIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
1208 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• CustomerGatewayIds (list) – One or more customer gateway IDs.
Default: Describes all your customer gateways.
– (string) –
• Filters (list) – One or more filters.
– bgp-asn - The customer gateway’s Border Gateway Protocol (BGP) Au-
tonomous System Number (ASN).
– customer-gateway-id - The ID of the customer gateway.
– ip-address - The IP address of the customer gateway’s Internet-
routable external interface.
– state - The state of the customer gateway (pending | available |
deleting | deleted ).
– type - The type of customer gateway. Currently, the only supported type
is ipsec.1 .
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'CustomerGateways': [
{
'CustomerGatewayId': 'string',
'State': 'string',
'Type': 'string',
'IpAddress': 'string',
'BgpAsn': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
3.1. Services 1209
Boto3 Documentation, Release 1.1.4
]
}
Response Structure
• (dict) –
– CustomerGateways (list) –
Information about one or more customer gateways.
* (dict) –
Describes a customer gateway.
· CustomerGatewayId (string) –
The ID of the customer gateway.
· State (string) –
The current state of the customer gateway (pending |
available | deleting | deleted ).
· Type (string) –
The type of VPN connection the customer gateway supports
(ipsec.1 ).
· IpAddress (string) –
The Internet-routable IP address of the customer gateway’s
outside interface.
· BgpAsn (string) –
The customer gateway’s Border Gateway Protocol (BGP) Au-
tonomous System Number (ASN).
· Tags (list) –
Any tags assigned to the customer gateway.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
describe_dhcp_options(**kwargs)
Describes one or more of your DHCP options sets.
For more information about DHCP options sets, see DHCP Options Sets in the Amazon Virtual Private
Cloud User Guide .
Request Syntax
response = client.describe_dhcp_options(
DryRun=True|False,
DhcpOptionsIds=[
'string',
],
1210 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• DhcpOptionsIds (list) – The IDs of one or more DHCP options sets.
Default: Describes all your DHCP options sets.
– (string) –
• Filters (list) – One or more filters.
– dhcp-options-id - The ID of a set of DHCP options.
– key - The key for one of the options (for example, domain-name ).
– value - The value for one of the options.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'DhcpOptions': [
{
'DhcpOptionsId': 'string',
'DhcpConfigurations': [
{
'Key': 'string',
3.1. Services 1211
Boto3 Documentation, Release 1.1.4
'Values': [
{
'Value': 'string'
},
]
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– DhcpOptions (list) –
Information about one or more DHCP options sets.
* (dict) –
Describes a set of DHCP options.
· DhcpOptionsId (string) –
The ID of the set of DHCP options.
· DhcpConfigurations (list) –
One or more DHCP options in the set.
· (dict) –
Describes a DHCP configuration option.
· Key (string) –
The name of a DHCP option.
· Values (list) –
One or more values for the DHCP option.
· (dict) –
The value to use for a resource attribute.
· Value (string) –
Valid values are case-sensitive and vary by action.
· Tags (list) –
Any tags assigned to the DHCP options set.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
1212 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
describe_export_tasks(**kwargs)
Describes one or more of your export tasks.
Request Syntax
response = client.describe_export_tasks(
ExportTaskIds=[
'string',
]
)
Parameters ExportTaskIds (list) – One or more export task IDs.
• (string) –
Return type dict
Returns
Response Syntax
{
'ExportTasks': [
{
'ExportTaskId': 'string',
'Description': 'string',
'State': 'active'|'cancelling'|'cancelled'|'completed',
'StatusMessage': 'string',
'InstanceExportDetails': {
'InstanceId': 'string',
'TargetEnvironment': 'citrix'|'vmware'|'microsoft'
},
'ExportToS3Task': {
'DiskImageFormat': 'VMDK'|'RAW'|'VHD',
'ContainerFormat': 'ova',
'S3Bucket': 'string',
'S3Key': 'string'
}
},
]
}
Response Structure
• (dict) –
– ExportTasks (list) –
Information about the export tasks.
* (dict) –
Describes an instance export task.
· ExportTaskId (string) –
The ID of the export task.
· Description (string) –
A description of the resource being exported.
· State (string) –
The state of the export task.
3.1. Services 1213
Boto3 Documentation, Release 1.1.4
· StatusMessage (string) –
The status message related to the export task.
· InstanceExportDetails (dict) –
Information about the instance to export.
· InstanceId (string) –
The ID of the resource being exported.
· TargetEnvironment (string) –
The target virtualization environment.
· ExportToS3Task (dict) –
Information about the export task.
· DiskImageFormat (string) –
The format for the exported image.
· ContainerFormat (string) –
The container format used to combine disk images with meta-
data (such as OVF). If absent, only the disk image is exported.
· S3Bucket (string) –
The S3 bucket for the destination image. The
destination bucket must exist and grant WRITE
and READ_ACP permissions to the AWS account
[email protected] .
· S3Key (string) –
The encryption key for your S3 bucket.
describe_flow_logs(**kwargs)
Describes one or more flow logs. To view the information in your flow logs (the log streams for the
network interfaces), you must use the CloudWatch Logs console or the CloudWatch Logs API.
Request Syntax
response = client.describe_flow_logs(
FlowLogIds=[
'string',
],
Filter=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• FlowLogIds (list) – One or more flow log IDs.
– (string) –
• Filter (list) – One or more filters.
– deliver-log-status - The status of the logs delivery (SUCCESS |
FAILED ).
– flow-log-id - The ID of the flow log.
1214 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– log-group-name - The name of the log group.
– resource-id - The ID of the VPC, subnet, or network interface.
– traffic-type - The type of traffic (ACCEPT | REJECT | ALL )
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to retrieve the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results can be seen by sending another request
with the returned NextToken value. This value can be between 5 and 1000; if
MaxResults is given a value larger than 1000, only 1000 results are returned.
You cannot specify this parameter and the flow log IDs parameter in the same
request.
Return type dict
Returns
Response Syntax
{
'FlowLogs': [
{
'CreationTime': datetime(2015, 1, 1),
'FlowLogId': 'string',
'FlowLogStatus': 'string',
'ResourceId': 'string',
'TrafficType': 'ACCEPT'|'REJECT'|'ALL',
'LogGroupName': 'string',
'DeliverLogsStatus': 'string',
'DeliverLogsErrorMessage': 'string',
'DeliverLogsPermissionArn': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– FlowLogs (list) –
Information about the flow logs.
* (dict) –
Describes a flow log.
· CreationTime (datetime) –
The date and time the flow log was created.
· FlowLogId (string) –
The flow log ID.
3.1. Services 1215
Boto3 Documentation, Release 1.1.4
· FlowLogStatus (string) –
The status of the flow log (ACTIVE ).
· ResourceId (string) –
The ID of the resource on which the flow log was created.
· TrafficType (string) –
The type of traffic captured for the flow log.
· LogGroupName (string) –
The name of the flow log group.
· DeliverLogsStatus (string) –
The status of the logs delivery (SUCCESS | FAILED ).
· DeliverLogsErrorMessage (string) –
Information about the error that occurred. Rate limited
indicates that CloudWatch logs throttling has been applied
for one or more network interfaces. Access error indi-
cates that the IAM role associated with the flow log does not
have sufficient permissions to publish to CloudWatch Logs.
Unknown error indicates an internal error.
· DeliverLogsPermissionArn (string) –
The ARN of the IAM role that posts logs to CloudWatch
Logs.
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return.
describe_image_attribute(**kwargs)
Describes the specified attribute of the specified AMI. You can specify only one attribute at a time.
Request Syntax
response = client.describe_image_attribute(
DryRun=True|False,
ImageId='string',
Attribute='description'|'kernel'|'ramdisk'|'launchPermission'|'productCodes'|'blockDevic
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageId (string) – [REQUIRED]
The ID of the AMI.
• Attribute (string) – [REQUIRED]
The AMI attribute.
Note : Depending on your account privileges, the blockDeviceMapping
attribute may return a Client.AuthFailure error. If this happens, use De-
scribeImages to get information about the block device mapping for the AMI.
Return type dict
1216 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'ImageId': 'string',
'LaunchPermissions': [
{
'UserId': 'string',
'Group': 'all'
},
],
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
],
'KernelId': {
'Value': 'string'
},
'RamdiskId': {
'Value': 'string'
},
'Description': {
'Value': 'string'
},
'SriovNetSupport': {
'Value': 'string'
},
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
},
]
}
Response Structure
• (dict) –
Information about the image attribute.
– ImageId (string) –
The ID of the AMI.
– LaunchPermissions (list) –
One or more launch permissions.
* (dict) –
Describes a launch permission.
3.1. Services 1217
Boto3 Documentation, Release 1.1.4
· UserId (string) –
The AWS account ID.
· Group (string) –
The name of the group.
– ProductCodes (list) –
One or more product codes.
* (dict) –
Describes a product code.
· ProductCodeId (string) –
The product code.
· ProductCodeType (string) –
The type of product code.
– KernelId (dict) –
The kernel ID.
* Value (string) –
Valid values are case-sensitive and vary by action.
– RamdiskId (dict) –
The RAM disk ID.
* Value (string) –
Valid values are case-sensitive and vary by action.
– Description (dict) –
A description for the AMI.
* Value (string) –
Valid values are case-sensitive and vary by action.
– SriovNetSupport (dict) –
The value to use for a resource attribute.
* Value (string) –
Valid values are case-sensitive and vary by action.
– BlockDeviceMappings (list) –
One or more block device mapping entries.
* (dict) –
Describes a block device mapping.
· VirtualName (string) –
The virtual device name (ephemeral N). Instance store vol-
umes are numbered starting from 0. An instance type with
2 available instance store volumes can specify mappings for
ephemeral0 and ephemeral1 .The number of available
instance store volumes depends on the instance type. After
you connect to the instance, you must mount the volume.
Constraints: For M3 instances, you must specify instance
store volumes in the block device mapping for the instance.
When you launch an M3 instance, we ignore any instance
store volumes specified in the block device mapping for the
AMI.
1218 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
· NoDevice (string) –
Suppresses the specified device included in the block device
mapping of the AMI.
3.1. Services 1219
Boto3 Documentation, Release 1.1.4
describe_images(**kwargs)
Describes one or more of the images (AMIs, AKIs, and ARIs) available to you. Images available to you
include public images, private images that you own, and private images owned by other AWS accounts
but for which you have explicit launch permissions.
Note: Deregistered images are included in the returned results for an unspecified interval after deregis-
tration.
Request Syntax
response = client.describe_images(
DryRun=True|False,
ImageIds=[
'string',
],
Owners=[
'string',
],
ExecutableUsers=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageIds (list) – One or more image IDs.
Default: Describes all images available to you.
– (string) –
• Owners (list) – Filters the images by the owner. Specify an AWS account ID,
amazon (owner is Amazon), aws-marketplace (owner is AWS Market-
place), self (owner is the sender of the request). Omitting this option returns
all images for which you have launch permissions, regardless of ownership.
– (string) –
• ExecutableUsers (list) – Scopes the images by users with explicit launch per-
missions. Specify an AWS account ID, self (the sender of the request), or all
(public AMIs).
– (string) –
• Filters (list) – One or more filters.
– architecture - The image architecture (i386 | x86_64 ).
– block-device-mapping.delete-on-termination - A
Boolean value that indicates whether the Amazon EBS volume is deleted
on instance termination.
– block-device-mapping.device-name - The device name for the
EBS volume (for example, /dev/sdh ).
1220 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– block-device-mapping.snapshot-id - The ID of the snapshot
used for the EBS volume.
– block-device-mapping.volume-size - The volume size of the
EBS volume, in GiB.
– block-device-mapping.volume-type - The volume type of the
EBS volume (gp2 | standard | io1 ).
– description - The description of the image (provided during image
creation).
– hypervisor - The hypervisor type (ovm | xen ).
– image-id - The ID of the image.
– image-type - The image type (machine | kernel | ramdisk ).
– is-public - A Boolean that indicates whether the image is public.
– kernel-id - The kernel ID.
– manifest-location - The location of the image manifest.
– name - The name of the AMI (provided during image creation).
– owner-alias - The AWS account alias (for example, amazon ).
– owner-id - The AWS account ID of the image owner.
– platform - The platform. To only list Windows-based AMIs, use
windows .
– product-code - The product code.
– product-code.type - The type of the product code (devpay |
marketplace ).
– ramdisk-id - The RAM disk ID.
– root-device-name - The name of the root device volume (for exam-
ple, /dev/sda1 ).
– root-device-type - The type of the root device volume (ebs |
instance-store ).
– state - The state of the image (available | pending | failed ).
– state-reason-code - The reason code for the state change.
– state-reason-message - The message for the state change.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is in-
dependent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– virtualization-type - The virtualization type (paravirtual |
hvm ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
3.1. Services 1221
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'Images': [
{
'ImageId': 'string',
'ImageLocation': 'string',
'State': 'pending'|'available'|'invalid'|'deregistered'|'transient'|'f
'OwnerId': 'string',
'CreationDate': 'string',
'Public': True|False,
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
],
'Architecture': 'i386'|'x86_64',
'ImageType': 'machine'|'kernel'|'ramdisk',
'KernelId': 'string',
'RamdiskId': 'string',
'Platform': 'Windows',
'SriovNetSupport': 'string',
'StateReason': {
'Code': 'string',
'Message': 'string'
},
'ImageOwnerAlias': 'string',
'Name': 'string',
'Description': 'string',
'RootDeviceType': 'ebs'|'instance-store',
'RootDeviceName': 'string',
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
},
],
'VirtualizationType': 'hvm'|'paravirtual',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'Hypervisor': 'ovm'|'xen'
},
1222 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
]
}
Response Structure
• (dict) –
– Images (list) –
Information about one or more images.
* (dict) –
Describes an image.
· ImageId (string) –
The ID of the AMI.
· ImageLocation (string) –
The location of the AMI.
· State (string) –
The current state of the AMI. If the state is available , the
image is successfully registered and can be used to launch an
instance.
· OwnerId (string) –
The AWS account ID of the image owner.
· CreationDate (string) –
The date and time the image was created.
· Public (boolean) –
Indicates whether the image has public launch permissions.
The value is true if this image has public launch permis-
sions or false if it has only implicit and explicit launch per-
missions.
· ProductCodes (list) –
Any product codes associated with the AMI.
· (dict) –
Describes a product code.
· ProductCodeId (string) –
The product code.
· ProductCodeType (string) –
The type of product code.
· Architecture (string) –
The architecture of the image.
· ImageType (string) –
The type of image.
· KernelId (string) –
The kernel associated with the image, if any. Only applicable
for machine images.
· RamdiskId (string) –
The RAM disk associated with the image, if any. Only appli-
cable for machine images.
3.1. Services 1223
Boto3 Documentation, Release 1.1.4
· Platform (string) –
The value is Windows for Windows AMIs; otherwise blank.
· SriovNetSupport (string) –
Specifies whether enhanced networking is enabled.
· StateReason (dict) –
The reason for the state change.
· Code (string) –
The reason code for the state change.
· Message (string) –
The message for the state change.
· Server.SpotInstanceTermination : A Spot In-
stance was terminated due to an increase in the market price.
· Server.InternalError : An internal error occurred
during instance launch, resulting in termination.
· Server.InsufficientInstanceCapacity : There
was insufficient instance capacity to satisfy the launch re-
quest.
· Client.InternalError : A client error caused the in-
stance to terminate on launch.
· Client.InstanceInitiatedShutdown : The in-
stance was shut down using the shutdown -h command
from the instance.
· Client.UserInitiatedShutdown : The instance was
shut down using the Amazon EC2 API.
· Client.VolumeLimitExceeded : The volume limit
was exceeded.
· Client.InvalidSnapshot.NotFound : The speci-
fied snapshot was not found.
· ImageOwnerAlias (string) –
The AWS account alias (for example, amazon , self ) or
the AWS account ID of the AMI owner.
· Name (string) –
The name of the AMI that was provided during image cre-
ation.
· Description (string) –
The description of the AMI that was provided during image
creation.
· RootDeviceType (string) –
The type of root device used by the AMI. The AMI can use
an EBS volume or an instance store volume.
· RootDeviceName (string) –
The device name of the root device (for example,
/dev/sda1 or /dev/xvda ).
· BlockDeviceMappings (list) –
Any block device mapping entries.
· (dict) –
Describes a block device mapping.
1224 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· VirtualName (string) –
The virtual device name (ephemeral N). Instance store vol-
umes are numbered starting from 0. An instance type with
2 available instance store volumes can specify mappings for
ephemeral0 and ephemeral1 .The number of available
instance store volumes depends on the instance type. After
you connect to the instance, you must mount the volume.
Constraints: For M3 instances, you must specify instance
store volumes in the block device mapping for the instance.
When you launch an M3 instance, we ignore any instance
store volumes specified in the block device mapping for the
AMI.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
3.1. Services 1225
Boto3 Documentation, Release 1.1.4
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
· NoDevice (string) –
Suppresses the specified device included in the block device
mapping of the AMI.
· VirtualizationType (string) –
The type of virtualization of the AMI.
· Tags (list) –
Any tags assigned to the image.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· Hypervisor (string) –
The hypervisor type of the image.
describe_import_image_tasks(**kwargs)
Displays details about an import virtual machine or import snapshot tasks that are already created.
Request Syntax
response = client.describe_import_image_tasks(
DryRun=True|False,
ImportTaskIds=[
'string',
],
NextToken='string',
MaxResults=123,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
1226 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImportTaskIds (list) – A list of import image task IDs.
– (string) –
• NextToken (string) – A token that indicates the next page of results.
• MaxResults (integer) – The maximum number of results to return in a single
request.
• Filters (list) – One or more filters.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'ImportImageTasks': [
{
'ImportTaskId': 'string',
'Architecture': 'string',
'LicenseType': 'string',
'Platform': 'string',
'Hypervisor': 'string',
'Description': 'string',
'SnapshotDetails': [
{
'DiskImageSize': 123.0,
'Description': 'string',
'Format': 'string',
'Url': 'string',
'UserBucket': {
'S3Bucket': 'string',
'S3Key': 'string'
},
'DeviceName': 'string',
'SnapshotId': 'string',
'Progress': 'string',
'StatusMessage': 'string',
'Status': 'string'
},
],
'ImageId': 'string',
'Progress': 'string',
'StatusMessage': 'string',
'Status': 'string'
3.1. Services 1227
Boto3 Documentation, Release 1.1.4
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– ImportImageTasks (list) –
A list of zero or more import image tasks that are currently active or were
completed or canceled in the previous 7 days.
* (dict) –
Describes an import image task.
· ImportTaskId (string) –
The ID of the import image task.
· Architecture (string) –
The architecture of the virtual machine.
Valid values: i386 | x86_64
· LicenseType (string) –
The license type of the virtual machine.
· Platform (string) –
The description string for the import image task.
· Hypervisor (string) –
The target hypervisor for the import task.
Valid values: xen
· Description (string) –
A description of the import task.
· SnapshotDetails (list) –
Information about the snapshots.
· (dict) –
Describes the snapshot created from the imported disk.
· DiskImageSize (float) –
The size of the disk in the snapshot, in GiB.
· Description (string) –
A description for the snapshot.
· Format (string) –
The format of the disk image from which the snapshot is cre-
ated.
· Url (string) –
The URL used to access the disk image.
· UserBucket (dict) –
Describes the S3 bucket for the disk image.
· S3Bucket (string) –
The S3 bucket from which the disk image was created.
1228 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· S3Key (string) –
The key from which the disk image was created.
· DeviceName (string) –
The block device mapping for the snapshot.
· SnapshotId (string) –
The snapshot ID of the disk being imported.
· Progress (string) –
The percentage of progress for the task.
· StatusMessage (string) –
A detailed status message for the snapshot creation.
· Status (string) –
A brief status of the snapshot creation.
· ImageId (string) –
The ID of the Amazon Machine Image (AMI) of the imported
virtual machine.
· Progress (string) –
The percentage of progress of the import image task.
· StatusMessage (string) –
A descriptive status message for the import image task.
· Status (string) –
A brief status for the import image task.
– NextToken (string) –
The token to use to get the next page of results. This value is null when
there are no more results to return.
describe_import_snapshot_tasks(**kwargs)
Describes your import snapshot tasks.
Request Syntax
response = client.describe_import_snapshot_tasks(
DryRun=True|False,
ImportTaskIds=[
'string',
],
NextToken='string',
MaxResults=123,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
3.1. Services 1229
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImportTaskIds (list) – A list of import snapshot task IDs.
– (string) –
• NextToken (string) – A token that indicates the next page of results.
• MaxResults (integer) – The maximum number of results to return in a single
request.
• Filters (list) – One or more filters.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'ImportSnapshotTasks': [
{
'ImportTaskId': 'string',
'SnapshotTaskDetail': {
'DiskImageSize': 123.0,
'Description': 'string',
'Format': 'string',
'Url': 'string',
'UserBucket': {
'S3Bucket': 'string',
'S3Key': 'string'
},
'SnapshotId': 'string',
'Progress': 'string',
'StatusMessage': 'string',
'Status': 'string'
},
'Description': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– ImportSnapshotTasks (list) –
A list of zero or more import snapshot tasks that are currently active or
were completed or canceled in the previous 7 days.
* (dict) –
Describes an import snapshot task.
1230 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· ImportTaskId (string) –
The ID of the import snapshot task.
· SnapshotTaskDetail (dict) –
Describes an import snapshot task.
· DiskImageSize (float) –
The size of the disk in the snapshot, in GiB.
· Description (string) –
The description of the snapshot.
· Format (string) –
The format of the disk image from which the snapshot is cre-
ated.
· Url (string) –
The URL of the disk image from which the snapshot is cre-
ated.
· UserBucket (dict) –
The S3 bucket for the disk image.
· S3Bucket (string) –
The S3 bucket from which the disk image was created.
· S3Key (string) –
The key from which the disk image was created.
· SnapshotId (string) –
The snapshot ID of the disk being imported.
· Progress (string) –
The percentage of completion for the import snapshot task.
· StatusMessage (string) –
A detailed status message for the import snapshot task.
· Status (string) –
A brief status for the import snapshot task.
· Description (string) –
A description of the import snapshot task.
– NextToken (string) –
The token to use to get the next page of results. This value is null when
there are no more results to return.
describe_instance_attribute(**kwargs)
Describes the specified attribute of the specified instance. You can specify only one attribute
at a time. Valid attribute values are: instanceType | kernel | ramdisk | userData |
disableApiTermination | instanceInitiatedShutdownBehavior | rootDeviceName
| blockDeviceMapping | productCodes | sourceDestCheck | groupSet | ebsOptimized
| sriovNetSupport
Request Syntax
response = client.describe_instance_attribute(
DryRun=True|False,
InstanceId='string',
3.1. Services 1231
Boto3 Documentation, Release 1.1.4
Attribute='instanceType'|'kernel'|'ramdisk'|'userData'|'disableApiTermination'|'instance
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the instance.
• Attribute (string) – [REQUIRED]
The instance attribute.
Return type dict
Returns
Response Syntax
{
'InstanceId': 'string',
'InstanceType': {
'Value': 'string'
},
'KernelId': {
'Value': 'string'
},
'RamdiskId': {
'Value': 'string'
},
'UserData': {
'Value': 'string'
},
'DisableApiTermination': {
'Value': True|False
},
'InstanceInitiatedShutdownBehavior': {
'Value': 'string'
},
'RootDeviceName': {
'Value': 'string'
},
'BlockDeviceMappings': [
{
'DeviceName': 'string',
'Ebs': {
'VolumeId': 'string',
'Status': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
}
},
],
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
1232 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'EbsOptimized': {
'Value': True|False
},
'SriovNetSupport': {
'Value': 'string'
},
'SourceDestCheck': {
'Value': True|False
},
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
]
}
Response Structure
• (dict) –
Information about the instance attribute.
– InstanceId (string) –
The ID of the instance.
– InstanceType (dict) –
The instance type.
* Value (string) –
Valid values are case-sensitive and vary by action.
– KernelId (dict) –
The kernel ID.
* Value (string) –
Valid values are case-sensitive and vary by action.
– RamdiskId (dict) –
The RAM disk ID.
* Value (string) –
Valid values are case-sensitive and vary by action.
– UserData (dict) –
The Base64-encoded MIME user data.
* Value (string) –
Valid values are case-sensitive and vary by action.
– DisableApiTermination (dict) –
If the value is true , you can’t terminate the instance through the Amazon
EC2 console, CLI, or API; otherwise, you can.
* Value (boolean) –
Valid values are true or false .
– InstanceInitiatedShutdownBehavior (dict) –
Indicates whether an instance stops or terminates when you initiate shut-
down from the instance (using the operating system command for system
shutdown).
3.1. Services 1233
Boto3 Documentation, Release 1.1.4
* Value (string) –
Valid values are case-sensitive and vary by action.
– RootDeviceName (dict) –
The name of the root device (for example, /dev/sda1 or /dev/xvda
).
* Value (string) –
Valid values are case-sensitive and vary by action.
– BlockDeviceMappings (list) –
The block device mapping of the instance.
* (dict) –
Describes a block device mapping.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· VolumeId (string) –
The ID of the EBS volume.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the volume is deleted on instance termina-
tion.
– ProductCodes (list) –
A list of product codes.
* (dict) –
Describes a product code.
· ProductCodeId (string) –
The product code.
· ProductCodeType (string) –
The type of product code.
– EbsOptimized (dict) –
Indicates whether the instance is optimized for EBS I/O.
* Value (boolean) –
Valid values are true or false .
– SriovNetSupport (dict) –
The value to use for a resource attribute.
* Value (string) –
Valid values are case-sensitive and vary by action.
1234 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– SourceDestCheck (dict) –
Indicates whether source/destination checking is enabled. A value of
true means checking is enabled, and false means checking is disabled.
This value must be false for a NAT instance to perform NAT.
* Value (boolean) –
Valid values are true or false .
– Groups (list) –
The security groups associated with the instance.
* (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
describe_instance_status(**kwargs)
Describes the status of one or more instances.
Instance status includes the following components:
•Status checks - Amazon EC2 performs status checks on running EC2 instances to identify hard-
ware and software issues. For more information, see Status Checks for Your Instances and Trou-
bleshooting Instances with Failed Status Checks in the Amazon Elastic Compute Cloud User Guide
.
•Scheduled events - Amazon EC2 can schedule events (such as reboot, stop, or terminate) for your
instances related to hardware issues, software updates, or system maintenance. For more informa-
tion, see Scheduled Events for Your Instances in the Amazon Elastic Compute Cloud User Guide
.
•Instance state - You can manage your instances from the moment you launch them through their
termination. For more information, see Instance Lifecycle in the Amazon Elastic Compute Cloud
User Guide .
Request Syntax
response = client.describe_instance_status(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123,
IncludeAllInstances=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
3.1. Services 1235
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
Constraints: Maximum 100 explicitly specified instance IDs.
– (string) –
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone of the instance.
– event.code - The code for the scheduled event
(instance-reboot | system-reboot | system-maintenance
| instance-retirement | instance-stop ).
– event.description - A description of the event.
– event.not-after - The latest end time for the scheduled event (for
example, 2014-09-15T17:15:20.000Z ).
– event.not-before - The earliest start time for the scheduled event
(for example, 2014-09-15T17:15:20.000Z ).
– instance-state-code - The code for the instance state, as a 16-bit
unsigned integer. The high byte is an opaque internal value and should
be ignored. The low byte is set based on the state represented. The valid
values are 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-status.reachability - Filters on instance sta-
tus where the name is reachability (passed | failed |
initializing | insufficient-data ).
– instance-status.status - The status of the instance (ok
| impaired | initializing | insufficient-data |
not-applicable ).
– system-status.reachability - Filters on system status where
the name is reachability (passed | failed | initializing
| insufficient-data ).
– system-status.status - The system status of the instance
(ok | impaired | initializing | insufficient-data |
not-applicable ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to retrieve the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
1236 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
IDs parameter in the same request.
• IncludeAllInstances (boolean) – When true , includes the health status for all
instances. When false , includes the health status for running instances only.
Default: false
Return type dict
Returns
Response Syntax
{
'InstanceStatuses': [
{
'InstanceId': 'string',
'AvailabilityZone': 'string',
'Events': [
{
'Code': 'instance-reboot'|'system-reboot'|'system-maintenance'
'Description': 'string',
'NotBefore': datetime(2015, 1, 1),
'NotAfter': datetime(2015, 1, 1)
},
],
'InstanceState': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
},
'SystemStatus': {
'Status': 'ok'|'impaired'|'insufficient-data'|'not-applicable'|'in
'Details': [
{
'Name': 'reachability',
'Status': 'passed'|'failed'|'insufficient-data'|'initializ
'ImpairedSince': datetime(2015, 1, 1)
},
]
},
'InstanceStatus': {
'Status': 'ok'|'impaired'|'insufficient-data'|'not-applicable'|'in
'Details': [
{
'Name': 'reachability',
'Status': 'passed'|'failed'|'insufficient-data'|'initializ
'ImpairedSince': datetime(2015, 1, 1)
},
]
}
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– InstanceStatuses (list) –
One or more instance status descriptions.
* (dict) –
3.1. Services 1237
Boto3 Documentation, Release 1.1.4
Describes the status of an instance.
· InstanceId (string) –
The ID of the instance.
· AvailabilityZone (string) –
The Availability Zone of the instance.
· Events (list) –
Any scheduled events associated with the instance.
· (dict) –
Describes a scheduled event for an instance.
· Code (string) –
The event code.
· Description (string) –
A description of the event.
After a scheduled event is completed, it can still be described
for up to a week. If the event has been completed, this de-
scription starts with the following text: [Completed].
· NotBefore (datetime) –
The earliest scheduled start time for the event.
· NotAfter (datetime) –
The latest scheduled end time for the event.
· InstanceState (dict) –
The intended state of the instance. DescribeInstanceStatus
requires that an instance be in the running state.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
· SystemStatus (dict) –
Reports impaired functionality that stems from issues related
to the systems that support an instance, such as hardware fail-
ures and network connectivity problems.
· Status (string) –
The status.
· Details (list) –
The system instance health or application instance health.
· (dict) –
Describes the instance status.
· Name (string) –
1238 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The type of instance status.
· Status (string) –
The status.
· ImpairedSince (datetime) –
The time when a status check failed. For an instance that was
launched and impaired, this is the time when the instance was
launched.
· InstanceStatus (dict) –
Reports impaired functionality that stems from issues internal
to the instance, such as impaired reachability.
· Status (string) –
The status.
· Details (list) –
The system instance health or application instance health.
· (dict) –
Describes the instance status.
· Name (string) –
The type of instance status.
· Status (string) –
The status.
· ImpairedSince (datetime) –
The time when a status check failed. For an instance that was
launched and impaired, this is the time when the instance was
launched.
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return.
describe_instances(**kwargs)
Describes one or more of your instances.
If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do
not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an
instance ID that is not valid, an error is returned. If you specify an instance that you do not own, it is not
included in the returned results.
Recently terminated instances might appear in the returned results. This interval is usually less than one
hour.
Request Syntax
response = client.describe_instances(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
3.1. Services 1239
Boto3 Documentation, Release 1.1.4
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
– (string) –
• Filters (list) – One or more filters.
– architecture - The instance architecture (i386 | x86_64 ).
– availability-zone - The Availability Zone of the instance.
– block-device-mapping.attach-time - The attach time
for an EBS volume mapped to the instance, for example,
2010-09-15T17:15:20.000Z .
– block-device-mapping.delete-on-termination - A
Boolean that indicates whether the EBS volume is deleted on instance
termination.
– block-device-mapping.device-name - The device name for the
EBS volume (for example, /dev/sdh or xvdh ).
– block-device-mapping.status - The status for the EBS volume
(attaching | attached | detaching | detached ).
– block-device-mapping.volume-id - The volume ID of the EBS
volume.
– client-token - The idempotency token you provided when you
launched the instance.
– dns-name - The public DNS name of the instance.
– group-id - The ID of the security group for the instance. EC2-Classic
only.
– group-name - The name of the security group for the instance. EC2-
Classic only.
– hypervisor - The hypervisor type of the instance (ovm | xen ).
– iam-instance-profile.arn - The instance profile associated with
the instance. Specified as an ARN.
– image-id - The ID of the image used to launch the instance.
– instance-id - The ID of the instance.
– instance-lifecycle - Indicates whether this is a Spot Instance
(spot ).
– instance-state-code - The state of the instance, as a 16-bit un-
signed integer. The high byte is an opaque internal value and should be
ignored. The low byte is set based on the state represented. The valid val-
ues are: 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-type - The type of instance (for example, t2.micro ).
– instance.group-id - The ID of the security group for the instance.
1240 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– instance.group-name - The name of the security group for the in-
stance.
– ip-address - The public IP address of the instance.
– kernel-id - The kernel ID.
– key-name - The name of the key pair used when the instance was
launched.
– launch-index - When launching multiple instances, this is the index
for the instance in the launch group (for example, 0, 1, 2, and so on).
– launch-time - The time when the instance was launched.
– monitoring-state - Indicates whether monitoring is enabled for the
instance (disabled | enabled ).
– owner-id - The AWS account ID of the instance owner.
– placement-group-name - The name of the placement group for the
instance.
– platform - The platform. Use windows if you have Windows in-
stances; otherwise, leave blank.
– private-dns-name - The private DNS name of the instance.
– private-ip-address - The private IP address of the instance.
– product-code - The product code associated with the AMI used to
launch the instance.
– product-code.type - The type of product code (devpay |
marketplace ).
– ramdisk-id - The RAM disk ID.
– reason - The reason for the current state of the instance (for example,
shows “User Initiated [date]” when you stop or terminate the instance).
Similar to the state-reason-code filter.
– requester-id - The ID of the entity that launched the instance on
your behalf (for example, AWS Management Console, Auto Scaling, and
so on).
– reservation-id - The ID of the instance’s reservation. A reservation
ID is created any time you launch an instance. A reservation ID has a
one-to-one relationship with an instance launch request, but can be asso-
ciated with more than one instance if you launch multiple instances using
the same launch request. For example, if you launch one instance, you’ll
get one reservation ID. If you launch ten instances using the same launch
request, you’ll also get one reservation ID.
– root-device-name - The name of the root device for the instance (for
example, /dev/sda1 or /dev/xvda ).
– root-device-type - The type of root device that the instance uses
(ebs | instance-store ).
– source-dest-check - Indicates whether the instance performs
source/destination checking. A value of true means that checking is
enabled, and false means checking is disabled. The value must be
false for the instance to perform network address translation (NAT) in
your VPC.
– spot-instance-request-id - The ID of the Spot Instance request.
– state-reason-code - The reason code for the state change.
– state-reason-message - A message that describes the state change.
– subnet-id - The ID of the subnet for the instance.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource, where tag :key is the tag’s key.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
3.1. Services 1241
Boto3 Documentation, Release 1.1.4
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– tenancy - The tenancy of an instance (dedicated | default ).
– virtualization-type - The virtualization type of the instance
(paravirtual | hvm ).
– vpc-id - The ID of the VPC that the instance is running in.
– network-interface.description - The description of the net-
work interface.
– network-interface.subnet-id - The ID of the subnet for the net-
work interface.
– network-interface.vpc-id - The ID of the VPC for the network
interface.
– network-interface.network-interface.id - The ID of the
network interface.
– network-interface.owner-id - The ID of the owner of the net-
work interface.
– network-interface.availability-zone - The Availability
Zone for the network interface.
– network-interface.requester-id - The requester ID for the
network interface.
– network-interface.requester-managed - Indicates whether
the network interface is being managed by AWS.
– network-interface.status - The status of the network interface
(available ) | in-use ).
– network-interface.mac-address - The MAC address of the net-
work interface.
– network-interface-private-dns-name - The private DNS
name of the network interface.
– network-interface.source-dest-check - Whether the net-
work interface performs source/destination checking. A value of true
means checking is enabled, and false means checking is disabled. The
value must be false for the network interface to perform network ad-
dress translation (NAT) in your VPC.
– network-interface.group-id - The ID of a security group asso-
ciated with the network interface.
– network-interface.group-name - The name of a security group
associated with the network interface.
– network-interface.attachment.attachment-id - The ID
of the interface attachment.
– network-interface.attachment.instance-id - The ID of
the instance to which the network interface is attached.
– network-interface.attachment.instance-owner-id -
The owner ID of the instance to which the network interface is attached.
– network-interface.addresses.private-ip-address -
The private IP address associated with the network interface.
– network-interface.attachment.device-index - The de-
vice index to which the network interface is attached.
– network-interface.attachment.status - The status of the at-
tachment (attaching | attached | detaching | detached ).
– network-interface.attachment.attach-time - The time
that the network interface was attached to an instance.
1242 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– network-interface.attachment.delete-on-termination
- Specifies whether the attachment is deleted when an instance is termi-
nated.
– network-interface.addresses.primary - Specifies whether
the IP address of the network interface is the primary private IP address.
– network-interface.addresses.association.public-ip
- The ID of the association of an Elastic IP address with a network
interface.
– network-interface.addresses.association.ip-owner-id
- The owner ID of the private IP address associated with the network
interface.
– association.public-ip - The address of the Elastic IP address
bound to the network interface.
– association.ip-owner-id - The owner of the Elastic IP address
associated with the network interface.
– association.allocation-id - The allocation ID returned when
you allocated the Elastic IP address for your network interface.
– association.association-id - The association ID returned
when the network interface was associated with an IP address.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to request the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
IDs parameter in the same request.
Return type dict
Returns
Response Syntax
{
'Reservations': [
{
'ReservationId': 'string',
'OwnerId': 'string',
'RequesterId': 'string',
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'Instances': [
3.1. Services 1243
Boto3 Documentation, Release 1.1.4
{
'InstanceId': 'string',
'ImageId': 'string',
'State': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'
},
'PrivateDnsName': 'string',
'PublicDnsName': 'string',
'StateTransitionReason': 'string',
'KeyName': 'string',
'AmiLaunchIndex': 123,
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
],
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'
'LaunchTime': datetime(2015, 1, 1),
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string',
'Tenancy': 'default'|'dedicated'
},
'KernelId': 'string',
'RamdiskId': 'string',
'Platform': 'Windows',
'Monitoring': {
'State': 'disabled'|'disabling'|'enabled'|'pending'
},
'SubnetId': 'string',
'VpcId': 'string',
'PrivateIpAddress': 'string',
'PublicIpAddress': 'string',
'StateReason': {
'Code': 'string',
'Message': 'string'
},
'Architecture': 'i386'|'x86_64',
'RootDeviceType': 'ebs'|'instance-store',
'RootDeviceName': 'string',
'BlockDeviceMappings': [
{
'DeviceName': 'string',
'Ebs': {
'VolumeId': 'string',
'Status': 'attaching'|'attached'|'detaching'|'deta
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
}
},
],
'VirtualizationType': 'hvm'|'paravirtual',
'InstanceLifecycle': 'spot',
'SpotInstanceRequestId': 'string',
'ClientToken': 'string',
'Tags': [
1244 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'Key': 'string',
'Value': 'string'
},
],
'SecurityGroups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'SourceDestCheck': True|False,
'Hypervisor': 'ovm'|'xen',
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'SubnetId': 'string',
'VpcId': 'string',
'Description': 'string',
'OwnerId': 'string',
'Status': 'available'|'attaching'|'in-use'|'detaching'
'MacAddress': 'string',
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'SourceDestCheck': True|False,
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'Attachment': {
'AttachmentId': 'string',
'DeviceIndex': 123,
'Status': 'attaching'|'attached'|'detaching'|'deta
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
},
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string'
},
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'Primary': True|False,
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string'
}
},
]
},
],
'IamInstanceProfile': {
3.1. Services 1245
Boto3 Documentation, Release 1.1.4
'Arn': 'string',
'Id': 'string'
},
'EbsOptimized': True|False,
'SriovNetSupport': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– Reservations (list) –
One or more reservations.
* (dict) –
Describes a reservation.
· ReservationId (string) –
The ID of the reservation.
· OwnerId (string) –
The ID of the AWS account that owns the reservation.
· RequesterId (string) –
The ID of the requester that launched the instances on your
behalf (for example, AWS Management Console or Auto
Scaling).
· Groups (list) –
One or more security groups.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· Instances (list) –
One or more instances.
· (dict) –
Describes an instance.
· InstanceId (string) –
The ID of the instance.
· ImageId (string) –
The ID of the AMI used to launch the instance.
· State (dict) –
The current state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
1246 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
· PrivateDnsName (string) –
The private DNS name assigned to the instance. This DNS
name can only be used inside the Amazon EC2 network. This
name is not available until the instance enters the running
state.
· PublicDnsName (string) –
The public DNS name assigned to the instance. This name is
not available until the instance enters the running state.
· StateTransitionReason (string) –
The reason for the most recent state transition. This might be
an empty string.
· KeyName (string) –
The name of the key pair, if this instance was launched with
an associated key pair.
· AmiLaunchIndex (integer) –
The AMI launch index, which can be used to find this instance
in the launch group.
· ProductCodes (list) –
The product codes attached to this instance.
· (dict) –
Describes a product code.
· ProductCodeId (string) –
The product code.
· ProductCodeType (string) –
The type of product code.
· InstanceType (string) –
The instance type.
· LaunchTime (datetime) –
The time the instance was launched.
· Placement (dict) –
The location where the instance launched.
· AvailabilityZone (string) –
The Availability Zone of the instance.
· GroupName (string) –
The name of the placement group the instance is in (for cluster
compute instances).
· Tenancy (string) –
3.1. Services 1247
Boto3 Documentation, Release 1.1.4
The tenancy of the instance (if the instance is running in a
VPC). An instance with a tenancy of dedicated runs on
single-tenant hardware.
· KernelId (string) –
The kernel associated with this instance.
· RamdiskId (string) –
The RAM disk associated with this instance.
· Platform (string) –
The value is Windows for Windows instances; otherwise
blank.
· Monitoring (dict) –
The monitoring information for the instance.
· State (string) –
Indicates whether monitoring is enabled for the instance.
· SubnetId (string) –
The ID of the subnet in which the instance is running.
· VpcId (string) –
The ID of the VPC in which the instance is running.
· PrivateIpAddress (string) –
The private IP address assigned to the instance.
· PublicIpAddress (string) –
The public IP address assigned to the instance.
· StateReason (dict) –
The reason for the most recent state transition.
· Code (string) –
The reason code for the state change.
· Message (string) –
The message for the state change.
· Server.SpotInstanceTermination : A Spot In-
stance was terminated due to an increase in the market price.
· Server.InternalError : An internal error occurred
during instance launch, resulting in termination.
· Server.InsufficientInstanceCapacity : There
was insufficient instance capacity to satisfy the launch re-
quest.
· Client.InternalError : A client error caused the in-
stance to terminate on launch.
· Client.InstanceInitiatedShutdown : The in-
stance was shut down using the shutdown -h command
from the instance.
· Client.UserInitiatedShutdown : The instance was
shut down using the Amazon EC2 API.
· Client.VolumeLimitExceeded : The volume limit
was exceeded.
· Client.InvalidSnapshot.NotFound : The speci-
fied snapshot was not found.
· Architecture (string) –
1248 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The architecture of the image.
· RootDeviceType (string) –
The root device type used by the AMI. The AMI can use an
EBS volume or an instance store volume.
· RootDeviceName (string) –
The root device name (for example, /dev/sda1 or
/dev/xvda ).
· BlockDeviceMappings (list) –
Any block device mapping entries for the instance.
· (dict) –
Describes a block device mapping.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· VolumeId (string) –
The ID of the EBS volume.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the volume is deleted on instance termina-
tion.
· VirtualizationType (string) –
The virtualization type of the instance.
· InstanceLifecycle (string) –
Indicates whether this is a Spot Instance.
· SpotInstanceRequestId (string) –
The ID of the Spot Instance request.
· ClientToken (string) –
The idempotency token you provided when you launched the
instance.
· Tags (list) –
Any tags assigned to the instance.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
3.1. Services 1249
Boto3 Documentation, Release 1.1.4
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· SecurityGroups (list) –
One or more security groups for the instance.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· SourceDestCheck (boolean) –
Specifies whether to enable an instance launched in a VPC
to perform NAT. This controls whether source/destination
checking is enabled on the instance. A value of true means
checking is enabled, and false means checking is disabled.
The value must be false for the instance to perform NAT.
For more information, see NAT Instances in the Amazon Vir-
tual Private Cloud User Guide .
· Hypervisor (string) –
The hypervisor type of the instance.
· NetworkInterfaces (list) –
[EC2-VPC] One or more network interfaces for the instance.
· (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· SubnetId (string) –
The ID of the subnet.
· VpcId (string) –
The ID of the VPC.
· Description (string) –
The description.
· OwnerId (string) –
The ID of the AWS account that created the network interface.
· Status (string) –
The status of the network interface.
· MacAddress (string) –
The MAC address.
· PrivateIpAddress (string) –
The IP address of the network interface within the subnet.
· PrivateDnsName (string) –
The private DNS name.
1250 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· SourceDestCheck (boolean) –
Indicates whether to validate network traffic to or from this
network interface.
· Groups (list) –
One or more security groups.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· Attachment (dict) –
The network interface attachment.
· AttachmentId (string) –
The ID of the network interface attachment.
· DeviceIndex (integer) –
The index of the device on the instance for the network inter-
face attachment.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the network interface is deleted when the
instance is terminated.
· Association (dict) –
The association information for an Elastic IP associated with
the network interface.
· PublicIp (string) –
The public IP address or Elastic IP address bound to the net-
work interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the owner of the Elastic IP address.
· PrivateIpAddresses (list) –
The private IP addresses associated with the network inter-
face.
· (dict) –
Describes a private IP address.
· PrivateIpAddress (string) –
The private IP address of the network interface.
· PrivateDnsName (string) –
The private DNS name.
3.1. Services 1251
Boto3 Documentation, Release 1.1.4
· Primary (boolean) –
Indicates whether this IP address is the primary private IP ad-
dress of the network interface.
· Association (dict) –
The association information for an Elastic IP address for the
network interface.
· PublicIp (string) –
The public IP address or Elastic IP address bound to the net-
work interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the owner of the Elastic IP address.
· IamInstanceProfile (dict) –
The IAM instance profile associated with the instance.
· Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
· Id (string) –
The ID of the instance profile.
· EbsOptimized (boolean) –
Indicates whether the instance is optimized for EBS I/O. This
optimization provides dedicated throughput to Amazon EBS
and an optimized configuration stack to provide optimal I/O
performance. This optimization isn’t available with all in-
stance types. Additional usage charges apply when using an
EBS Optimized instance.
· SriovNetSupport (string) –
Specifies whether enhanced networking is enabled.
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return.
describe_internet_gateways(**kwargs)
Describes one or more of your Internet gateways.
Request Syntax
response = client.describe_internet_gateways(
DryRun=True|False,
InternetGatewayIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
1252 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InternetGatewayIds (list) – One or more Internet gateway IDs.
Default: Describes all your Internet gateways.
– (string) –
• Filters (list) – One or more filters.
– attachment.state - The current state of the attachment between the
gateway and the VPC (available ). Present only if a VPC is attached.
– attachment.vpc-id - The ID of an attached VPC.
– internet-gateway-id - The ID of the Internet gateway.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'InternetGateways': [
{
'InternetGatewayId': 'string',
'Attachments': [
{
'VpcId': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached'
},
],
'Tags': [
{
'Key': 'string',
3.1. Services 1253
Boto3 Documentation, Release 1.1.4
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– InternetGateways (list) –
Information about one or more Internet gateways.
* (dict) –
Describes an Internet gateway.
· InternetGatewayId (string) –
The ID of the Internet gateway.
· Attachments (list) –
Any VPCs attached to the Internet gateway.
· (dict) –
Describes the attachment of a VPC to an Internet gateway.
· VpcId (string) –
The ID of the VPC.
· State (string) –
The current state of the attachment.
· Tags (list) –
Any tags assigned to the Internet gateway.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
describe_key_pairs(**kwargs)
Describes one or more of your key pairs.
For more information about key pairs, see Key Pairs in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.describe_key_pairs(
DryRun=True|False,
KeyNames=[
'string',
],
Filters=[
1254 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• KeyNames (list) – One or more key pair names.
Default: Describes all your key pairs.
– (string) –
• Filters (list) – One or more filters.
– fingerprint - The fingerprint of the key pair.
– key-name - The name of the key pair.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'KeyPairs': [
{
'KeyName': 'string',
'KeyFingerprint': 'string'
},
]
}
Response Structure
• (dict) –
– KeyPairs (list) –
Information about one or more key pairs.
* (dict) –
Describes a key pair.
· KeyName (string) –
The name of the key pair.
3.1. Services 1255
Boto3 Documentation, Release 1.1.4
· KeyFingerprint (string) –
If you used CreateKeyPair to create the key pair, this is
the SHA-1 digest of the DER encoded private key. If you
used ImportKeyPair to provide AWS the public key, this is
the MD5 public key fingerprint as specified in section 4 of
RFC4716.
describe_moving_addresses(**kwargs)
Describes your Elastic IP addresses that are being moved to the EC2-VPC platform, or that are being
restored to the EC2-Classic platform. This request does not return information about any other Elastic IP
addresses in your account.
Request Syntax
response = client.describe_moving_addresses(
DryRun=True|False,
PublicIps=[
'string',
],
NextToken='string',
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• PublicIps (list) – One or more Elastic IP addresses.
– (string) –
• NextToken (string) – The token to use to retrieve the next page of results.
• Filters (list) – One or more filters.
– moving-status - The status of the Elastic IP address (MovingToVpc
| RestoringToClassic ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
1256 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
between 5 and 1000; if MaxResults is given a value outside of this range, an
error is returned.
Default: If no value is provided, the default is 1000.
Return type dict
Returns
Response Syntax
{
'MovingAddressStatuses': [
{
'PublicIp': 'string',
'MoveStatus': 'movingToVpc'|'restoringToClassic'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– MovingAddressStatuses (list) –
The status for each Elastic IP address.
* (dict) –
Describes the status of a moving Elastic IP address.
· PublicIp (string) –
The Elastic IP address.
· MoveStatus (string) –
The status of the Elastic IP address that’s being moved to the
EC2-VPC platform, or restored to the EC2-Classic platform.
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return.
describe_network_acls(**kwargs)
Describes one or more of your network ACLs.
For more information about network ACLs, see Network ACLs in the Amazon Virtual Private Cloud User
Guide .
Request Syntax
response = client.describe_network_acls(
DryRun=True|False,
NetworkAclIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
3.1. Services 1257
Boto3 Documentation, Release 1.1.4
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkAclIds (list) – One or more network ACL IDs.
Default: Describes all your network ACLs.
– (string) –
• Filters (list) – One or more filters.
– association.association-id - The ID of an association ID for
the ACL.
– association.network-acl-id - The ID of the network ACL in-
volved in the association.
– association.subnet-id - The ID of the subnet involved in the as-
sociation.
– default - Indicates whether the ACL is the default network ACL for the
VPC.
– entry.cidr - The CIDR range specified in the entry.
– entry.egress - Indicates whether the entry applies to egress traffic.
– entry.icmp.code - The ICMP code specified in the entry, if any.
– entry.icmp.type - The ICMP type specified in the entry, if any.
– entry.port-range.from - The start of the port range specified in
the entry.
– entry.port-range.to - The end of the port range specified in the
entry.
– entry.protocol - The protocol specified in the entry (tcp | udp |
icmp or a protocol number).
– entry.rule-action - Allows or denies the matching traffic (allow
| deny ).
– entry.rule-number - The number of an entry (in other words, rule)
in the ACL’s set of entries.
– network-acl-id - The ID of the network ACL.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-id - The ID of the VPC for the network ACL.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
1258 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'NetworkAcls': [
{
'NetworkAclId': 'string',
'VpcId': 'string',
'IsDefault': True|False,
'Entries': [
{
'RuleNumber': 123,
'Protocol': 'string',
'RuleAction': 'allow'|'deny',
'Egress': True|False,
'CidrBlock': 'string',
'IcmpTypeCode': {
'Type': 123,
'Code': 123
},
'PortRange': {
'From': 123,
'To': 123
}
},
],
'Associations': [
{
'NetworkAclAssociationId': 'string',
'NetworkAclId': 'string',
'SubnetId': 'string'
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– NetworkAcls (list) –
Information about one or more network ACLs.
* (dict) –
Describes a network ACL.
· NetworkAclId (string) –
The ID of the network ACL.
· VpcId (string) –
3.1. Services 1259
Boto3 Documentation, Release 1.1.4
The ID of the VPC for the network ACL.
· IsDefault (boolean) –
Indicates whether this is the default network ACL for the
VPC.
· Entries (list) –
One or more entries (rules) in the network ACL.
· (dict) –
Describes an entry in a network ACL.
· RuleNumber (integer) –
The rule number for the entry. ACL entries are processed in
ascending order by rule number.
· Protocol (string) –
The protocol. A value of -1 means all protocols.
· RuleAction (string) –
Indicates whether to allow or deny the traffic that matches the
rule.
· Egress (boolean) –
Indicates whether the rule is an egress rule (applied to traffic
leaving the subnet).
· CidrBlock (string) –
The network range to allow or deny, in CIDR notation.
· IcmpTypeCode (dict) –
ICMP protocol: The ICMP type and code.
· Type (integer) –
The ICMP code. A value of -1 means all codes for the speci-
fied ICMP type.
· Code (integer) –
The ICMP type. A value of -1 means all types.
· PortRange (dict) –
TCP or UDP protocols: The range of ports the rule applies to.
· From (integer) –
The first port in the range.
· To (integer) –
The last port in the range.
· Associations (list) –
Any associations between the network ACL and one or more
subnets
· (dict) –
Describes an association between a network ACL and a sub-
net.
· NetworkAclAssociationId (string) –
The ID of the association between a network ACL and a sub-
net.
· NetworkAclId (string) –
The ID of the network ACL.
1260 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· SubnetId (string) –
The ID of the subnet.
· Tags (list) –
Any tags assigned to the network ACL.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
describe_network_interface_attribute(**kwargs)
Describes a network interface attribute. You can specify only one attribute at a time.
Request Syntax
response = client.describe_network_interface_attribute(
DryRun=True|False,
NetworkInterfaceId='string',
Attribute='description'|'groupSet'|'sourceDestCheck'|'attachment'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkInterfaceId (string) – [REQUIRED]
The ID of the network interface.
• Attribute (string) – The attribute of the network interface.
Return type dict
Returns
Response Syntax
{
'NetworkInterfaceId': 'string',
'Description': {
'Value': 'string'
},
'SourceDestCheck': {
'Value': True|False
},
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
3.1. Services 1261
Boto3 Documentation, Release 1.1.4
'Attachment': {
'AttachmentId': 'string',
'InstanceId': 'string',
'InstanceOwnerId': 'string',
'DeviceIndex': 123,
'Status': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
}
}
Response Structure
• (dict) –
– NetworkInterfaceId (string) –
The ID of the network interface.
– Description (dict) –
The description of the network interface.
* Value (string) –
Valid values are case-sensitive and vary by action.
– SourceDestCheck (dict) –
Indicates whether source/destination checking is enabled.
* Value (boolean) –
Valid values are true or false .
– Groups (list) –
The security groups associated with the network interface.
* (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
– Attachment (dict) –
The attachment (if any) of the network interface.
* AttachmentId (string) –
The ID of the network interface attachment.
* InstanceId (string) –
The ID of the instance.
* InstanceOwnerId (string) –
The AWS account ID of the owner of the instance.
* DeviceIndex (integer) –
The device index of the network interface attachment on the in-
stance.
* Status (string) –
The attachment state.
* AttachTime (datetime) –
The timestamp indicating when the attachment initiated.
1262 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* DeleteOnTermination (boolean) –
Indicates whether the network interface is deleted when the instance
is terminated.
describe_network_interfaces(**kwargs)
Describes one or more of your network interfaces.
Request Syntax
response = client.describe_network_interfaces(
DryRun=True|False,
NetworkInterfaceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkInterfaceIds (list) – One or more network interface IDs.
Default: Describes all your network interfaces.
– (string) –
• Filters (list) – One or more filters.
– addresses.private-ip-address - The private IP addresses asso-
ciated with the network interface.
– addresses.primary - Whether the private IP address is the primary
IP address associated with the network interface.
– addresses.association.public-ip - The association ID re-
turned when the network interface was associated with the Elastic IP ad-
dress.
– addresses.association.owner-id - The owner ID of the ad-
dresses associated with the network interface.
– association.association-id - The association ID returned
when the network interface was associated with an IP address.
– association.allocation-id - The allocation ID returned when
you allocated the Elastic IP address for your network interface.
– association.ip-owner-id - The owner of the Elastic IP address
associated with the network interface.
– association.public-ip - The address of the Elastic IP address
bound to the network interface.
– association.public-dns-name - The public DNS name for the
network interface.
– attachment.attachment-id - The ID of the interface attachment.
– attachment.instance-id - The ID of the instance to which the
network interface is attached.
3.1. Services 1263
Boto3 Documentation, Release 1.1.4
– attachment.instance-owner-id - The owner ID of the instance
to which the network interface is attached.
– attachment.device-index - The device index to which the net-
work interface is attached.
– attachment.status - The status of the attachment (attaching |
attached | detaching | detached ).
– attachment.attach.time - The time that the network interface was
attached to an instance.
– attachment.delete-on-termination - Indicates whether the
attachment is deleted when an instance is terminated.
– availability-zone - The Availability Zone of the network interface.
– description - The description of the network interface.
– group-id - The ID of a security group associated with the network in-
terface.
– group-name - The name of a security group associated with the network
interface.
– mac-address - The MAC address of the network interface.
– network-interface-id - The ID of the network interface.
– owner-id - The AWS account ID of the network interface owner.
– private-ip-address - The private IP address or addresses of the
network interface.
– private-dns-name - The private DNS name of the network interface.
– requester-id - The ID of the entity that launched the instance on
your behalf (for example, AWS Management Console, Auto Scaling, and
so on).
– requester-managed - Indicates whether the network interface is be-
ing managed by an AWS service (for example, AWS Management Con-
sole, Auto Scaling, and so on).
– source-desk-check - Indicates whether the network interface per-
forms source/destination checking. A value of true means checking
is enabled, and false means checking is disabled. The value must be
false for the network interface to perform Network Address Translation
(NAT) in your VPC.
– status - The status of the network interface. If the network interface
is not attached to an instance, the status is available ; if a network
interface is attached to an instance the status is in-use .
– subnet-id - The ID of the subnet for the network interface.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-id - The ID of the VPC for the network interface.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
1264 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'SubnetId': 'string',
'VpcId': 'string',
'AvailabilityZone': 'string',
'Description': 'string',
'OwnerId': 'string',
'RequesterId': 'string',
'RequesterManaged': True|False,
'Status': 'available'|'attaching'|'in-use'|'detaching',
'MacAddress': 'string',
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'SourceDestCheck': True|False,
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'Attachment': {
'AttachmentId': 'string',
'InstanceId': 'string',
'InstanceOwnerId': 'string',
'DeviceIndex': 123,
'Status': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
},
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string',
'AllocationId': 'string',
'AssociationId': 'string'
},
'TagSet': [
{
'Key': 'string',
'Value': 'string'
},
],
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'Primary': True|False,
3.1. Services 1265
Boto3 Documentation, Release 1.1.4
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string',
'AllocationId': 'string',
'AssociationId': 'string'
}
},
]
},
]
}
Response Structure
• (dict) –
– NetworkInterfaces (list) –
Information about one or more network interfaces.
* (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· SubnetId (string) –
The ID of the subnet.
· VpcId (string) –
The ID of the VPC.
· AvailabilityZone (string) –
The Availability Zone.
· Description (string) –
A description.
· OwnerId (string) –
The AWS account ID of the owner of the network interface.
· RequesterId (string) –
The ID of the entity that launched the instance on your behalf
(for example, AWS Management Console or Auto Scaling).
· RequesterManaged (boolean) –
Indicates whether the network interface is being managed by
AWS.
· Status (string) –
The status of the network interface.
· MacAddress (string) –
The MAC address.
· PrivateIpAddress (string) –
The IP address of the network interface within the subnet.
· PrivateDnsName (string) –
The private DNS name.
· SourceDestCheck (boolean) –
Indicates whether traffic to or from the instance is validated.
1266 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Groups (list) –
Any security groups for the network interface.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· Attachment (dict) –
The network interface attachment.
· AttachmentId (string) –
The ID of the network interface attachment.
· InstanceId (string) –
The ID of the instance.
· InstanceOwnerId (string) –
The AWS account ID of the owner of the instance.
· DeviceIndex (integer) –
The device index of the network interface attachment on the
instance.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The timestamp indicating when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the network interface is deleted when the
instance is terminated.
· Association (dict) –
The association information for an Elastic IP associated with
the network interface.
· PublicIp (string) –
The address of the Elastic IP address bound to the network
interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the Elastic IP address owner.
· AllocationId (string) –
The allocation ID.
· AssociationId (string) –
The association ID.
· TagSet (list) –
Any tags assigned to the network interface.
· (dict) –
Describes a tag.
3.1. Services 1267
Boto3 Documentation, Release 1.1.4
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· PrivateIpAddresses (list) –
The private IP addresses associated with the network inter-
face.
· (dict) –
Describes the private IP address of a network interface.
· PrivateIpAddress (string) –
The private IP address.
· PrivateDnsName (string) –
The private DNS name.
· Primary (boolean) –
Indicates whether this IP address is the primary private IP ad-
dress of the network interface.
· Association (dict) –
The association information for an Elastic IP address associ-
ated with the network interface.
· PublicIp (string) –
The address of the Elastic IP address bound to the network
interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the Elastic IP address owner.
· AllocationId (string) –
The allocation ID.
· AssociationId (string) –
The association ID.
describe_placement_groups(**kwargs)
Describes one or more of your placement groups. For more information about placement groups and
cluster instances, see Cluster Instances in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.describe_placement_groups(
DryRun=True|False,
GroupNames=[
'string',
],
Filters=[
{
1268 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupNames (list) – One or more placement group names.
Default: Describes all your placement groups, or only those otherwise specified.
– (string) –
• Filters (list) – One or more filters.
– group-name - The name of the placement group.
– state - The state of the placement group (pending | available |
deleting | deleted ).
– strategy - The strategy of the placement group (cluster ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'PlacementGroups': [
{
'GroupName': 'string',
'Strategy': 'cluster',
'State': 'pending'|'available'|'deleting'|'deleted'
},
]
}
Response Structure
• (dict) –
– PlacementGroups (list) –
One or more placement groups.
* (dict) –
Describes a placement group.
3.1. Services 1269
Boto3 Documentation, Release 1.1.4
· GroupName (string) –
The name of the placement group.
· Strategy (string) –
The placement strategy.
· State (string) –
The state of the placement group.
describe_prefix_lists(**kwargs)
Describes available AWS services in a prefix list format, which includes the prefix list name and prefix
list ID of the service and the IP address range for the service. A prefix list ID is required for creating an
outbound security group rule that allows traffic from a VPC to access an AWS service through a VPC
endpoint.
Request Syntax
response = client.describe_prefix_lists(
DryRun=True|False,
PrefixListIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
MaxResults=123,
NextToken='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• PrefixListIds (list) – One or more prefix list IDs.
– (string) –
• Filters (list) – One or more filters.
– prefix-list-id : The ID of a prefix list.
– prefix-list-name : The name of a prefix list.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
1270 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• MaxResults (integer) – The maximum number of items to return for this request.
The request returns a token that you can specify in a subsequent call to get the
next set of results.
Constraint: If the value specified is greater than 1000, we return only 1000 items.
• NextToken (string) – The token for the next set of items to return. (You received
this token from a prior call.)
Return type dict
Returns
Response Syntax
{
'PrefixLists': [
{
'PrefixListId': 'string',
'PrefixListName': 'string',
'Cidrs': [
'string',
]
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– PrefixLists (list) –
All available prefix lists.
* (dict) –
Describes prefixes for AWS services.
· PrefixListId (string) –
The ID of the prefix.
· PrefixListName (string) –
The name of the prefix.
· Cidrs (list) –
The IP address range of the AWS service.
· (string) –
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_regions(**kwargs)
Describes one or more regions that are currently available to you.
For a list of the regions supported by Amazon EC2, see Regions and Endpoints .
Request Syntax
response = client.describe_regions(
DryRun=True|False,
RegionNames=[
'string',
],
Filters=[
3.1. Services 1271
Boto3 Documentation, Release 1.1.4
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• RegionNames (list) – The names of one or more regions.
– (string) –
• Filters (list) – One or more filters.
– endpoint - The endpoint of the region (for example,
ec2.us-east-1.amazonaws.com ).
– region-name - The name of the region (for example, us-east-1 ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'Regions': [
{
'RegionName': 'string',
'Endpoint': 'string'
},
]
}
Response Structure
• (dict) –
– Regions (list) –
Information about one or more regions.
* (dict) –
Describes a region.
· RegionName (string) –
The name of the region.
1272 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Endpoint (string) –
The region service endpoint.
describe_reserved_instances(**kwargs)
Describes one or more of the Reserved Instances that you purchased.
For more information about Reserved Instances, see Reserved Instances in the Amazon Elastic Compute
Cloud User Guide .
Request Syntax
response = client.describe_reserved_instances(
DryRun=True|False,
ReservedInstancesIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
OfferingType='Heavy Utilization'|'Medium Utilization'|'Light Utilization'|'No Upfront'|'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ReservedInstancesIds (list) – One or more Reserved Instance IDs.
Default: Describes all your Reserved Instances, or only those otherwise speci-
fied.
– (string) –
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone where the Reserved In-
stance can be used.
– duration - The duration of the Reserved Instance (one year or three
years), in seconds (31536000 | 94608000 ).
– end - The time when the Reserved Instance expires (for example, 2015-
08-07T11:54:42.000Z).
– fixed-price - The purchase price of the Reserved Instance (for exam-
ple, 9800.0).
– instance-type - The instance type on which the Reserved Instance
can be used.
– product-description - The Reserved Instance product platform
description. Instances that include (Amazon VPC) in the product plat-
form description will only be displayed to EC2-Classic account holders
and are for use with Amazon VPC. (Linux/UNIX | Linux/UNIX
(Amazon VPC) | SUSE Linux | SUSE Linux (Amazon VPC) |
Red Hat Enterprise Linux | Red Hat Enterprise Linux
(Amazon VPC) | Windows | Windows (Amazon VPC) | Windows
with SQL Server Standard | Windows with SQL Server
Standard (Amazon VPC) | Windows with SQL Server
3.1. Services 1273
Boto3 Documentation, Release 1.1.4
Web | Windows with SQL Server Web (Amazon VPC) |
Windows with SQL Server Enterprise | Windows with
SQL Server Enterprise (Amazon VPC) ).
– reserved-instances-id - The ID of the Reserved Instance.
– start - The time at which the Reserved Instance purchase request was
placed (for example, 2014-08-07T11:54:42.000Z).
– state - The state of the Reserved Instance (payment-pending |
active | payment-failed | retired ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– usage-price - The usage price of the Reserved Instance, per hour (for
example, 0.84).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• OfferingType (string) – The Reserved Instance offering type. If you are us-
ing tools that predate the 2011-11-01 API version, you only have access to the
Medium Utilization Reserved Instance offering type.
Return type dict
Returns
Response Syntax
{
'ReservedInstances': [
{
'ReservedInstancesId': 'string',
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarg
'AvailabilityZone': 'string',
'Start': datetime(2015, 1, 1),
'End': datetime(2015, 1, 1),
'Duration': 123,
'UsagePrice': ...,
'FixedPrice': ...,
'InstanceCount': 123,
'ProductDescription': 'Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'
'State': 'payment-pending'|'active'|'payment-failed'|'retired',
'Tags': [
{
1274 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Key': 'string',
'Value': 'string'
},
],
'InstanceTenancy': 'default'|'dedicated',
'CurrencyCode': 'USD',
'OfferingType': 'Heavy Utilization'|'Medium Utilization'|'Light Utiliz
'RecurringCharges': [
{
'Frequency': 'Hourly',
'Amount': 123.0
},
]
},
]
}
Response Structure
• (dict) –
– ReservedInstances (list) –
A list of Reserved Instances.
* (dict) –
Describes a Reserved Instance.
· ReservedInstancesId (string) –
The ID of the Reserved Instance.
· InstanceType (string) –
The instance type on which the Reserved Instance can be
used.
· AvailabilityZone (string) –
The Availability Zone in which the Reserved Instance can be
used.
· Start (datetime) –
The date and time the Reserved Instance started.
· End (datetime) –
The time when the Reserved Instance expires.
· Duration (integer) –
The duration of the Reserved Instance, in seconds.
· UsagePrice (float) –
The usage price of the Reserved Instance, per hour.
· FixedPrice (float) –
The purchase price of the Reserved Instance.
· InstanceCount (integer) –
The number of Reserved Instances purchased.
· ProductDescription (string) –
The Reserved Instance product platform description.
· State (string) –
The state of the Reserved Instance purchase.
· Tags (list) –
3.1. Services 1275
Boto3 Documentation, Release 1.1.4
Any tags assigned to the resource.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· InstanceTenancy (string) –
The tenancy of the reserved instance.
· CurrencyCode (string) –
The currency of the Reserved Instance. It’s specified using
ISO 4217 standard currency codes. At this time, the only
supported currency is USD .
· OfferingType (string) –
The Reserved Instance offering type.
· RecurringCharges (list) –
The recurring charge tag assigned to the resource.
· (dict) –
Describes a recurring charge.
· Frequency (string) –
The frequency of the recurring charge.
· Amount (float) –
The amount of the recurring charge.
describe_reserved_instances_listings(**kwargs)
Describes your account’s Reserved Instance listings in the Reserved Instance Marketplace.
The Reserved Instance Marketplace matches sellers who want to resell Reserved Instance capacity that
they no longer need with buyers who want to purchase additional capacity. Reserved Instances bought
and sold through the Reserved Instance Marketplace work like any other Reserved Instances.
As a seller, you choose to list some or all of your Reserved Instances, and you specify the upfront price to
receive for them. Your Reserved Instances are then listed in the Reserved Instance Marketplace and are
available for purchase.
As a buyer, you specify the configuration of the Reserved Instance to purchase, and the Marketplace
matches what you’re searching for with what’s available. The Marketplace first sells the lowest priced
Reserved Instances to you, and continues to sell available Reserved Instance listings to you until your
demand is met. You are charged based on the total price of all of the listings that you purchase.
For more information, see Reserved Instance Marketplace in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
1276 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.describe_reserved_instances_listings(
ReservedInstancesId='string',
ReservedInstancesListingId='string',
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• ReservedInstancesId (string) – One or more Reserved Instance IDs.
• ReservedInstancesListingId (string) – One or more Reserved Instance Listing
IDs.
• Filters (list) – One or more filters.
– reserved-instances-id - The ID of the Reserved Instances.
– reserved-instances-listing-id - The ID of the Reserved In-
stances listing.
– status - The status of the Reserved Instance listing (pending |
active | cancelled | closed ).
– status-message - The reason for the status.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'ReservedInstancesListings': [
{
'ReservedInstancesListingId': 'string',
'ReservedInstancesId': 'string',
'CreateDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'Status': 'active'|'pending'|'cancelled'|'closed',
'StatusMessage': 'string',
'InstanceCounts': [
{
'State': 'available'|'sold'|'cancelled'|'pending',
'InstanceCount': 123
},
],
'PriceSchedules': [
3.1. Services 1277
Boto3 Documentation, Release 1.1.4
{
'Term': 123,
'Price': 123.0,
'CurrencyCode': 'USD',
'Active': True|False
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'ClientToken': 'string'
},
]
}
Response Structure
• (dict) –
– ReservedInstancesListings (list) –
Information about the Reserved Instance listing.
* (dict) –
Describes a Reserved Instance listing.
· ReservedInstancesListingId (string) –
The ID of the Reserved Instance listing.
· ReservedInstancesId (string) –
The ID of the Reserved Instance.
· CreateDate (datetime) –
The time the listing was created.
· UpdateDate (datetime) –
The last modified timestamp of the listing.
· Status (string) –
The status of the Reserved Instance listing.
· StatusMessage (string) –
The reason for the current status of the Reserved Instance list-
ing. The response can be blank.
· InstanceCounts (list) –
The number of instances in this state.
· (dict) –
Describes a Reserved Instance listing state.
· State (string) –
The states of the listed Reserved Instances.
· InstanceCount (integer) –
The number of listed Reserved Instances in the state specified
by the state .
· PriceSchedules (list) –
The price of the Reserved Instance listing.
1278 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes the price for a Reserved Instance.
· Term (integer) –
The number of months remaining in the reservation. For ex-
ample, 2 is the second to the last month before the capacity
reservation expires.
· Price (float) –
The fixed price for the term.
· CurrencyCode (string) –
The currency for transacting the Reserved Instance resale. At
this time, the only supported currency is USD .
· Active (boolean) –
The current price schedule, as determined by the term remain-
ing for the Reserved Instance in the listing.
A specific price schedule is always in effect, but only one
price schedule can be active at any time. Take, for exam-
ple, a Reserved Instance listing that has five months remain-
ing in its term. When you specify price schedules for five
months and two months, this means that schedule 1, covering
the first three months of the remaining term, will be active
during months 5, 4, and 3. Then schedule 2, covering the last
two months of the term, will be active for months 2 and 1.
· Tags (list) –
Any tags assigned to the resource.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· ClientToken (string) –
A unique, case-sensitive key supplied by the client to ensure
that the request is idempotent. For more information, see En-
suring Idempotency .
describe_reserved_instances_modifications(**kwargs)
Describes the modifications made to your Reserved Instances. If no parameter is specified, information
about all your Reserved Instances modification requests is returned. If a modification ID is specified, only
information about the specific modification is returned.
For more information, see Modifying Reserved Instances in the Amazon Elastic Compute Cloud User
Guide.
Request Syntax
3.1. Services 1279
Boto3 Documentation, Release 1.1.4
response = client.describe_reserved_instances_modifications(
ReservedInstancesModificationIds=[
'string',
],
NextToken='string',
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• ReservedInstancesModificationIds (list) – IDs for the submitted modification
request.
– (string) –
• NextToken (string) – The token to retrieve the next page of results.
• Filters (list) – One or more filters.
– client-token - The idempotency token for the modification request.
– create-date - The time when the modification request was created.
– effective-date - The time when the modification becomes effective.
– modification-result.reserved-instances-id - The ID for
the Reserved Instances created as part of the modification request. This ID
is only available when the status of the modification is fulfilled .
– modification-result.target-configuration.availability-zone
- The Availability Zone for the new Reserved Instances.
– modification-result.target-configuration.instance-count
- The number of new Reserved Instances.
– modification-result.target-configuration.instance-type
- The instance type of the new Reserved Instances.
– modification-result.target-configuration.platform
- The network platform of the new Reserved Instances (EC2-Classic |
EC2-VPC ).
– reserved-instances-id - The ID of the Reserved Instances modi-
fied.
– reserved-instances-modification-id - The ID of the modi-
fication request.
– status - The status of the Reserved Instances modification request
(processing | fulfilled | failed ).
– status-message - The reason for the status.
– update-date - The time when the modification request was last up-
dated.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
1280 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'ReservedInstancesModifications': [
{
'ReservedInstancesModificationId': 'string',
'ReservedInstancesIds': [
{
'ReservedInstancesId': 'string'
},
],
'ModificationResults': [
{
'ReservedInstancesId': 'string',
'TargetConfiguration': {
'AvailabilityZone': 'string',
'Platform': 'string',
'InstanceCount': 123,
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.larg
}
},
],
'CreateDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'EffectiveDate': datetime(2015, 1, 1),
'Status': 'string',
'StatusMessage': 'string',
'ClientToken': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– ReservedInstancesModifications (list) –
The Reserved Instance modification information.
* (dict) –
Describes a Reserved Instance modification.
· ReservedInstancesModificationId (string) –
A unique ID for the Reserved Instance modification.
· ReservedInstancesIds (list) –
The IDs of one or more Reserved Instances.
· (dict) –
Describes the ID of a Reserved Instance.
· ReservedInstancesId (string) –
The ID of the Reserved Instance.
· ModificationResults (list) –
3.1. Services 1281
Boto3 Documentation, Release 1.1.4
Contains target configurations along with their corresponding
new Reserved Instance IDs.
· (dict) –
· ReservedInstancesId (string) –
The ID for the Reserved Instances that were created as part of
the modification request. This field is only available when the
modification is fulfilled.
· TargetConfiguration (dict) –
The target Reserved Instances configurations supplied as part
of the modification request.
· AvailabilityZone (string) –
The Availability Zone for the modified Reserved Instances.
· Platform (string) –
The network platform of the modified Reserved Instances,
which is either EC2-Classic or EC2-VPC.
· InstanceCount (integer) –
The number of modified Reserved Instances.
· InstanceType (string) –
The instance type for the modified Reserved Instances.
· CreateDate (datetime) –
The time when the modification request was created.
· UpdateDate (datetime) –
The time when the modification request was last updated.
· EffectiveDate (datetime) –
The time for the modification to become effective.
· Status (string) –
The status of the Reserved Instances modification request.
· StatusMessage (string) –
The reason for the status.
· ClientToken (string) –
A unique, case-sensitive key supplied by the client to ensure
that the request is idempotent. For more information, see En-
suring Idempotency .
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return.
describe_reserved_instances_offerings(**kwargs)
Describes Reserved Instance offerings that are available for purchase. With Reserved Instances, you
purchase the right to launch instances for a period of time. During that time period, you do not receive
insufficient capacity errors, and you pay a lower usage rate than the rate charged for On-Demand instances
for the actual time used.
For more information, see Reserved Instance Marketplace in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
1282 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.describe_reserved_instances_offerings(
DryRun=True|False,
ReservedInstancesOfferingIds=[
'string',
],
InstanceType='t1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.medium'|'m3.la
AvailabilityZone='string',
ProductDescription='Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'|'Windows (Amazon VPC
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
InstanceTenancy='default'|'dedicated',
OfferingType='Heavy Utilization'|'Medium Utilization'|'Light Utilization'|'No Upfront'|'
NextToken='string',
MaxResults=123,
IncludeMarketplace=True|False,
MinDuration=123,
MaxDuration=123,
MaxInstanceCount=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ReservedInstancesOfferingIds (list) – One or more Reserved Instances offer-
ing IDs.
– (string) –
• InstanceType (string) – The instance type on which the Reserved Instance can
be used. For more information, see Instance Types in the Amazon Elastic Com-
pute Cloud User Guide .
• AvailabilityZone (string) – The Availability Zone in which the Reserved In-
stance can be used.
• ProductDescription (string) – The Reserved Instance product platform descrip-
tion. Instances that include (Amazon VPC) in the description are for use with
Amazon VPC.
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone where the Reserved In-
stance can be used.
– duration - The duration of the Reserved Instance (for example, one
year or three years), in seconds (31536000 | 94608000 ).
– fixed-price - The purchase price of the Reserved Instance (for exam-
ple, 9800.0).
– instance-type - The instance type on which the Reserved Instance
can be used.
– marketplace - Set to true to show only Reserved Instance Market-
place offerings. When this filter is not used, which is the default behavior,
all offerings from AWS and Reserved Instance Marketplace are listed.
– product-description - The Reserved Instance product platform
3.1. Services 1283
Boto3 Documentation, Release 1.1.4
description. Instances that include (Amazon VPC) in the product plat-
form description will only be displayed to EC2-Classic account holders
and are for use with Amazon VPC. (Linux/UNIX | Linux/UNIX
(Amazon VPC) | SUSE Linux | SUSE Linux (Amazon VPC) |
Red Hat Enterprise Linux | Red Hat Enterprise Linux
(Amazon VPC) | Windows | Windows (Amazon VPC) | Windows
with SQL Server Standard | Windows with SQL Server
Standard (Amazon VPC) | Windows with SQL Server
Web | Windows with SQL Server Web (Amazon VPC) |
Windows with SQL Server Enterprise | Windows with
SQL Server Enterprise (Amazon VPC) )
– reserved-instances-offering-id - The Reserved Instances of-
fering ID.
– usage-price - The usage price of the Reserved Instance, per hour (for
example, 0.84).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• InstanceTenancy (string) – The tenancy of the Reserved Instance offering. A
Reserved Instance with dedicated tenancy runs on single-tenant hardware
and can only be launched within a VPC.
Default: default
• OfferingType (string) – The Reserved Instance offering type. If you are us-
ing tools that predate the 2011-11-01 API version, you only have access to the
Medium Utilization Reserved Instance offering type.
• NextToken (string) – The token to retrieve the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. The maximum is
100.
Default: 100
• IncludeMarketplace (boolean) – Include Marketplace offerings in the response.
• MinDuration (integer) – The minimum duration (in seconds) to filter when
searching for offerings.
Default: 2592000 (1 month)
• MaxDuration (integer) – The maximum duration (in seconds) to filter when
searching for offerings.
Default: 94608000 (3 years)
• MaxInstanceCount (integer) – The maximum number of instances to filter
when searching for offerings.
Default: 20
Return type dict
Returns
1284 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Response Syntax
{
'ReservedInstancesOfferings': [
{
'ReservedInstancesOfferingId': 'string',
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarg
'AvailabilityZone': 'string',
'Duration': 123,
'UsagePrice': ...,
'FixedPrice': ...,
'ProductDescription': 'Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'
'InstanceTenancy': 'default'|'dedicated',
'CurrencyCode': 'USD',
'OfferingType': 'Heavy Utilization'|'Medium Utilization'|'Light Utiliz
'RecurringCharges': [
{
'Frequency': 'Hourly',
'Amount': 123.0
},
],
'Marketplace': True|False,
'PricingDetails': [
{
'Price': 123.0,
'Count': 123
},
]
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– ReservedInstancesOfferings (list) –
A list of Reserved Instances offerings.
* (dict) –
Describes a Reserved Instance offering.
· ReservedInstancesOfferingId (string) –
The ID of the Reserved Instance offering.
· InstanceType (string) –
The instance type on which the Reserved Instance can be
used.
· AvailabilityZone (string) –
The Availability Zone in which the Reserved Instance can be
used.
· Duration (integer) –
The duration of the Reserved Instance, in seconds.
· UsagePrice (float) –
The usage price of the Reserved Instance, per hour.
· FixedPrice (float) –
3.1. Services 1285
Boto3 Documentation, Release 1.1.4
The purchase price of the Reserved Instance.
· ProductDescription (string) –
The Reserved Instance product platform description.
· InstanceTenancy (string) –
The tenancy of the reserved instance.
· CurrencyCode (string) –
The currency of the Reserved Instance offering you are pur-
chasing. It’s specified using ISO 4217 standard currency
codes. At this time, the only supported currency is USD .
· OfferingType (string) –
The Reserved Instance offering type.
· RecurringCharges (list) –
The recurring charge tag assigned to the resource.
· (dict) –
Describes a recurring charge.
· Frequency (string) –
The frequency of the recurring charge.
· Amount (float) –
The amount of the recurring charge.
· Marketplace (boolean) –
Indicates whether the offering is available through the Re-
served Instance Marketplace (resale) or AWS. If it’s a Re-
served Instance Marketplace offering, this is true .
· PricingDetails (list) –
The pricing details of the Reserved Instance offering.
· (dict) –
Describes a Reserved Instance offering.
· Price (float) –
The price per instance.
· Count (integer) –
The number of instances available for the price.
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return.
describe_route_tables(**kwargs)
Describes one or more of your route tables.
Each subnet in your VPC must be associated with a route table. If a subnet is not explicitly associated
with any route table, it is implicitly associated with the main route table. This command does not return
the subnet ID for implicit associations.
For more information about route tables, see Route Tables in the Amazon Virtual Private Cloud User
Guide .
Request Syntax
1286 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.describe_route_tables(
DryRun=True|False,
RouteTableIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• RouteTableIds (list) – One or more route table IDs.
Default: Describes all your route tables.
– (string) –
• Filters (list) – One or more filters.
– association.route-table-association-id - The ID of an
association ID for the route table.
– association.route-table-id - The ID of the route table in-
volved in the association.
– association.subnet-id - The ID of the subnet involved in the as-
sociation.
– association.main - Indicates whether the route table is the main
route table for the VPC.
– route-table-id - The ID of the route table.
– route.destination-cidr-block - The CIDR range specified in
a route in the table.
– route.destination-prefix-list-id - The ID (prefix) of the
AWS service specified in a route in the table.
– route.gateway-id - The ID of a gateway specified in a route in the
table.
– route.instance-id - The ID of an instance specified in a route in
the table.
– route.origin - Describes how the route was created.
CreateRouteTable indicates that the route was automati-
cally created when the route table was created; CreateRoute
indicates that the route was manually added to the route table;
EnableVgwRoutePropagation indicates that the route was
propagated by route propagation.
– route.state - The state of a route in the route table (active |
blackhole ). The blackhole state indicates that the route’s target isn’t
available (for example, the specified gateway isn’t attached to the VPC,
the specified NAT instance has been terminated, and so on).
– route.vpc-peering-connection-id - The ID of a VPC peering
connection specified in a route in the table.
– tag :key =*value* - The key/value combination of a tag assigned to the
3.1. Services 1287
Boto3 Documentation, Release 1.1.4
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-id - The ID of the VPC for the route table.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'RouteTables': [
{
'RouteTableId': 'string',
'VpcId': 'string',
'Routes': [
{
'DestinationCidrBlock': 'string',
'DestinationPrefixListId': 'string',
'GatewayId': 'string',
'InstanceId': 'string',
'InstanceOwnerId': 'string',
'NetworkInterfaceId': 'string',
'VpcPeeringConnectionId': 'string',
'State': 'active'|'blackhole',
'Origin': 'CreateRouteTable'|'CreateRoute'|'EnableVgwRouteProp
},
],
'Associations': [
{
'RouteTableAssociationId': 'string',
'RouteTableId': 'string',
'SubnetId': 'string',
'Main': True|False
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
1288 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'PropagatingVgws': [
{
'GatewayId': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– RouteTables (list) –
Information about one or more route tables.
* (dict) –
Describes a route table.
· RouteTableId (string) –
The ID of the route table.
· VpcId (string) –
The ID of the VPC.
· Routes (list) –
The routes in the route table.
· (dict) –
Describes a route in a route table.
· DestinationCidrBlock (string) –
The CIDR block used for the destination match.
· DestinationPrefixListId (string) –
The prefix of the AWS service.
· GatewayId (string) –
The ID of a gateway attached to your VPC.
· InstanceId (string) –
The ID of a NAT instance in your VPC.
· InstanceOwnerId (string) –
The AWS account ID of the owner of the instance.
· NetworkInterfaceId (string) –
The ID of the network interface.
· VpcPeeringConnectionId (string) –
The ID of the VPC peering connection.
· State (string) –
The state of the route. The blackhole state indicates that
the route’s target isn’t available (for example, the specified
gateway isn’t attached to the VPC, or the specified NAT in-
stance has been terminated).
· Origin (string) –
Describes how the route was created.
· CreateRouteTable indicates that route was automati-
cally created when the route table was created.
3.1. Services 1289
Boto3 Documentation, Release 1.1.4
· CreateRoute indicates that the route was manually added
to the route table.
· EnableVgwRoutePropagation indicates that the route
was propagated by route propagation.
· Associations (list) –
The associations between the route table and one or more sub-
nets.
· (dict) –
Describes an association between a route table and a subnet.
· RouteTableAssociationId (string) –
The ID of the association between a route table and a subnet.
· RouteTableId (string) –
The ID of the route table.
· SubnetId (string) –
The ID of the subnet. A subnet ID is not returned for an im-
plicit association.
· Main (boolean) –
Indicates whether this is the main route table.
· Tags (list) –
Any tags assigned to the route table.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· PropagatingVgws (list) –
Any virtual private gateway (VGW) propagating routes.
· (dict) –
Describes a virtual private gateway propagating route.
· GatewayId (string) –
The ID of the virtual private gateway (VGW).
describe_security_groups(**kwargs)
Describes one or more of your security groups.
A security group is for use with instances either in the EC2-Classic platform or in a specific VPC. For
more information, see Amazon EC2 Security Groups in the Amazon Elastic Compute Cloud User Guide
and Security Groups for Your VPC in the Amazon Virtual Private Cloud User Guide .
Request Syntax
1290 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.describe_security_groups(
DryRun=True|False,
GroupNames=[
'string',
],
GroupIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupNames (list) – [EC2-Classic and default VPC only] One or more security
group names. You can specify either the security group name or the security
group ID. For security groups in a nondefault VPC, use the group-name filter
to describe security groups by name.
Default: Describes all your security groups.
– (string) –
• GroupIds (list) – One or more security group IDs. Required for security groups
in a nondefault VPC.
Default: Describes all your security groups.
– (string) –
• Filters (list) – One or more filters. If using multiple filters for rules, the results
include security groups for which any combination of rules - not necessarily a
single rule - match all filters.
– description - The description of the security group.
– egress.ip-permission.prefix-list-id - The ID (prefix) of
the AWS service to which the security group allows access.
– group-id - The ID of the security group.
– group-name - The name of the security group.
– ip-permission.cidr - A CIDR range that has been granted permis-
sion.
– ip-permission.from-port - The start of port range for the TCP
and UDP protocols, or an ICMP type number.
– ip-permission.group-id - The ID of a security group that has
been granted permission.
– ip-permission.group-name - The name of a security group that
has been granted permission.
– ip-permission.protocol - The IP protocol for the permission
(tcp | udp | icmp or a protocol number).
– ip-permission.to-port - The end of port range for the TCP and
UDP protocols, or an ICMP code.
– ip-permission.user-id - The ID of an AWS account that has been
3.1. Services 1291
Boto3 Documentation, Release 1.1.4
granted permission.
– owner-id - The AWS account ID of the owner of the security group.
– tag-key - The key of a tag assigned to the security group.
– tag-value - The value of a tag assigned to the security group.
– vpc-id - The ID of the VPC specified when the security group was cre-
ated.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'SecurityGroups': [
{
'OwnerId': 'string',
'GroupName': 'string',
'GroupId': 'string',
'Description': 'string',
'IpPermissions': [
{
'IpProtocol': 'string',
'FromPort': 123,
'ToPort': 123,
'UserIdGroupPairs': [
{
'UserId': 'string',
'GroupName': 'string',
'GroupId': 'string'
},
],
'IpRanges': [
{
'CidrIp': 'string'
},
],
'PrefixListIds': [
{
'PrefixListId': 'string'
},
]
},
],
'IpPermissionsEgress': [
{
'IpProtocol': 'string',
'FromPort': 123,
1292 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'ToPort': 123,
'UserIdGroupPairs': [
{
'UserId': 'string',
'GroupName': 'string',
'GroupId': 'string'
},
],
'IpRanges': [
{
'CidrIp': 'string'
},
],
'PrefixListIds': [
{
'PrefixListId': 'string'
},
]
},
],
'VpcId': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– SecurityGroups (list) –
Information about one or more security groups.
* (dict) –
Describes a security group
· OwnerId (string) –
The AWS account ID of the owner of the security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· Description (string) –
A description of the security group.
· IpPermissions (list) –
One or more inbound rules associated with the security group.
· (dict) –
Describes a security group rule.
· IpProtocol (string) –
The protocol.
3.1. Services 1293
Boto3 Documentation, Release 1.1.4
When you call DescribeSecurityGroups , the protocol value
returned is the number. Exception: For TCP, UDP, and ICMP,
the value returned is the name (for example, tcp , udp , or
icmp ). For a list of protocol numbers, see Protocol Numbers
. (VPC only) When you call AuthorizeSecurityGroupIngress
, you can use -1 to specify all.
· FromPort (integer) –
The start of port range for the TCP and UDP protocols, or an
ICMP type number. A value of -1 indicates all ICMP types.
· ToPort (integer) –
The end of port range for the TCP and UDP protocols, or an
ICMP code. A value of -1 indicates all ICMP codes for the
specified ICMP type.
· UserIdGroupPairs (list) –
One or more security group and AWS account ID pairs.
· (dict) –
Describes a security group and AWS account ID pair.
· UserId (string) –
The ID of an AWS account. EC2-Classic only.
· GroupName (string) –
The name of the security group. In a request, use this parame-
ter for a security group in EC2-Classic or a default VPC only.
For a security group in a nondefault VPC, use GroupId .
· GroupId (string) –
The ID of the security group.
· IpRanges (list) –
One or more IP ranges.
· (dict) –
Describes an IP range.
· CidrIp (string) –
The CIDR range. You can either specify a CIDR range or a
source security group, not both.
· PrefixListIds (list) –
(Valid for AuthorizeSecurityGroupEgress , RevokeSecurity-
GroupEgress and DescribeSecurityGroups only) One or more
prefix list IDs for an AWS service. In an AuthorizeSecurity-
GroupEgress request, this is the AWS service that you want
to access through a VPC endpoint from instances associated
with the security group.
· (dict) –
The ID of the prefix.
· PrefixListId (string) –
The ID of the prefix.
· IpPermissionsEgress (list) –
[EC2-VPC] One or more outbound rules associated with the
security group.
1294 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes a security group rule.
· IpProtocol (string) –
The protocol.
When you call DescribeSecurityGroups , the protocol value
returned is the number. Exception: For TCP, UDP, and ICMP,
the value returned is the name (for example, tcp , udp , or
icmp ). For a list of protocol numbers, see Protocol Numbers
. (VPC only) When you call AuthorizeSecurityGroupIngress
, you can use -1 to specify all.
· FromPort (integer) –
The start of port range for the TCP and UDP protocols, or an
ICMP type number. A value of -1 indicates all ICMP types.
· ToPort (integer) –
The end of port range for the TCP and UDP protocols, or an
ICMP code. A value of -1 indicates all ICMP codes for the
specified ICMP type.
· UserIdGroupPairs (list) –
One or more security group and AWS account ID pairs.
· (dict) –
Describes a security group and AWS account ID pair.
· UserId (string) –
The ID of an AWS account. EC2-Classic only.
· GroupName (string) –
The name of the security group. In a request, use this parame-
ter for a security group in EC2-Classic or a default VPC only.
For a security group in a nondefault VPC, use GroupId .
· GroupId (string) –
The ID of the security group.
· IpRanges (list) –
One or more IP ranges.
· (dict) –
Describes an IP range.
· CidrIp (string) –
The CIDR range. You can either specify a CIDR range or a
source security group, not both.
· PrefixListIds (list) –
(Valid for AuthorizeSecurityGroupEgress , RevokeSecurity-
GroupEgress and DescribeSecurityGroups only) One or more
prefix list IDs for an AWS service. In an AuthorizeSecurity-
GroupEgress request, this is the AWS service that you want
to access through a VPC endpoint from instances associated
with the security group.
· (dict) –
The ID of the prefix.
3.1. Services 1295
Boto3 Documentation, Release 1.1.4
· PrefixListId (string) –
The ID of the prefix.
· VpcId (string) –
[EC2-VPC] The ID of the VPC for the security group.
· Tags (list) –
Any tags assigned to the security group.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
describe_snapshot_attribute(**kwargs)
Describes the specified attribute of the specified snapshot. You can specify only one attribute at a time.
For more information about EBS snapshots, see Amazon EBS Snapshots in the Amazon Elastic Compute
Cloud User Guide .
Request Syntax
response = client.describe_snapshot_attribute(
DryRun=True|False,
SnapshotId='string',
Attribute='productCodes'|'createVolumePermission'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SnapshotId (string) – [REQUIRED]
The ID of the EBS snapshot.
• Attribute (string) – [REQUIRED]
The snapshot attribute you would like to view.
Return type dict
Returns
Response Syntax
{
'SnapshotId': 'string',
'CreateVolumePermissions': [
{
'UserId': 'string',
'Group': 'all'
},
1296 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
]
}
Response Structure
• (dict) –
– SnapshotId (string) –
The ID of the EBS snapshot.
– CreateVolumePermissions (list) –
A list of permissions for creating volumes from the snapshot.
* (dict) –
Describes the user or group to be added or removed from the per-
missions for a volume.
· UserId (string) –
The specific AWS account ID that is to be added or removed
from a volume’s list of create volume permissions.
· Group (string) –
The specific group that is to be added or removed from a vol-
ume’s list of create volume permissions.
– ProductCodes (list) –
A list of product codes.
* (dict) –
Describes a product code.
· ProductCodeId (string) –
The product code.
· ProductCodeType (string) –
The type of product code.
describe_snapshots(**kwargs)
Describes one or more of the EBS snapshots available to you. Available snapshots include public snap-
shots available for any AWS account to launch, private snapshots that you own, and private snapshots
owned by another AWS account but for which you’ve been given explicit create volume permissions.
The create volume permissions fall into the following categories:
•public : The owner of the snapshot granted create volume permissions for the snapshot to the all
group. All AWS accounts have create volume permissions for these snapshots.
•explicit : The owner of the snapshot granted create volume permissions to a specific AWS account.
•implicit : An AWS account has implicit create volume permissions for all snapshots it owns.
The list of snapshots returned can be modified by specifying snapshot IDs, snapshot owners, or AWS
accounts with create volume permissions. If no options are specified, Amazon EC2 returns all snapshots
for which you have create volume permissions.
If you specify one or more snapshot IDs, only snapshots that have the specified IDs are returned. If you
specify an invalid snapshot ID, an error is returned. If you specify a snapshot ID for which you do not
have access, it is not included in the returned results.
3.1. Services 1297
Boto3 Documentation, Release 1.1.4
If you specify one or more snapshot owners, only snapshots from the specified owners and for which you
have access are returned. The results can include the AWS account IDs of the specified owners, amazon
for snapshots owned by Amazon, or self for snapshots that you own.
If you specify a list of restorable users, only snapshots with create snapshot permissions for those users
are returned. You can specify AWS account IDs (if you own the snapshots), self for snapshots for which
you own or have explicit permissions, or all for public snapshots.
If you are describing a long list of snapshots, you can paginate the output to make the list more manage-
able. The MaxResults parameter sets the maximum number of results returned in a single page. If
the list of results exceeds your MaxResults value, then that number of results is returned along with
a NextToken value that can be passed to a subsequent DescribeSnapshots request to retrieve the
remaining results.
For more information about EBS snapshots, see Amazon EBS Snapshots in the Amazon Elastic Compute
Cloud User Guide .
Request Syntax
response = client.describe_snapshots(
DryRun=True|False,
SnapshotIds=[
'string',
],
OwnerIds=[
'string',
],
RestorableByUserIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SnapshotIds (list) – One or more snapshot IDs.
Default: Describes snapshots for which you have launch permissions.
– (string) –
• OwnerIds (list) – Returns the snapshots owned by the specified owner. Multiple
owners can be specified.
– (string) –
• RestorableByUserIds (list) – One or more AWS accounts IDs that can create
volumes from the snapshot.
– (string) –
• Filters (list) – One or more filters.
1298 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– description - A description of the snapshot.
– owner-alias - The AWS account alias (for example, amazon ) that
owns the snapshot.
– owner-id - The ID of the AWS account that owns the snapshot.
– progress - The progress of the snapshot, as a percentage (for example,
80%).
– snapshot-id - The snapshot ID.
– start-time - The time stamp when the snapshot was initiated.
– status - The status of the snapshot (pending | completed | error
).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– volume-id - The ID of the volume the snapshot is for.
– volume-size - The size of the volume, in GiB.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The NextToken value returned from a previous pagi-
nated DescribeSnapshots request where MaxResults was used and the
results exceeded the value of that parameter. Pagination continues from the end
of the previous results that returned the NextToken value. This value is null
when there are no more results to return.
• MaxResults (integer) – The maximum number of snapshot results returned by
DescribeSnapshots in paginated output. When this parameter is used,
DescribeSnapshots only returns MaxResults results in a single page
along with a NextToken response element. The remaining results of the ini-
tial request can be seen by sending another DescribeSnapshots request
with the returned NextToken value. This value can be between 5 and 1000; if
MaxResults is given a value larger than 1000, only 1000 results are returned.
If this parameter is not used, then DescribeSnapshots returns all results.
You cannot specify this parameter and the snapshot IDs parameter in the same
request.
Return type dict
Returns
Response Syntax
3.1. Services 1299
Boto3 Documentation, Release 1.1.4
{
'Snapshots': [
{
'SnapshotId': 'string',
'VolumeId': 'string',
'State': 'pending'|'completed'|'error',
'StateMessage': 'string',
'StartTime': datetime(2015, 1, 1),
'Progress': 'string',
'OwnerId': 'string',
'Description': 'string',
'VolumeSize': 123,
'OwnerAlias': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'Encrypted': True|False,
'KmsKeyId': 'string',
'DataEncryptionKeyId': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– Snapshots (list) –
Information about the snapshots.
* (dict) –
Describes a snapshot.
· SnapshotId (string) –
The ID of the snapshot. Each snapshot receives a unique iden-
tifier when it is created.
· VolumeId (string) –
The ID of the volume that was used to create the snapshot.
· State (string) –
The snapshot state.
· StateMessage (string) –
Encrypted Amazon EBS snapshots are copied asyn-
chronously. If a snapshot copy operation fails (for example, if
the proper AWS Key Management Service (AWS KMS) per-
missions are not obtained) this field displays error state details
to help you diagnose why the error occurred. This parameter
is only returned by the DescribeSnapshots API operation.
· StartTime (datetime) –
The time stamp when the snapshot was initiated.
· Progress (string) –
The progress of the snapshot, as a percentage.
1300 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· OwnerId (string) –
The AWS account ID of the EBS snapshot owner.
· Description (string) –
The description for the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
· OwnerAlias (string) –
The AWS account alias (for example, amazon , self ) or
AWS account ID that owns the snapshot.
· Tags (list) –
Any tags assigned to the snapshot.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· Encrypted (boolean) –
Indicates whether the snapshot is encrypted.
· KmsKeyId (string) –
The full ARN of the AWS Key Management Service (AWS
KMS) customer master key (CMK) that was used to protect
the volume encryption key for the parent volume.
· DataEncryptionKeyId (string) –
The data encryption key identifier for the snapshot. This value
is a unique identifier that corresponds to the data encryption
key that was used to encrypt the original volume or snapshot
copy. Because data encryption keys are inherited by volumes
created from snapshots, and vice versa, if snapshots share the
same data encryption key identifier, then they belong to the
same volume/snapshot lineage. This parameter is only re-
turned by the DescribeSnapshots API operation.
– NextToken (string) –
The NextToken value to include in a future DescribeSnapshots
request. When the results of a DescribeSnapshots request exceed
MaxResults , this value can be used to retrieve the next page of results.
This value is null when there are no more results to return.
describe_spot_datafeed_subscription(**kwargs)
Describes the data feed for Spot instances. For more information, see Spot Instance Data Feed in the
Amazon Elastic Compute Cloud User Guide .
Request Syntax
3.1. Services 1301
Boto3 Documentation, Release 1.1.4
response = client.describe_spot_datafeed_subscription(
DryRun=True|False
)
Parameters DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If you have
the required permissions, the error response is DryRunOperation . Otherwise, it is
UnauthorizedOperation .
Return type dict
Returns
Response Syntax
{
'SpotDatafeedSubscription': {
'OwnerId': 'string',
'Bucket': 'string',
'Prefix': 'string',
'State': 'Active'|'Inactive',
'Fault': {
'Code': 'string',
'Message': 'string'
}
}
}
Response Structure
• (dict) –
Contains the output of DescribeSpotDatafeedSubscription.
– SpotDatafeedSubscription (dict) –
The Spot instance data feed subscription.
* OwnerId (string) –
The AWS account ID of the account.
* Bucket (string) –
The Amazon S3 bucket where the Spot instance data feed is located.
* Prefix (string) –
The prefix that is prepended to data feed files.
* State (string) –
The state of the Spot instance data feed subscription.
* Fault (dict) –
The fault codes for the Spot instance request, if any.
· Code (string) –
The reason code for the Spot instance state change.
· Message (string) –
The message for the Spot instance state change.
describe_spot_fleet_instances(**kwargs)
Describes the running instances for the specified Spot fleet.
Request Syntax
1302 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.describe_spot_fleet_instances(
DryRun=True|False,
SpotFleetRequestId='string',
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SpotFleetRequestId (string) – [REQUIRED]
The ID of the Spot fleet request.
• NextToken (string) – The token for the next set of results.
• MaxResults (integer) – The maximum number of results to return in a single
call. Specify a value between 1 and 1000. The default value is 1000. To retrieve
the remaining results, make another call with the returned NextToken value.
Return type dict
Returns
Response Syntax
{
'SpotFleetRequestId': 'string',
'ActiveInstances': [
{
'InstanceType': 'string',
'InstanceId': 'string',
'SpotInstanceRequestId': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the output of DescribeSpotFleetInstances.
– SpotFleetRequestId (string) –
The ID of the Spot fleet request.
– ActiveInstances (list) –
The running instances. Note that this list is refreshed periodically and
might be out of date.
* (dict) –
Describes a running instance in a Spot fleet.
· InstanceType (string) –
The instance type.
· InstanceId (string) –
The ID of the instance.
· SpotInstanceRequestId (string) –
The ID of the Spot instance request.
3.1. Services 1303
Boto3 Documentation, Release 1.1.4
– NextToken (string) –
The token required to retrieve the next set of results. This value is null
when there are no more results to return.
describe_spot_fleet_request_history(**kwargs)
Describes the events for the specified Spot fleet request during the specified time.
Spot fleet events are delayed by up to 30 seconds before they can be described. This ensures that you can
query by the last evaluated time and not miss a recorded event.
Request Syntax
response = client.describe_spot_fleet_request_history(
DryRun=True|False,
SpotFleetRequestId='string',
EventType='instanceChange'|'fleetRequestChange'|'error',
StartTime=datetime(2015, 1, 1),
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SpotFleetRequestId (string) – [REQUIRED]
The ID of the Spot fleet request.
• EventType (string) – The type of events to describe. By default, all events are
described.
• StartTime (datetime) – [REQUIRED]
The starting date and time for the events, in UTC format (for example, YYYY
-MM -DD T*HH* :MM :SS Z).
• NextToken (string) – The token for the next set of results.
• MaxResults (integer) – The maximum number of results to return in a single
call. Specify a value between 1 and 1000. The default value is 1000. To retrieve
the remaining results, make another call with the returned NextToken value.
Return type dict
Returns
Response Syntax
{
'SpotFleetRequestId': 'string',
'StartTime': datetime(2015, 1, 1),
'LastEvaluatedTime': datetime(2015, 1, 1),
'HistoryRecords': [
{
'Timestamp': datetime(2015, 1, 1),
'EventType': 'instanceChange'|'fleetRequestChange'|'error',
'EventInformation': {
'InstanceId': 'string',
'EventSubType': 'string',
'EventDescription': 'string'
}
},
1304 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the output of DescribeSpotFleetRequestHistory.
– SpotFleetRequestId (string) –
The ID of the Spot fleet request.
– StartTime (datetime) –
The starting date and time for the events, in UTC format (for example,
YYYY -MM -DD T*HH* :MM :SS Z).
– LastEvaluatedTime (datetime) –
The last date and time for the events, in UTC format (for example, YYYY
-MM -DD T*HH* :MM :SS Z). All records up to this time were retrieved.
If nextToken indicates that there are more results, this value is not
present.
– HistoryRecords (list) –
Information about the events in the history of the Spot fleet request.
* (dict) –
Describes an event in the history of the Spot fleet request.
· Timestamp (datetime) –
The date and time of the event, in UTC format (for example,
YYYY -MM -DD T*HH* :MM :SS Z).
· EventType (string) –
The event type.
· error - Indicates an error with the Spot fleet request.
· fleetRequestChange - Indicates a change in the status
or configuration of the Spot fleet request.
· instanceChange - Indicates that an instance was
launched or terminated.
· EventInformation (dict) –
Information about the event.
· InstanceId (string) –
The ID of the instance. This information is available only for
instanceChange events.
· EventSubType (string) –
The event.
The following are the error events.
· iamFleetRoleInvalid - Spot fleet did not have the re-
quired permissions either to launch or terminate an instance.
· spotFleetRequestConfigurationInvalid - The
configuration is not valid. For more information, see the de-
scription.
· spotInstanceCountLimitExceeded - You’ve
reached the limit on the number of Spot instances that you
can launch.
3.1. Services 1305
Boto3 Documentation, Release 1.1.4
The following are the fleetRequestChange events.
· active - The Spot fleet has been validated and Amazon EC2
is attempting to maintain the target number of running Spot
instances.
· cancelled - The Spot fleet is canceled and has no running
Spot instances. The Spot fleet will be deleted two days after
its instances were terminated.
· cancelled_running - The Spot fleet is canceled and will
not launch additional Spot instances, but its existing Spot in-
stances continue to run until they are interrupted or termi-
nated.
· cancelled_terminating - The Spot fleet is canceled
and its Spot instances are terminating.
· expired - The Spot fleet request has expired.
A subsequent event indicates that the instances
were terminated, if the request was created with
TerminateInstancesWithExpiration set.
· price_update - The bid price for a launch configuration
was adjusted because it was too high. This change is perma-
nent.
· submitted - The Spot fleet request is being evaluated and
Amazon EC2 is preparing to launch the target number of Spot
instances.
The following are the instanceChange events.
· launched - A bid was fulfilled and a new instance was
launched.
· terminated - An instance was terminated by the user.
· EventDescription (string) –
The description of the event.
– NextToken (string) –
The token required to retrieve the next set of results. This value is null
when there are no more results to return.
describe_spot_fleet_requests(**kwargs)
Describes your Spot fleet requests.
Request Syntax
response = client.describe_spot_fleet_requests(
DryRun=True|False,
SpotFleetRequestIds=[
'string',
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SpotFleetRequestIds (list) – The IDs of the Spot fleet requests.
– (string) –
• NextToken (string) – The token for the next set of results.
1306 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• MaxResults (integer) – The maximum number of results to return in a single
call. Specify a value between 1 and 1000. The default value is 1000. To retrieve
the remaining results, make another call with the returned NextToken value.
Return type dict
Returns
Response Syntax
{
'SpotFleetRequestConfigs': [
{
'SpotFleetRequestId': 'string',
'SpotFleetRequestState': 'submitted'|'active'|'cancelled'|'failed'|'ca
'SpotFleetRequestConfig': {
'ClientToken': 'string',
'SpotPrice': 'string',
'TargetCapacity': 123,
'ValidFrom': datetime(2015, 1, 1),
'ValidUntil': datetime(2015, 1, 1),
'TerminateInstancesWithExpiration': True|False,
'IamFleetRole': 'string',
'LaunchSpecifications': [
{
'ImageId': 'string',
'KeyName': 'string',
'SecurityGroups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'UserData': 'string',
'AddressingType': 'string',
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.larg
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string'
},
'KernelId': 'string',
'RamdiskId': 'string',
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
},
],
'Monitoring': {
'Enabled': True|False
},
3.1. Services 1307
Boto3 Documentation, Release 1.1.4
'SubnetId': 'string',
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'DeviceIndex': 123,
'SubnetId': 'string',
'Description': 'string',
'PrivateIpAddress': 'string',
'Groups': [
'string',
],
'DeleteOnTermination': True|False,
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
'SecondaryPrivateIpAddressCount': 123,
'AssociatePublicIpAddress': True|False
},
],
'IamInstanceProfile': {
'Arn': 'string',
'Name': 'string'
},
'EbsOptimized': True|False,
'WeightedCapacity': 123.0,
'SpotPrice': 'string'
},
],
'AllocationStrategy': 'lowestPrice'|'diversified'
}
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the output of DescribeSpotFleetRequests.
– SpotFleetRequestConfigs (list) –
Information about the configuration of your Spot fleet.
* (dict) –
Describes a Spot fleet request.
· SpotFleetRequestId (string) –
The ID of the Spot fleet request.
· SpotFleetRequestState (string) –
The state of the Spot fleet request.
· SpotFleetRequestConfig (dict) –
Information about the configuration of the Spot fleet request.
· ClientToken (string) –
A unique, case-sensitive identifier you provide to ensure
1308 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
idempotency of your listings. This helps avoid duplicate list-
ings. For more information, see Ensuring Idempotency .
· SpotPrice (string) –
The bid price per unit hour.
· TargetCapacity (integer) –
The number of units to request. You can choose to set the
target capacity in terms of instances or a performance charac-
teristic that is important to your application workload, such as
vCPUs, memory, or I/O.
· ValidFrom (datetime) –
The start date and time of the request, in UTC format (for
example, YYYY -MM -DD T*HH* :MM :SS Z). The default is
to start fulfilling the request immediately.
· ValidUntil (datetime) –
The end date and time of the request, in UTC format (for ex-
ample, YYYY -MM -DD T*HH* :MM :SS Z). At this point, no
new Spot instance requests are placed or enabled to fulfill the
request.
· TerminateInstancesWithExpiration (boolean) –
Indicates whether running Spot instances should be termi-
nated when the Spot fleet request expires.
· IamFleetRole (string) –
Grants the Spot fleet permission to terminate Spot
instances on your behalf when you cancel its
Spot fleet request using CancelSpotFleetRequests
or when the Spot fleet request expires, if you set
terminateInstancesWithExpiration .
· LaunchSpecifications (list) –
Information about the launch specifications for the Spot fleet
request.
· (dict) –
Describes the launch specification for one or more Spot in-
stances.
· ImageId (string) –
The ID of the AMI.
· KeyName (string) –
The name of the key pair.
· SecurityGroups (list) –
One or more security groups. To request an instance in a non-
default VPC, you must specify the ID of the security group.
To request an instance in EC2-Classic or a default VPC, you
can specify the name or the ID of the security group.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
3.1. Services 1309
Boto3 Documentation, Release 1.1.4
The ID of the security group.
· UserData (string) –
The Base64-encoded MIME user data to make available to
the instances.
· AddressingType (string) –
Deprecated.
· InstanceType (string) –
The instance type.
· Placement (dict) –
The placement information.
· AvailabilityZone (string) –
The Availability Zone.
· GroupName (string) –
The name of the placement group (for cluster instances).
· KernelId (string) –
The ID of the kernel.
· RamdiskId (string) –
The ID of the RAM disk.
· BlockDeviceMappings (list) –
One or more block device mapping entries.
· (dict) –
Describes a block device mapping.
· VirtualName (string) –
The virtual device name (ephemeral N). Instance store vol-
umes are numbered starting from 0. An instance type with
2 available instance store volumes can specify mappings for
ephemeral0 and ephemeral1 .The number of available
instance store volumes depends on the instance type. After
you connect to the instance, you must mount the volume.
Constraints: For M3 instances, you must specify instance
store volumes in the block device mapping for the instance.
When you launch an M3 instance, we ignore any instance
store volumes specified in the block device mapping for the
AMI.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
1310 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
· NoDevice (string) –
Suppresses the specified device included in the block device
mapping of the AMI.
· Monitoring (dict) –
Enable or disable monitoring for the instances.
· Enabled (boolean) –
Enables monitoring for the instance.
Default: false
· SubnetId (string) –
The ID of the subnet in which to launch the instances.
· NetworkInterfaces (list) –
One or more network interfaces.
3.1. Services 1311
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· DeviceIndex (integer) –
The index of the device on the instance for the network inter-
face attachment. If you are specifying a network interface in
a RunInstances request, you must provide the device index.
· SubnetId (string) –
The ID of the subnet associated with the network string. Ap-
plies only if creating a network interface when launching an
instance.
· Description (string) –
The description of the network interface. Applies only if cre-
ating a network interface when launching an instance.
· PrivateIpAddress (string) –
The private IP address of the network interface. Applies only
if creating a network interface when launching an instance.
· Groups (list) –
The IDs of the security groups for the network interface. Ap-
plies only if creating a network interface when launching an
instance.
· (string) –
· DeleteOnTermination (boolean) –
If set to true , the interface is deleted when the instance
is terminated. You can specify true only if creating a new
network interface when launching an instance.
· PrivateIpAddresses (list) –
One or more private IP addresses to assign to the network
interface. Only one private IP address can be designated as
primary.
· (dict) –
Describes a secondary private IP address for a network inter-
face.
· PrivateIpAddress (string) –
The private IP addresses.
· Primary (boolean) –
Indicates whether the private IP address is the primary private
IP address. Only one IP address can be designated as primary.
· SecondaryPrivateIpAddressCount (integer) –
The number of secondary private IP addresses. You can’t
specify this option and specify more than one private IP ad-
dress using the private IP addresses option.
· AssociatePublicIpAddress (boolean) –
Indicates whether to assign a public IP address to an instance
you launch in a VPC. The public IP address can only be as-
signed to a network interface for eth0, and can only be as-
1312 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
signed to a new network interface, not an existing one. You
cannot specify more than one network interface in the request.
If launching into a default subnet, the default value is true .
· IamInstanceProfile (dict) –
The IAM instance profile.
· Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
· Name (string) –
The name of the instance profile.
· EbsOptimized (boolean) –
Indicates whether the instances are optimized for EBS I/O.
This optimization provides dedicated throughput to Amazon
EBS and an optimized configuration stack to provide optimal
EBS I/O performance. This optimization isn’t available with
all instance types. Additional usage charges apply when using
an EBS Optimized instance.
Default: false
· WeightedCapacity (float) –
The number of units provided by the specified instance type.
These are the same units that you chose to set the target capac-
ity in terms (instances or a performance characteristic such as
vCPUs, memory, or I/O).
If the target capacity divided by this value is not a whole num-
ber, we round the number of instances to the next whole num-
ber. If this value is not specified, the default is 1.
· SpotPrice (string) –
The bid price per unit hour for the specified instance type.
If this value is not specified, the default is the Spot bid
price specified for the fleet. To determine the bid price
per unit hour, divide the Spot bid price by the value of
WeightedCapacity .
· AllocationStrategy (string) –
Determines how to allocate the target capacity across the
Spot pools specified by the Spot fleet request. The default
is lowestPrice .
– NextToken (string) –
The token required to retrieve the next set of results. This value is null
when there are no more results to return.
describe_spot_instance_requests(**kwargs)
Describes the Spot instance requests that belong to your account. Spot instances are instances that Ama-
zon EC2 launches when the bid price that you specify exceeds the current Spot price. Amazon EC2
periodically sets the Spot price based on available Spot instance capacity and current Spot instance re-
quests. For more information, see Spot Instance Requests in the Amazon Elastic Compute Cloud User
Guide .
You can use DescribeSpotInstanceRequests to find a running Spot instance by examining the
response. If the status of the Spot instance is fulfilled , the instance ID appears in the response and
contains the identifier of the instance. Alternatively, you can use DescribeInstances with a filter to look
for instances where the instance lifecycle is spot .
3.1. Services 1313
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.describe_spot_instance_requests(
DryRun=True|False,
SpotInstanceRequestIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SpotInstanceRequestIds (list) – One or more Spot instance request IDs.
– (string) –
• Filters (list) – One or more filters.
– availability-zone-group - The Availability Zone group.
– create-time - The time stamp when the Spot instance request was
created.
– fault-code - The fault code related to the request.
– fault-message - The fault message related to the request.
– instance-id - The ID of the instance that fulfilled the request.
– launch-group - The Spot instance launch group.
– launch.block-device-mapping.delete-on-termination
- Indicates whether the Amazon EBS volume is deleted on instance
termination.
– launch.block-device-mapping.device-name - The device
name for the Amazon EBS volume (for example, /dev/sdh ).
– launch.block-device-mapping.snapshot-id - The ID of the
snapshot used for the Amazon EBS volume.
– launch.block-device-mapping.volume-size - The size of
the Amazon EBS volume, in GiB.
– launch.block-device-mapping.volume-type - The type of
the Amazon EBS volume (gp2 | standard | io1 ).
– launch.group-id - The security group for the instance.
– launch.image-id - The ID of the AMI.
– launch.instance-type - The type of instance (for example,
m1.small ).
– launch.kernel-id - The kernel ID.
– launch.key-name - The name of the key pair the instance launched
with.
– launch.monitoring-enabled - Whether monitoring is enabled for
the Spot instance.
– launch.ramdisk-id - The RAM disk ID.
– network-interface.network-interface-id - The ID of the
network interface.
1314 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– network-interface.device-index - The index of the device for
the network interface attachment on the instance.
– network-interface.subnet-id - The ID of the subnet for the in-
stance.
– network-interface.description - A description of the network
interface.
– network-interface.private-ip-address - The primary pri-
vate IP address of the network interface.
– network-interface.delete-on-termination - Indicates
whether the network interface is deleted when the instance is terminated.
– network-interface.group-id - The ID of the security group as-
sociated with the network interface.
– network-interface.group-name - The name of the security
group associated with the network interface.
– network-interface.addresses.primary - Indicates whether
the IP address is the primary private IP address.
– product-description - The product description associated with the
instance (Linux/UNIX | Windows ).
– spot-instance-request-id - The Spot instance request ID.
– spot-price - The maximum hourly price for any Spot instance
launched to fulfill the request.
– state - The state of the Spot instance request (open | active |
closed | cancelled | failed ). Spot bid status information can
help you track your Amazon EC2 Spot instance requests. For more infor-
mation, see Spot Bid Status in the Amazon Elastic Compute Cloud User
Guide.
– status-code - The short code describing the most recent evaluation of
your Spot instance request.
– status-message - The message explaining the status of the Spot in-
stance request.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– type - The type of Spot instance request (one-time | persistent ).
– launched-availability-zone - The Availability Zone in which
the bid is launched.
– valid-from - The start date of the request.
– valid-until - The end date of the request.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
3.1. Services 1315
Boto3 Documentation, Release 1.1.4
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'SpotInstanceRequests': [
{
'SpotInstanceRequestId': 'string',
'SpotPrice': 'string',
'Type': 'one-time'|'persistent',
'State': 'open'|'active'|'closed'|'cancelled'|'failed',
'Fault': {
'Code': 'string',
'Message': 'string'
},
'Status': {
'Code': 'string',
'UpdateTime': datetime(2015, 1, 1),
'Message': 'string'
},
'ValidFrom': datetime(2015, 1, 1),
'ValidUntil': datetime(2015, 1, 1),
'LaunchGroup': 'string',
'AvailabilityZoneGroup': 'string',
'LaunchSpecification': {
'ImageId': 'string',
'KeyName': 'string',
'SecurityGroups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'UserData': 'string',
'AddressingType': 'string',
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.x
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string'
},
'KernelId': 'string',
'RamdiskId': 'string',
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
1316 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
],
'SubnetId': 'string',
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'DeviceIndex': 123,
'SubnetId': 'string',
'Description': 'string',
'PrivateIpAddress': 'string',
'Groups': [
'string',
],
'DeleteOnTermination': True|False,
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
'SecondaryPrivateIpAddressCount': 123,
'AssociatePublicIpAddress': True|False
},
],
'IamInstanceProfile': {
'Arn': 'string',
'Name': 'string'
},
'EbsOptimized': True|False,
'Monitoring': {
'Enabled': True|False
}
},
'InstanceId': 'string',
'CreateTime': datetime(2015, 1, 1),
'ProductDescription': 'Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'LaunchedAvailabilityZone': 'string'
},
]
}
Response Structure
• (dict) –
Contains the output of DescribeSpotInstanceRequests.
– SpotInstanceRequests (list) –
One or more Spot instance requests.
* (dict) –
Describe a Spot instance request.
· SpotInstanceRequestId (string) –
3.1. Services 1317
Boto3 Documentation, Release 1.1.4
The ID of the Spot instance request.
· SpotPrice (string) –
The maximum hourly price (bid) for any Spot instance
launched to fulfill the request.
· Type (string) –
The Spot instance request type.
· State (string) –
The state of the Spot instance request. Spot bid status infor-
mation can help you track your Spot instance requests. For
more information, see Spot Bid Status in the Amazon Elastic
Compute Cloud User Guide .
· Fault (dict) –
The fault codes for the Spot instance request, if any.
· Code (string) –
The reason code for the Spot instance state change.
· Message (string) –
The message for the Spot instance state change.
· Status (dict) –
The status code and status message describing the Spot in-
stance request.
· Code (string) –
The status code.
· UpdateTime (datetime) –
The date and time of the most recent status update, in UTC
format (for example, YYYY -MM -DD T*HH* :MM :SS Z).
· Message (string) –
The description for the status code.
· ValidFrom (datetime) –
The start date of the request, in UTC format (for example,
YYYY -MM -DD T*HH* :MM :SS Z). If this is a one-time
request, the request becomes active at this date and time and
remains active until all instances launch, the request expires,
or the request is canceled. If the request is persistent, the re-
quest becomes active at this date and time and remains active
until it expires or is canceled.
· ValidUntil (datetime) –
The end date of the request, in UTC format (for example,
YYYY -MM -DD T*HH* :MM :SS Z). If this is a one-time
request, the request remains active until all instances launch,
the request is canceled, or this date is reached. If the request
is persistent, it remains active until it is canceled or this date
is reached.
· LaunchGroup (string) –
The instance launch group. Launch groups are Spot instances
that launch together and terminate together.
· AvailabilityZoneGroup (string) –
1318 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The Availability Zone group. If you specify the same Avail-
ability Zone group for all Spot instance requests, all Spot in-
stances are launched in the same Availability Zone.
· LaunchSpecification (dict) –
Additional information for launching instances.
· ImageId (string) –
The ID of the AMI.
· KeyName (string) –
The name of the key pair.
· SecurityGroups (list) –
One or more security groups. To request an instance in a non-
default VPC, you must specify the ID of the security group.
To request an instance in EC2-Classic or a default VPC, you
can specify the name or the ID of the security group.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· UserData (string) –
The Base64-encoded MIME user data to make available to
the instances.
· AddressingType (string) –
Deprecated.
· InstanceType (string) –
The instance type.
· Placement (dict) –
The placement information for the instance.
· AvailabilityZone (string) –
The Availability Zone.
· GroupName (string) –
The name of the placement group (for cluster instances).
· KernelId (string) –
The ID of the kernel.
· RamdiskId (string) –
The ID of the RAM disk.
· BlockDeviceMappings (list) –
One or more block device mapping entries.
· (dict) –
Describes a block device mapping.
· VirtualName (string) –
The virtual device name (ephemeral N). Instance store vol-
umes are numbered starting from 0. An instance type with
2 available instance store volumes can specify mappings for
3.1. Services 1319
Boto3 Documentation, Release 1.1.4
ephemeral0 and ephemeral1 .The number of available
instance store volumes depends on the instance type. After
you connect to the instance, you must mount the volume.
Constraints: For M3 instances, you must specify instance
store volumes in the block device mapping for the instance.
When you launch an M3 instance, we ignore any instance
store volumes specified in the block device mapping for the
AMI.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
1320 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
· NoDevice (string) –
Suppresses the specified device included in the block device
mapping of the AMI.
· SubnetId (string) –
The ID of the subnet in which to launch the instance.
· NetworkInterfaces (list) –
One or more network interfaces.
· (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· DeviceIndex (integer) –
The index of the device on the instance for the network inter-
face attachment. If you are specifying a network interface in
a RunInstances request, you must provide the device index.
· SubnetId (string) –
The ID of the subnet associated with the network string. Ap-
plies only if creating a network interface when launching an
instance.
· Description (string) –
The description of the network interface. Applies only if cre-
ating a network interface when launching an instance.
· PrivateIpAddress (string) –
The private IP address of the network interface. Applies only
if creating a network interface when launching an instance.
· Groups (list) –
The IDs of the security groups for the network interface. Ap-
plies only if creating a network interface when launching an
instance.
· (string) –
· DeleteOnTermination (boolean) –
If set to true , the interface is deleted when the instance
is terminated. You can specify true only if creating a new
network interface when launching an instance.
· PrivateIpAddresses (list) –
One or more private IP addresses to assign to the network
interface. Only one private IP address can be designated as
primary.
· (dict) –
Describes a secondary private IP address for a network inter-
face.
3.1. Services 1321
Boto3 Documentation, Release 1.1.4
· PrivateIpAddress (string) –
The private IP addresses.
· Primary (boolean) –
Indicates whether the private IP address is the primary private
IP address. Only one IP address can be designated as primary.
· SecondaryPrivateIpAddressCount (integer) –
The number of secondary private IP addresses. You can’t
specify this option and specify more than one private IP ad-
dress using the private IP addresses option.
· AssociatePublicIpAddress (boolean) –
Indicates whether to assign a public IP address to an instance
you launch in a VPC. The public IP address can only be as-
signed to a network interface for eth0, and can only be as-
signed to a new network interface, not an existing one. You
cannot specify more than one network interface in the request.
If launching into a default subnet, the default value is true .
· IamInstanceProfile (dict) –
The IAM instance profile.
· Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
· Name (string) –
The name of the instance profile.
· EbsOptimized (boolean) –
Indicates whether the instance is optimized for EBS I/O. This
optimization provides dedicated throughput to Amazon EBS
and an optimized configuration stack to provide optimal EBS
I/O performance. This optimization isn’t available with all
instance types. Additional usage charges apply when using
an EBS Optimized instance.
Default: false
· Monitoring (dict) –
Describes the monitoring for the instance.
· Enabled (boolean) –
Indicates whether monitoring is enabled for the instance.
· InstanceId (string) –
The instance ID, if an instance has been launched to fulfill the
Spot instance request.
· CreateTime (datetime) –
The date and time when the Spot instance request was created,
in UTC format (for example, YYYY -MM -DD T*HH* :MM
:SS Z).
· ProductDescription (string) –
The product description associated with the Spot instance.
· Tags (list) –
Any tags assigned to the resource.
1322 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· LaunchedAvailabilityZone (string) –
The Availability Zone in which the bid is launched.
describe_spot_price_history(**kwargs)
Describes the Spot price history. The prices returned are listed in chronological order, from the oldest to
the most recent, for up to the past 90 days. For more information, see Spot Instance Pricing History in the
Amazon Elastic Compute Cloud User Guide .
When you specify a start and end time, this operation returns the prices of the instance types within the
time range that you specified and the time when the price changed. The price is valid within the time
period that you specified; the response merely indicates the last time that the price changed.
Request Syntax
response = client.describe_spot_price_history(
DryRun=True|False,
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
InstanceTypes=[
't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.medium'|'m3.large'|'m3.
],
ProductDescriptions=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
AvailabilityZone='string',
MaxResults=123,
NextToken='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
3.1. Services 1323
Boto3 Documentation, Release 1.1.4
• StartTime (datetime) – The date and time, up to the past 90 days, from which to
start retrieving the price history data, in UTC format (for example, YYYY -MM
-DD T*HH* :MM :SS Z).
• EndTime (datetime) – The date and time, up to the current date, from which to
stop retrieving the price history data, in UTC format (for example, YYYY -MM
-DD T*HH* :MM :SS Z).
• InstanceTypes (list) – Filters the results by the specified instance types.
– (string) –
• ProductDescriptions (list) – Filters the results by the specified basic product
descriptions.
– (string) –
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone for which prices should
be returned.
– instance-type - The type of instance (for example, m1.small ).
– product-description - The product description for the Spot price
(Linux/UNIX | SUSE Linux | Windows | Linux/UNIX (Amazon
VPC) | SUSE Linux (Amazon VPC) | Windows (Amazon VPC)
).
– spot-price - The Spot price. The value must match exactly (or use
wildcards; greater than or less than comparison is not supported).
– timestamp - The timestamp of the Spot price history, in UTC format
(for example, YYYY -MM -DD T*HH* :MM :SS Z). You can use wildcards
(* and ?). Greater than or less than comparison is not supported.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• AvailabilityZone (string) – Filters the results by the specified Availability Zone.
• MaxResults (integer) – The maximum number of results to return in a single
call. Specify a value between 1 and 1000. The default value is 1000. To retrieve
the remaining results, make another call with the returned NextToken value.
• NextToken (string) – The token for the next set of results.
Return type dict
Returns
Response Syntax
{
'SpotPriceHistory': [
{
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarg
'ProductDescription': 'Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'
'SpotPrice': 'string',
'Timestamp': datetime(2015, 1, 1),
'AvailabilityZone': 'string'
},
],
1324 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'NextToken': 'string'
}
Response Structure
• (dict) –
Contains the output of DescribeSpotPriceHistory.
– SpotPriceHistory (list) –
The historical Spot prices.
* (dict) –
Describes the maximum hourly price (bid) for any Spot instance
launched to fulfill the request.
· InstanceType (string) –
The instance type.
· ProductDescription (string) –
A general description of the AMI.
· SpotPrice (string) –
The maximum price (bid) that you are willing to pay for a
Spot instance.
· Timestamp (datetime) –
The date and time the request was created, in UTC format (for
example, YYYY -MM -DD T*HH* :MM :SS Z).
· AvailabilityZone (string) –
The Availability Zone.
– NextToken (string) –
The token required to retrieve the next set of results. This value is null
when there are no more results to return.
describe_subnets(**kwargs)
Describes one or more of your subnets.
For more information about subnets, see Your VPC and Subnets in the Amazon Virtual Private Cloud
User Guide .
Request Syntax
response = client.describe_subnets(
DryRun=True|False,
SubnetIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
3.1. Services 1325
Boto3 Documentation, Release 1.1.4
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SubnetIds (list) – One or more subnet IDs.
Default: Describes all your subnets.
– (string) –
• Filters (list) – One or more filters.
– availabilityZone - The Availability Zone for the subnet. You can
also use availability-zone as the filter name.
– available-ip-address-count - The number of IP addresses in
the subnet that are available.
– cidrBlock - The CIDR block of the subnet. The CIDR block you spec-
ify must exactly match the subnet’s CIDR block for information to be
returned for the subnet. You can also use cidr or cidr-block as the
filter names.
– defaultForAz - Indicates whether this is the default subnet for the
Availability Zone. You can also use default-for-az as the filter
name.
– state - The state of the subnet (pending | available ).
– subnet-id - The ID of the subnet.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-id - The ID of the VPC for the subnet.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'Subnets': [
{
'SubnetId': 'string',
'State': 'pending'|'available',
'VpcId': 'string',
1326 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'CidrBlock': 'string',
'AvailableIpAddressCount': 123,
'AvailabilityZone': 'string',
'DefaultForAz': True|False,
'MapPublicIpOnLaunch': True|False,
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– Subnets (list) –
Information about one or more subnets.
* (dict) –
Describes a subnet.
· SubnetId (string) –
The ID of the subnet.
· State (string) –
The current state of the subnet.
· VpcId (string) –
The ID of the VPC the subnet is in.
· CidrBlock (string) –
The CIDR block assigned to the subnet.
· AvailableIpAddressCount (integer) –
The number of unused IP addresses in the subnet. Note that
the IP addresses for any stopped instances are considered un-
available.
· AvailabilityZone (string) –
The Availability Zone of the subnet.
· DefaultForAz (boolean) –
Indicates whether this is the default subnet for the Availability
Zone.
· MapPublicIpOnLaunch (boolean) –
Indicates whether instances launched in this subnet receive a
public IP address.
· Tags (list) –
Any tags assigned to the subnet.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
3.1. Services 1327
Boto3 Documentation, Release 1.1.4
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
describe_tags(**kwargs)
Describes one or more of the tags for your EC2 resources.
For more information about tags, see Tagging Your Resources in the Amazon Elastic Compute Cloud User
Guide .
Request Syntax
response = client.describe_tags(
DryRun=True|False,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
MaxResults=123,
NextToken='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Filters (list) – One or more filters.
– key - The tag key.
– resource-id - The resource ID.
– resource-type - The resource type (customer-gateway |
dhcp-options | image | instance | internet-gateway |
network-acl | network-interface | reserved-instances
| route-table | security-group | snapshot |
spot-instances-request | subnet | volume | vpc |
vpn-connection | vpn-gateway ).
– value - The tag value.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
1328 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned.
• NextToken (string) – The token to retrieve the next page of results.
Return type dict
Returns
Response Syntax
{
'Tags': [
{
'ResourceId': 'string',
'ResourceType': 'customer-gateway'|'dhcp-options'|'image'|'instance'|'
'Key': 'string',
'Value': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– Tags (list) –
A list of tags.
* (dict) –
Describes a tag.
· ResourceId (string) –
The ID of the resource. For example, ami-1a2b3c4d .
· ResourceType (string) –
The resource type.
· Key (string) –
The tag key.
· Value (string) –
The tag value.
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return..
describe_volume_attribute(**kwargs)
Describes the specified attribute of the specified volume. You can specify only one attribute at a time.
For more information about EBS volumes, see Amazon EBS Volumes in the Amazon Elastic Compute
Cloud User Guide .
Request Syntax
response = client.describe_volume_attribute(
DryRun=True|False,
VolumeId='string',
3.1. Services 1329
Boto3 Documentation, Release 1.1.4
Attribute='autoEnableIO'|'productCodes'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeId (string) – [REQUIRED]
The ID of the volume.
• Attribute (string) – The instance attribute.
Return type dict
Returns
Response Syntax
{
'VolumeId': 'string',
'AutoEnableIO': {
'Value': True|False
},
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
]
}
Response Structure
• (dict) –
– VolumeId (string) –
The ID of the volume.
– AutoEnableIO (dict) –
The state of autoEnableIO attribute.
* Value (boolean) –
Valid values are true or false .
– ProductCodes (list) –
A list of product codes.
* (dict) –
Describes a product code.
· ProductCodeId (string) –
The product code.
· ProductCodeType (string) –
The type of product code.
describe_volume_status(**kwargs)
Describes the status of the specified volumes. Volume status provides the result of the checks performed
on your volumes to determine events that can impair the performance of your volumes. The performance
of a volume can be affected if an issue occurs on the volume’s underlying host. If the volume’s under-
lying host experiences a power outage or system issue, after the system is restored, there could be data
1330 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
inconsistencies on the volume. Volume events notify you if this occurs. Volume actions notify you if any
action needs to be taken in response to the event.
The DescribeVolumeStatus operation provides the following information about the specified vol-
umes:
Status : Reflects the current status of the volume. The possible values are ok , impaired , warning ,
or insufficient-data . If all checks pass, the overall status of the volume is ok . If the check fails,
the overall status is impaired . If the status is insufficient-data , then the checks may still be
taking place on your volume at the time. We recommend that you retry the request. For more information
on volume status, see Monitoring the Status of Your Volumes .
Events : Reflect the cause of a volume status and may require you to take action. For
example, if your volume returns an impaired status, then the volume event might be
potential-data-inconsistency . This means that your volume has been affected by an issue
with the underlying host, has all I/O operations disabled, and may have inconsistent data.
Actions : Reflect the actions you may have to take in response to an event. For example, if the status of
the volume is impaired and the volume event shows potential-data-inconsistency , then
the action shows enable-volume-io . This means that you may want to enable the I/O operations for
the volume by calling the EnableVolumeIO action and then check the volume for data consistency.
Note: Volume status is based on the volume status checks, and does not reflect the volume state. There-
fore, volume status does not indicate volumes in the error state (for example, when a volume is inca-
pable of accepting I/O.)
Request Syntax
response = client.describe_volume_status(
DryRun=True|False,
VolumeIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeIds (list) – One or more volume IDs.
Default: Describes all your volumes.
– (string) –
• Filters (list) – One or more filters.
– action.code - The action code for the event (for example,
enable-volume-io ).
– action.description - A description of the action.
3.1. Services 1331
Boto3 Documentation, Release 1.1.4
– action.event-id - The event ID associated with the action.
– availability-zone - The Availability Zone of the instance.
– event.description - A description of the event.
– event.event-id - The event ID.
– event.event-type - The event type (for io-enabled : passed |
failed ; for io-performance : io-performance:degraded
| io-performance:severely-degraded |
io-performance:stalled ).
– event.not-after - The latest end time for the event.
– event.not-before - The earliest start time for the event.
– volume-status.details-name - The cause for
volume-status.status (io-enabled | io-performance
).
– volume-status.details-status - The status of
volume-status.details-name (for io-enabled : passed
| failed ; for io-performance : normal | degraded |
severely-degraded | stalled ).
– volume-status.status - The status of the volume (ok | impaired
| warning | insufficient-data ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The NextToken value to include in a future
DescribeVolumeStatus request. When the results of the request exceed
MaxResults , this value can be used to retrieve the next page of results. This
value is null when there are no more results to return.
• MaxResults (integer) – The maximum number of volume results returned by
DescribeVolumeStatus in paginated output. When this parameter is used,
the request only returns MaxResults results in a single page along with a
NextToken response element. The remaining results of the initial request
can be seen by sending another request with the returned NextToken value.
This value can be between 5 and 1000; if MaxResults is given a value larger
than 1000, only 1000 results are returned. If this parameter is not used, then
DescribeVolumeStatus returns all results. You cannot specify this param-
eter and the volume IDs parameter in the same request.
Return type dict
Returns
Response Syntax
{
'VolumeStatuses': [
{
'VolumeId': 'string',
'AvailabilityZone': 'string',
'VolumeStatus': {
'Status': 'ok'|'impaired'|'insufficient-data',
1332 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Details': [
{
'Name': 'io-enabled'|'io-performance',
'Status': 'string'
},
]
},
'Events': [
{
'EventType': 'string',
'Description': 'string',
'NotBefore': datetime(2015, 1, 1),
'NotAfter': datetime(2015, 1, 1),
'EventId': 'string'
},
],
'Actions': [
{
'Code': 'string',
'Description': 'string',
'EventType': 'string',
'EventId': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– VolumeStatuses (list) –
A list of volumes.
* (dict) –
Describes the volume status.
· VolumeId (string) –
The volume ID.
· AvailabilityZone (string) –
The Availability Zone of the volume.
· VolumeStatus (dict) –
The volume status.
· Status (string) –
The status of the volume.
· Details (list) –
The details of the volume status.
· (dict) –
Describes a volume status.
· Name (string) –
The name of the volume status.
· Status (string) –
The intended status of the volume status.
3.1. Services 1333
Boto3 Documentation, Release 1.1.4
· Events (list) –
A list of events associated with the volume.
· (dict) –
Describes a volume status event.
· EventType (string) –
The type of this event.
· Description (string) –
A description of the event.
· NotBefore (datetime) –
The earliest start time of the event.
· NotAfter (datetime) –
The latest end time of the event.
· EventId (string) –
The ID of this event.
· Actions (list) –
The details of the operation.
· (dict) –
Describes a volume status operation code.
· Code (string) –
The code identifying the operation, for example,
enable-volume-io .
· Description (string) –
A description of the operation.
· EventType (string) –
The event type associated with this operation.
· EventId (string) –
The ID of the event associated with this operation.
– NextToken (string) –
The token to use to retrieve the next page of results. This value is null
when there are no more results to return.
describe_volumes(**kwargs)
Describes the specified EBS volumes.
If you are describing a long list of volumes, you can paginate the output to make the list more manage-
able. The MaxResults parameter sets the maximum number of results returned in a single page. If
the list of results exceeds your MaxResults value, then that number of results is returned along with
a NextToken value that can be passed to a subsequent DescribeVolumes request to retrieve the
remaining results.
For more information about EBS volumes, see Amazon EBS Volumes in the Amazon Elastic Compute
Cloud User Guide .
Request Syntax
response = client.describe_volumes(
DryRun=True|False,
VolumeIds=[
'string',
1334 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeIds (list) – One or more volume IDs.
– (string) –
• Filters (list) – One or more filters.
– attachment.attach-time - The time stamp when the attachment
initiated.
– attachment.delete-on-termination - Whether the volume is
deleted on instance termination.
– attachment.device - The device name that is exposed to the instance
(for example, /dev/sda1 ).
– attachment.instance-id - The ID of the instance the volume is
attached to.
– attachment.status - The attachment state (attaching |
attached | detaching | detached ).
– availability-zone - The Availability Zone in which the volume
was created.
– create-time - The time stamp when the volume was created.
– encrypted - The encryption status of the volume.
– size - The size of the volume, in GiB.
– snapshot-id - The snapshot from which the volume was created.
– status - The status of the volume (creating | available | in-use
| deleting | deleted | error ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– volume-id - The volume ID.
– volume-type - The Amazon EBS volume type. This can be gp2 for
General Purpose (SSD) volumes, io1 for Provisioned IOPS (SSD) vol-
umes, or standard for Magnetic volumes.
– (dict) –
3.1. Services 1335
Boto3 Documentation, Release 1.1.4
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The NextToken value returned from a previous pagi-
nated DescribeVolumes request where MaxResults was used and the re-
sults exceeded the value of that parameter. Pagination continues from the end
of the previous results that returned the NextToken value. This value is null
when there are no more results to return.
• MaxResults (integer) – The maximum number of volume results returned
by DescribeVolumes in paginated output. When this parameter is used,
DescribeVolumes only returns MaxResults results in a single page along
with a NextToken response element. The remaining results of the initial
request can be seen by sending another DescribeVolumes request with
the returned NextToken value. This value can be between 5 and 1000; if
MaxResults is given a value larger than 1000, only 1000 results are returned.
If this parameter is not used, then DescribeVolumes returns all results. You
cannot specify this parameter and the volume IDs parameter in the same request.
Return type dict
Returns
Response Syntax
{
'Volumes': [
{
'VolumeId': 'string',
'Size': 123,
'SnapshotId': 'string',
'AvailabilityZone': 'string',
'State': 'creating'|'available'|'in-use'|'deleting'|'deleted'|'error',
'CreateTime': datetime(2015, 1, 1),
'Attachments': [
{
'VolumeId': 'string',
'InstanceId': 'string',
'Device': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False,
1336 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'KmsKeyId': 'string'
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– Volumes (list) –
Information about the volumes.
* (dict) –
Describes a volume.
· VolumeId (string) –
The ID of the volume.
· Size (integer) –
The size of the volume, in GiBs.
· SnapshotId (string) –
The snapshot from which the volume was created, if applica-
ble.
· AvailabilityZone (string) –
The Availability Zone for the volume.
· State (string) –
The volume state.
· CreateTime (datetime) –
The time stamp when volume creation was initiated.
· Attachments (list) –
Information about the volume attachments.
· (dict) –
Describes volume attachment details.
· VolumeId (string) –
The ID of the volume.
· InstanceId (string) –
The ID of the instance.
· Device (string) –
The device name.
· State (string) –
The attachment state of the volume.
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· Tags (list) –
Any tags assigned to the volume.
3.1. Services 1337
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· VolumeType (string) –
The volume type. This can be gp2 for General Purpose
(SSD) volumes, io1 for Provisioned IOPS (SSD) volumes,
or standard for Magnetic volumes.
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the volume will be encrypted.
· KmsKeyId (string) –
The full ARN of the AWS Key Management Service (AWS
KMS) customer master key (CMK) that was used to protect
the volume encryption key for the volume.
– NextToken (string) –
The NextToken value to include in a future DescribeVolumes
request. When the results of a DescribeVolumes request exceed
MaxResults , this value can be used to retrieve the next page of results.
This value is null when there are no more results to return.
describe_vpc_attribute(**kwargs)
Describes the specified attribute of the specified VPC. You can specify only one attribute at a time.
Request Syntax
response = client.describe_vpc_attribute(
DryRun=True|False,
1338 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
VpcId='string',
Attribute='enableDnsSupport'|'enableDnsHostnames'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – [REQUIRED]
The ID of the VPC.
• Attribute (string) – The VPC attribute.
Return type dict
Returns
Response Syntax
{
'VpcId': 'string',
'EnableDnsSupport': {
'Value': True|False
},
'EnableDnsHostnames': {
'Value': True|False
}
}
Response Structure
• (dict) –
– VpcId (string) –
The ID of the VPC.
– EnableDnsSupport (dict) –
Indicates whether DNS resolution is enabled for the VPC. If this attribute
is true , the Amazon DNS server resolves DNS hostnames for your in-
stances to their corresponding IP addresses; otherwise, it does not.
* Value (boolean) –
Valid values are true or false .
– EnableDnsHostnames (dict) –
Indicates whether the instances launched in the VPC get DNS hostnames.
If this attribute is true , instances in the VPC get DNS hostnames; other-
wise, they do not.
* Value (boolean) –
Valid values are true or false .
describe_vpc_classic_link(**kwargs)
Describes the ClassicLink status of one or more VPCs.
Request Syntax
response = client.describe_vpc_classic_link(
DryRun=True|False,
VpcIds=[
'string',
3.1. Services 1339
Boto3 Documentation, Release 1.1.4
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcIds (list) – One or more VPCs for which you want to describe the Classi-
cLink status.
– (string) –
• Filters (list) – One or more filters.
– is-classic-link-enabled - Whether the VPC is enabled for Clas-
sicLink (true | false ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'Vpcs': [
{
'VpcId': 'string',
'ClassicLinkEnabled': True|False,
'Tags': [
{
1340 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Key': 'string',
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– Vpcs (list) –
The ClassicLink status of one or more VPCs.
* (dict) –
Describes whether a VPC is enabled for ClassicLink.
· VpcId (string) –
The ID of the VPC.
· ClassicLinkEnabled (boolean) –
Indicates whether the VPC is enabled for ClassicLink.
· Tags (list) –
Any tags assigned to the VPC.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
describe_vpc_endpoint_services(**kwargs)
Describes all supported AWS services that can be specified when creating a VPC endpoint.
Request Syntax
response = client.describe_vpc_endpoint_services(
DryRun=True|False,
MaxResults=123,
NextToken='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• MaxResults (integer) – The maximum number of items to return for this request.
The request returns a token that you can specify in a subsequent call to get the
next set of results.
3.1. Services 1341
Boto3 Documentation, Release 1.1.4
Constraint: If the value is greater than 1000, we return only 1000 items.
• NextToken (string) – The token for the next set of items to return. (You received
this token from a prior call.)
Return type dict
Returns
Response Syntax
{
'ServiceNames': [
'string',
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– ServiceNames (list) –
A list of supported AWS services.
* (string) –
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_vpc_endpoints(**kwargs)
Describes one or more of your VPC endpoints.
Request Syntax
response = client.describe_vpc_endpoints(
DryRun=True|False,
VpcEndpointIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
MaxResults=123,
NextToken='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcEndpointIds (list) – One or more endpoint IDs.
– (string) –
• Filters (list) – One or more filters.
– service-name : The name of the AWS service.
– vpc-id : The ID of the VPC in which the endpoint resides.
1342 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– vpc-endpoint-id : The ID of the endpoint.
– vpc-endpoint-state : The state of the endpoint. (pending |
available | deleting | deleted )
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• MaxResults (integer) – The maximum number of items to return for this request.
The request returns a token that you can specify in a subsequent call to get the
next set of results.
Constraint: If the value is greater than 1000, we return only 1000 items.
• NextToken (string) – The token for the next set of items to return. (You received
this token from a prior call.)
Return type dict
Returns
Response Syntax
{
'VpcEndpoints': [
{
'VpcEndpointId': 'string',
'VpcId': 'string',
'ServiceName': 'string',
'State': 'Pending'|'Available'|'Deleting'|'Deleted',
'PolicyDocument': 'string',
'RouteTableIds': [
'string',
],
'CreationTimestamp': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
• (dict) –
– VpcEndpoints (list) –
Information about the endpoints.
* (dict) –
Describes a VPC endpoint.
· VpcEndpointId (string) –
The ID of the VPC endpoint.
· VpcId (string) –
The ID of the VPC to which the endpoint is associated.
3.1. Services 1343
Boto3 Documentation, Release 1.1.4
· ServiceName (string) –
The name of the AWS service to which the endpoint is asso-
ciated.
· State (string) –
The state of the VPC endpoint.
· PolicyDocument (string) –
The policy document associated with the endpoint.
· RouteTableIds (list) –
One or more route tables associated with the endpoint.
· (string) –
· CreationTimestamp (datetime) –
The date and time the VPC endpoint was created.
– NextToken (string) –
The token to use when requesting the next set of items. If there are no
additional items to return, the string is empty.
describe_vpc_peering_connections(**kwargs)
Describes one or more of your VPC peering connections.
Request Syntax
response = client.describe_vpc_peering_connections(
DryRun=True|False,
VpcPeeringConnectionIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcPeeringConnectionIds (list) – One or more VPC peering connection IDs.
Default: Describes all your VPC peering connections.
– (string) –
• Filters (list) – One or more filters.
– accepter-vpc-info.cidr-block - The CIDR block of the peer
VPC.
– accepter-vpc-info.owner-id - The AWS account ID of the
owner of the peer VPC.
– accepter-vpc-info.vpc-id - The ID of the peer VPC.
– expiration-time - The expiration date and time for the VPC peering
connection.
1344 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– requester-vpc-info.cidr-block - The CIDR block of the re-
quester’s VPC.
– requester-vpc-info.owner-id - The AWS account ID of the
owner of the requester VPC.
– requester-vpc-info.vpc-id - The ID of the requester VPC.
– status-code - The status of the VPC peering connection
(pending-acceptance | failed | expired | provisioning |
active | deleted | rejected ).
– status-message - A message that provides more information about
the status of the VPC peering connection, if applicable.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-peering-connection-id - The ID of the VPC peering con-
nection.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'VpcPeeringConnections': [
{
'AccepterVpcInfo': {
'CidrBlock': 'string',
'OwnerId': 'string',
'VpcId': 'string'
},
'ExpirationTime': datetime(2015, 1, 1),
'RequesterVpcInfo': {
'CidrBlock': 'string',
'OwnerId': 'string',
'VpcId': 'string'
},
'Status': {
'Code': 'initiating-request'|'pending-acceptance'|'active'|'delete
'Message': 'string'
},
3.1. Services 1345
Boto3 Documentation, Release 1.1.4
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VpcPeeringConnectionId': 'string'
},
]
}
Response Structure
• (dict) –
– VpcPeeringConnections (list) –
Information about the VPC peering connections.
* (dict) –
Describes a VPC peering connection.
· AccepterVpcInfo (dict) –
The information of the peer VPC.
· CidrBlock (string) –
The CIDR block for the VPC.
· OwnerId (string) –
The AWS account ID of the VPC owner.
· VpcId (string) –
The ID of the VPC.
· ExpirationTime (datetime) –
The time that an unaccepted VPC peering connection will ex-
pire.
· RequesterVpcInfo (dict) –
The information of the requester VPC.
· CidrBlock (string) –
The CIDR block for the VPC.
· OwnerId (string) –
The AWS account ID of the VPC owner.
· VpcId (string) –
The ID of the VPC.
· Status (dict) –
The status of the VPC peering connection.
· Code (string) –
The status of the VPC peering connection.
· Message (string) –
A message that provides more information about the status, if
applicable.
· Tags (list) –
Any tags assigned to the resource.
· (dict) –
1346 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· VpcPeeringConnectionId (string) –
The ID of the VPC peering connection.
describe_vpcs(**kwargs)
Describes one or more of your VPCs.
Request Syntax
response = client.describe_vpcs(
DryRun=True|False,
VpcIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcIds (list) – One or more VPC IDs.
Default: Describes all your VPCs.
– (string) –
• Filters (list) – One or more filters.
– cidr - The CIDR block of the VPC. The CIDR block you specify must
exactly match the VPC’s CIDR block for information to be returned for the
VPC. Must contain the slash followed by one or two digits (for example,
/28 ).
– dhcp-options-id - The ID of a set of DHCP options.
– isDefault - Indicates whether the VPC is the default VPC.
– state - The state of the VPC (pending | available ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
3.1. Services 1347
Boto3 Documentation, Release 1.1.4
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-id - The ID of the VPC.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'Vpcs': [
{
'VpcId': 'string',
'State': 'pending'|'available',
'CidrBlock': 'string',
'DhcpOptionsId': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'InstanceTenancy': 'default'|'dedicated',
'IsDefault': True|False
},
]
}
Response Structure
• (dict) –
– Vpcs (list) –
Information about one or more VPCs.
* (dict) –
Describes a VPC.
· VpcId (string) –
The ID of the VPC.
· State (string) –
The current state of the VPC.
· CidrBlock (string) –
1348 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The CIDR block for the VPC.
· DhcpOptionsId (string) –
The ID of the set of DHCP options you’ve associated with the
VPC (or default if the default options are associated with
the VPC).
· Tags (list) –
Any tags assigned to the VPC.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· InstanceTenancy (string) –
The allowed tenancy of instances launched into the VPC.
· IsDefault (boolean) –
Indicates whether the VPC is the default VPC.
describe_vpn_connections(**kwargs)
Describes one or more of your VPN connections.
For more information about VPN connections, see Adding a Hardware Virtual Private Gateway to Your
VPC in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.describe_vpn_connections(
DryRun=True|False,
VpnConnectionIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpnConnectionIds (list) – One or more VPN connection IDs.
Default: Describes your VPN connections.
3.1. Services 1349
Boto3 Documentation, Release 1.1.4
– (string) –
• Filters (list) – One or more filters.
– customer-gateway-configuration - The configuration infor-
mation for the customer gateway.
– customer-gateway-id - The ID of a customer gateway associated
with the VPN connection.
– state - The state of the VPN connection (pending | available |
deleting | deleted ).
– option.static-routes-only - Indicates whether the connection
has static routes only. Used for devices that do not support Border Gate-
way Protocol (BGP).
– route.destination-cidr-block - The destination CIDR block.
This corresponds to the subnet used in a customer data center.
– bgp-asn - The BGP Autonomous System Number (ASN) associated
with a BGP device.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– type - The type of VPN connection. Currently the only supported type is
ipsec.1 .
– vpn-connection-id - The ID of the VPN connection.
– vpn-gateway-id - The ID of a virtual private gateway associated with
the VPN connection.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'VpnConnections': [
{
'VpnConnectionId': 'string',
'State': 'pending'|'available'|'deleting'|'deleted',
'CustomerGatewayConfiguration': 'string',
'Type': 'ipsec.1',
'CustomerGatewayId': 'string',
'VpnGatewayId': 'string',
1350 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VgwTelemetry': [
{
'OutsideIpAddress': 'string',
'Status': 'UP'|'DOWN',
'LastStatusChange': datetime(2015, 1, 1),
'StatusMessage': 'string',
'AcceptedRouteCount': 123
},
],
'Options': {
'StaticRoutesOnly': True|False
},
'Routes': [
{
'DestinationCidrBlock': 'string',
'Source': 'Static',
'State': 'pending'|'available'|'deleting'|'deleted'
},
]
},
]
}
Response Structure
• (dict) –
– VpnConnections (list) –
Information about one or more VPN connections.
* (dict) –
Describes a VPN connection.
· VpnConnectionId (string) –
The ID of the VPN connection.
· State (string) –
The current state of the VPN connection.
· CustomerGatewayConfiguration (string) –
The configuration information for the VPN connection’s
customer gateway (in the native XML format). This el-
ement is always present in the CreateVpnConnection re-
sponse; however, it’s present in the DescribeVpnConnections
response only if the VPN connection is in the pending or
available state.
· Type (string) –
The type of VPN connection.
· CustomerGatewayId (string) –
The ID of the customer gateway at your end of the VPN con-
nection.
· VpnGatewayId (string) –
3.1. Services 1351
Boto3 Documentation, Release 1.1.4
The ID of the virtual private gateway at the AWS side of the
VPN connection.
· Tags (list) –
Any tags assigned to the VPN connection.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· VgwTelemetry (list) –
Information about the VPN tunnel.
· (dict) –
Describes telemetry for a VPN tunnel.
· OutsideIpAddress (string) –
The Internet-routable IP address of the virtual private gate-
way’s outside interface.
· Status (string) –
The status of the VPN tunnel.
· LastStatusChange (datetime) –
The date and time of the last change in status.
· StatusMessage (string) –
If an error occurs, a description of the error.
· AcceptedRouteCount (integer) –
The number of accepted routes.
· Options (dict) –
The VPN connection options.
· StaticRoutesOnly (boolean) –
Indicates whether the VPN connection uses static routes only.
Static routes must be used for devices that don’t support BGP.
· Routes (list) –
The static routes associated with the VPN connection.
· (dict) –
Describes a static route for a VPN connection.
· DestinationCidrBlock (string) –
The CIDR block associated with the local subnet of the cus-
tomer data center.
· Source (string) –
Indicates how the routes were provided.
1352 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· State (string) –
The current state of the static route.
describe_vpn_gateways(**kwargs)
Describes one or more of your virtual private gateways.
For more information about virtual private gateways, see Adding an IPsec Hardware VPN to Your VPC
in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.describe_vpn_gateways(
DryRun=True|False,
VpnGatewayIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpnGatewayIds (list) – One or more virtual private gateway IDs.
Default: Describes all your virtual private gateways.
– (string) –
• Filters (list) – One or more filters.
– attachment.state - The current state of the attachment between
the gateway and the VPC (attaching | attached | detaching |
detached ).
– attachment.vpc-id - The ID of an attached VPC.
– availability-zone - The Availability Zone for the virtual private
gateway.
– state - The state of the virtual private gateway (pending |
available | deleting | deleted ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– type - The type of virtual private gateway. Currently the only supported
type is ipsec.1 .
– vpn-gateway-id - The ID of the virtual private gateway.
3.1. Services 1353
Boto3 Documentation, Release 1.1.4
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Return type dict
Returns
Response Syntax
{
'VpnGateways': [
{
'VpnGatewayId': 'string',
'State': 'pending'|'available'|'deleting'|'deleted',
'Type': 'ipsec.1',
'AvailabilityZone': 'string',
'VpcAttachments': [
{
'VpcId': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached'
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
]
}
Response Structure
• (dict) –
– VpnGateways (list) –
Information about one or more virtual private gateways.
* (dict) –
Describes a virtual private gateway.
· VpnGatewayId (string) –
The ID of the virtual private gateway.
· State (string) –
The current state of the virtual private gateway.
· Type (string) –
The type of VPN connection the virtual private gateway sup-
ports.
· AvailabilityZone (string) –
1354 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The Availability Zone where the virtual private gateway was
created.
· VpcAttachments (list) –
Any VPCs attached to the virtual private gateway.
· (dict) –
Describes an attachment between a virtual private gateway
and a VPC.
· VpcId (string) –
The ID of the VPC.
· State (string) –
The current state of the attachment.
· Tags (list) –
Any tags assigned to the virtual private gateway.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
detach_classic_link_vpc(**kwargs)
Unlinks (detaches) a linked EC2-Classic instance from a VPC. After the instance has been unlinked, the
VPC security groups are no longer associated with it. An instance is automatically unlinked from a VPC
when it’s stopped.
Request Syntax
response = client.detach_classic_link_vpc(
DryRun=True|False,
InstanceId='string',
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the instance to unlink from the VPC.
• VpcId (string) – [REQUIRED]
The ID of the VPC to which the instance is linked.
Return type dict
Returns
Response Syntax
3.1. Services 1355
Boto3 Documentation, Release 1.1.4
{
'Return': True|False
}
Response Structure
• (dict) –
– Return (boolean) –
Returns true if the request succeeds; otherwise, it returns an error.
detach_internet_gateway(**kwargs)
Detaches an Internet gateway from a VPC, disabling connectivity between the Internet and the VPC. The
VPC must not contain any running instances with Elastic IP addresses.
Request Syntax
response = client.detach_internet_gateway(
DryRun=True|False,
InternetGatewayId='string',
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InternetGatewayId (string) – [REQUIRED]
The ID of the Internet gateway.
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Returns None
detach_network_interface(**kwargs)
Detaches a network interface from an instance.
Request Syntax
response = client.detach_network_interface(
DryRun=True|False,
AttachmentId='string',
Force=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• AttachmentId (string) – [REQUIRED]
The ID of the attachment.
• Force (boolean) – Specifies whether to force a detachment.
Returns None
detach_volume(**kwargs)
Detaches an EBS volume from an instance. Make sure to unmount any file systems on the device within
1356 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
your operating system before detaching the volume. Failure to do so results in the volume being stuck in
a busy state while detaching.
If an Amazon EBS volume is the root device of an instance, it can’t be detached while the instance is
running. To detach the root volume, stop the instance first.
When a volume with an AWS Marketplace product code is detached from an instance, the product code
is no longer associated with the instance.
For more information, see Detaching an Amazon EBS Volume in the Amazon Elastic Compute Cloud
User Guide .
Request Syntax
response = client.detach_volume(
DryRun=True|False,
VolumeId='string',
InstanceId='string',
Device='string',
Force=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeId (string) – [REQUIRED]
The ID of the volume.
• InstanceId (string) – The ID of the instance.
• Device (string) – The device name.
• Force (boolean) – Forces detachment if the previous detachment attempt did not
occur cleanly (for example, logging into an instance, unmounting the volume,
and detaching normally). This option can lead to data loss or a corrupted file
system. Use this option only as a last resort to detach a volume from a failed
instance. The instance won’t have an opportunity to flush file system caches or
file system metadata. If you use this option, you must perform file system check
and repair procedures.
Return type dict
Returns
Response Syntax
{
'VolumeId': 'string',
'InstanceId': 'string',
'Device': 'string',
'State': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
}
Response Structure
• (dict) –
Information about the volume attachment.
3.1. Services 1357
Boto3 Documentation, Release 1.1.4
– VolumeId (string) –
The ID of the volume.
– InstanceId (string) –
The ID of the instance.
– Device (string) –
The device name.
– State (string) –
The attachment state of the volume.
– AttachTime (datetime) –
The time stamp when the attachment initiated.
– DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance termination.
detach_vpn_gateway(**kwargs)
Detaches a virtual private gateway from a VPC. You do this if you’re planning to turn off the VPC and not
use it anymore. You can confirm a virtual private gateway has been completely detached from a VPC by
describing the virtual private gateway (any attachments to the virtual private gateway are also described).
You must wait for the attachment’s state to switch to detached before you can delete the VPC or attach
a different VPC to the virtual private gateway.
Request Syntax
response = client.detach_vpn_gateway(
DryRun=True|False,
VpnGatewayId='string',
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpnGatewayId (string) – [REQUIRED]
The ID of the virtual private gateway.
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Returns None
disable_vgw_route_propagation(**kwargs)
Disables a virtual private gateway (VGW) from propagating routes to a specified route table of a VPC.
Request Syntax
response = client.disable_vgw_route_propagation(
RouteTableId='string',
GatewayId='string'
)
Parameters
• RouteTableId (string) – [REQUIRED]
The ID of the route table.
1358 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• GatewayId (string) – [REQUIRED]
The ID of the virtual private gateway.
Returns None
disable_vpc_classic_link(**kwargs)
Disables ClassicLink for a VPC. You cannot disable ClassicLink for a VPC that has EC2-Classic instances
linked to it.
Request Syntax
response = client.disable_vpc_classic_link(
DryRun=True|False,
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Return type dict
Returns
Response Syntax
{
'Return': True|False
}
Response Structure
• (dict) –
– Return (boolean) –
Returns true if the request succeeds; otherwise, it returns an error.
disassociate_address(**kwargs)
Disassociates an Elastic IP address from the instance or network interface it’s associated with.
An Elastic IP address is for use in either the EC2-Classic platform or in a VPC. For more information, see
Elastic IP Addresses in the Amazon Elastic Compute Cloud User Guide .
This is an idempotent operation. If you perform the operation more than once, Amazon EC2 doesn’t
return an error.
Request Syntax
response = client.disassociate_address(
DryRun=True|False,
PublicIp='string',
AssociationId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
3.1. Services 1359
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• PublicIp (string) – [EC2-Classic] The Elastic IP address. Required for EC2-
Classic.
• AssociationId (string) – [EC2-VPC] The association ID. Required for EC2-
VPC.
Returns None
disassociate_route_table(**kwargs)
Disassociates a subnet from a route table.
After you perform this action, the subnet no longer uses the routes in the route table. Instead, it uses the
routes in the VPC’s main route table. For more information about route tables, see Route Tables in the
Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.disassociate_route_table(
DryRun=True|False,
AssociationId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• AssociationId (string) – [REQUIRED]
The association ID representing the current association between the route table
and subnet.
Returns None
enable_vgw_route_propagation(**kwargs)
Enables a virtual private gateway (VGW) to propagate routes to the specified route table of a VPC.
Request Syntax
response = client.enable_vgw_route_propagation(
RouteTableId='string',
GatewayId='string'
)
Parameters
• RouteTableId (string) – [REQUIRED]
The ID of the route table.
• GatewayId (string) – [REQUIRED]
The ID of the virtual private gateway.
Returns None
enable_volume_io(**kwargs)
Enables I/O operations for a volume that had I/O operations disabled because the data on the volume was
potentially inconsistent.
Request Syntax
1360 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.enable_volume_io(
DryRun=True|False,
VolumeId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeId (string) – [REQUIRED]
The ID of the volume.
Returns None
enable_vpc_classic_link(**kwargs)
Enables a VPC for ClassicLink. You can then link EC2-Classic instances to your ClassicLink-enabled
VPC to allow communication over private IP addresses. You cannot enable your VPC for ClassicLink
if any of your VPC’s route tables have existing routes for address ranges within the 10.0.0.0/8 IP
address range, excluding local routes for VPCs in the 10.0.0.0/16 and 10.1.0.0/16 IP address
ranges. For more information, see ClassicLink in the Amazon Elastic Compute Cloud User Guide.
Request Syntax
response = client.enable_vpc_classic_link(
DryRun=True|False,
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Return type dict
Returns
Response Syntax
{
'Return': True|False
}
Response Structure
• (dict) –
– Return (boolean) –
Returns true if the request succeeds; otherwise, it returns an error.
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)
Generate a presigned url given a client, its method, and arguments
Parameters
• ClientMethod (string) – The client method to presign for
• Params (dict) – The parameters normally passed to ClientMethod.
3.1. Services 1361
Boto3 Documentation, Release 1.1.4
• ExpiresIn (int) – The number of seconds the presigned url is valid for. By
default it expires in an hour (3600 seconds)
• HttpMethod (string) – The http method to use on the generated url. By default,
the http method is whatever is used in the method’s model.
Returns The presigned url
get_console_output(**kwargs)
Gets the console output for the specified instance.
Instances do not have a physical monitor through which you can view their console output. They also
lack physical controls that allow you to power up, reboot, or shut them down. To allow these actions, we
provide them through the Amazon EC2 API and command line interface.
Instance console output is buffered and posted shortly after instance boot, reboot, and termination. Ama-
zon EC2 preserves the most recent 64 KB output which is available for at least one hour after the most
recent post.
For Linux instances, the instance console output displays the exact console output that would normally
be displayed on a physical monitor attached to a computer. This output is buffered because the instance
produces it and then posts it to a store where the instance’s owner can retrieve it.
For Windows instances, the instance console output includes output from the EC2Config service.
Request Syntax
response = client.get_console_output(
DryRun=True|False,
InstanceId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the instance.
Return type dict
Returns
Response Syntax
{
'InstanceId': 'string',
'Timestamp': datetime(2015, 1, 1),
'Output': 'string'
}
Response Structure
• (dict) –
– InstanceId (string) –
The ID of the instance.
– Timestamp (datetime) –
The time the output was last updated.
– Output (string) –
The console output, Base64 encoded.
1362 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
get_paginator(operation_name)
Create a paginator for an operation.
Parameters operation_name (string) – The operation name. This is the same name as
the method name on the client. For example, if the method name is create_foo,
and you’d normally invoke the operation as client.create_foo(**kwargs),
if the create_foo operation can be paginated, you can use the call
client.get_paginator("create_foo").
Raises OperationNotPageableError Raised if the operation is not pageable. You can use
the client.can_paginate method to check if an operation is pageable.
Return type L{botocore.paginate.Paginator}
Returns A paginator object.
get_password_data(**kwargs)
Retrieves the encrypted administrator password for an instance running Windows.
The Windows password is generated at boot if the EC2Config service plugin, Ec2SetPassword , is
enabled. This usually only happens the first time an AMI is launched, and then Ec2SetPassword is
automatically disabled. The password is not generated for rebundled AMIs unless Ec2SetPassword
is enabled before bundling.
The password is encrypted using the key pair that you specified when you launched the instance. You
must provide the corresponding key pair file.
Password generation and encryption takes a few moments. We recommend that you wait up to 15 minutes
after launching an instance before trying to retrieve the generated password.
Request Syntax
response = client.get_password_data(
DryRun=True|False,
InstanceId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the Windows instance.
Return type dict
Returns
Response Syntax
{
'InstanceId': 'string',
'Timestamp': datetime(2015, 1, 1),
'PasswordData': 'string'
}
Response Structure
• (dict) –
– InstanceId (string) –
The ID of the Windows instance.
3.1. Services 1363
Boto3 Documentation, Release 1.1.4
– Timestamp (datetime) –
The time the data was last updated.
– PasswordData (string) –
The password of the instance.
get_waiter(waiter_name)
import_image(**kwargs)
Import single or multi-volume disk images or EBS snapshots into an Amazon Machine Image (AMI).
Request Syntax
response = client.import_image(
DryRun=True|False,
Description='string',
DiskContainers=[
{
'Description': 'string',
'Format': 'string',
'Url': 'string',
'UserBucket': {
'S3Bucket': 'string',
'S3Key': 'string'
},
'DeviceName': 'string',
'SnapshotId': 'string'
},
],
LicenseType='string',
Hypervisor='string',
Architecture='string',
Platform='string',
ClientData={
'UploadStart': datetime(2015, 1, 1),
'UploadEnd': datetime(2015, 1, 1),
'UploadSize': 123.0,
'Comment': 'string'
},
ClientToken='string',
RoleName='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Description (string) – A description string for the import image task.
• DiskContainers (list) – Information about the disk containers.
– (dict) –
Describes the disk container object for an import image task.
* Description (string) –
The description of the disk image.
* Format (string) –
The format of the disk image being imported.
1364 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Valid values: RAW | VHD | VMDK | OVA
* Url (string) –
The URL to the Amazon S3-based disk image being imported. The
URL can either be a https URL (https://..) or an Amazon S3 URL
(s3://..)
* UserBucket (dict) –
The S3 bucket for the disk image.
· S3Bucket (string) –
The name of the S3 bucket where the disk image is located.
· S3Key (string) –
The key for the disk image.
* DeviceName (string) –
The block device mapping for the disk.
* SnapshotId (string) –
The ID of the EBS snapshot to be used for importing the snapshot.
• LicenseType (string) – The license type to be used for the Amazon Machine
Image (AMI) after importing.
Note: You may only use BYOL if you have existing licenses with rights to use
these licenses in a third party cloud like AWS. For more information, see VM
Import/Export Prerequisites in the Amazon Elastic Compute Cloud User Guide .
Valid values: AWS | BYOL
• Hypervisor (string) – The target hypervisor platform.
Valid values: xen
• Architecture (string) – The architecture of the virtual machine.
Valid values: i386 | x86_64
• Platform (string) – The operating system of the virtual machine.
Valid values: Windows | Linux
• ClientData (dict) – The client-specific data.
– UploadStart (datetime) –
The time that the disk upload starts.
– UploadEnd (datetime) –
The time that the disk upload ends.
– UploadSize (float) –
The size of the uploaded disk image, in GiB.
– Comment (string) –
A user-defined comment about the disk upload.
• ClientToken (string) – The token to enable idempotency for VM import re-
quests.
• RoleName (string) – The name of the role to use when not using the default role,
‘vmimport’.
Return type dict
Returns
Response Syntax
3.1. Services 1365
Boto3 Documentation, Release 1.1.4
{
'ImportTaskId': 'string',
'Architecture': 'string',
'LicenseType': 'string',
'Platform': 'string',
'Hypervisor': 'string',
'Description': 'string',
'SnapshotDetails': [
{
'DiskImageSize': 123.0,
'Description': 'string',
'Format': 'string',
'Url': 'string',
'UserBucket': {
'S3Bucket': 'string',
'S3Key': 'string'
},
'DeviceName': 'string',
'SnapshotId': 'string',
'Progress': 'string',
'StatusMessage': 'string',
'Status': 'string'
},
],
'ImageId': 'string',
'Progress': 'string',
'StatusMessage': 'string',
'Status': 'string'
}
Response Structure
• (dict) –
– ImportTaskId (string) –
The task ID of the import image task.
– Architecture (string) –
The architecture of the virtual machine.
– LicenseType (string) –
The license type of the virtual machine.
– Platform (string) –
The operating system of the virtual machine.
– Hypervisor (string) –
The target hypervisor of the import task.
– Description (string) –
A description of the import task.
– SnapshotDetails (list) –
Information about the snapshots.
* (dict) –
Describes the snapshot created from the imported disk.
· DiskImageSize (float) –
The size of the disk in the snapshot, in GiB.
· Description (string) –
1366 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A description for the snapshot.
· Format (string) –
The format of the disk image from which the snapshot is cre-
ated.
· Url (string) –
The URL used to access the disk image.
· UserBucket (dict) –
Describes the S3 bucket for the disk image.
· S3Bucket (string) –
The S3 bucket from which the disk image was created.
· S3Key (string) –
The key from which the disk image was created.
· DeviceName (string) –
The block device mapping for the snapshot.
· SnapshotId (string) –
The snapshot ID of the disk being imported.
· Progress (string) –
The percentage of progress for the task.
· StatusMessage (string) –
A detailed status message for the snapshot creation.
· Status (string) –
A brief status of the snapshot creation.
– ImageId (string) –
The ID of the Amazon Machine Image (AMI) created by the import task.
– Progress (string) –
The progress of the task.
– StatusMessage (string) –
A detailed status message of the import task.
– Status (string) –
A brief status of the task.
import_instance(**kwargs)
Creates an import instance task using metadata from the specified disk image. ImportInstance only
supports single-volume VMs. To import multi-volume VMs, use ImportImage . After importing the
image, you then upload it using the ec2-import-volume command in the EC2 command line tools.
For more information, see Using the Command Line Tools to Import Your Virtual Machine to Amazon
EC2 in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.import_instance(
DryRun=True|False,
Description='string',
LaunchSpecification={
'Architecture': 'i386'|'x86_64',
'GroupNames': [
'string',
],
3.1. Services 1367
Boto3 Documentation, Release 1.1.4
'GroupIds': [
'string',
],
'AdditionalInfo': 'string',
'UserData': {
'Data': 'string'
},
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.medium'
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string',
'Tenancy': 'default'|'dedicated'
},
'Monitoring': True|False,
'SubnetId': 'string',
'InstanceInitiatedShutdownBehavior': 'stop'|'terminate',
'PrivateIpAddress': 'string'
},
DiskImages=[
{
'Image': {
'Format': 'VMDK'|'RAW'|'VHD',
'Bytes': 123,
'ImportManifestUrl': 'string'
},
'Description': 'string',
'Volume': {
'Size': 123
}
},
],
Platform='Windows'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Description (string) – A description for the instance being imported.
• LaunchSpecification (dict) – The launch specification.
– Architecture (string) –
The architecture of the instance.
– GroupNames (list) –
One or more security group names.
* (string) –
– GroupIds (list) –
One or more security group IDs.
* (string) –
– AdditionalInfo (string) –
Reserved.
– UserData (dict) –
The Base64-encoded MIME user data to be made available to the instance.
* Data (string) –
1368 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The Base64-encoded MIME user data for the instance.
– InstanceType (string) –
The instance type. For more information about the instance types that you
can import, see Before You Get Started in the Amazon Elastic Compute
Cloud User Guide.
– Placement (dict) –
The placement information for the instance.
* AvailabilityZone (string) –
The Availability Zone of the instance.
* GroupName (string) –
The name of the placement group the instance is in (for cluster com-
pute instances).
* Tenancy (string) –
The tenancy of the instance (if the instance is running in a VPC).
An instance with a tenancy of dedicated runs on single-tenant
hardware.
– Monitoring (boolean) –
Indicates whether monitoring is enabled.
– SubnetId (string) –
[EC2-VPC] The ID of the subnet in which to launch the instance.
– InstanceInitiatedShutdownBehavior (string) –
Indicates whether an instance stops or terminates when you initiate shut-
down from the instance (using the operating system command for system
shutdown).
– PrivateIpAddress (string) –
[EC2-VPC] An available IP address from the IP address range of the sub-
net.
• DiskImages (list) – The disk image.
– (dict) –
Describes a disk image.
* Image (dict) –
Information about the disk image.
· Format (string) – [REQUIRED]
The disk image format.
· Bytes (integer) – [REQUIRED]
The size of the disk image, in GiB.
· ImportManifestUrl (string) – [REQUIRED]
A presigned URL for the import manifest stored in Amazon
S3 and presented here as an Amazon S3 presigned URL. For
information about creating a presigned URL for an Amazon
S3 object, read the “Query String Request Authentication Al-
ternative” section of the Authenticating REST Requests topic
in the Amazon Simple Storage Service Developer Guide .
* Description (string) –
A description of the disk image.
3.1. Services 1369
Boto3 Documentation, Release 1.1.4
* Volume (dict) –
Information about the volume.
· Size (integer) – [REQUIRED]
The size of the volume, in GiB.
• Platform (string) – [REQUIRED]
The instance operating system.
Return type dict
Returns
Response Syntax
{
'ConversionTask': {
'ConversionTaskId': 'string',
'ExpirationTime': 'string',
'ImportInstance': {
'Volumes': [
{
'BytesConverted': 123,
'AvailabilityZone': 'string',
'Image': {
'Format': 'VMDK'|'RAW'|'VHD',
'Size': 123,
'ImportManifestUrl': 'string',
'Checksum': 'string'
},
'Volume': {
'Size': 123,
'Id': 'string'
},
'Status': 'string',
'StatusMessage': 'string',
'Description': 'string'
},
],
'InstanceId': 'string',
'Platform': 'Windows',
'Description': 'string'
},
'ImportVolume': {
'BytesConverted': 123,
'AvailabilityZone': 'string',
'Description': 'string',
'Image': {
'Format': 'VMDK'|'RAW'|'VHD',
'Size': 123,
'ImportManifestUrl': 'string',
'Checksum': 'string'
},
'Volume': {
'Size': 123,
'Id': 'string'
}
},
'State': 'active'|'cancelling'|'cancelled'|'completed',
'StatusMessage': 'string',
1370 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
– ConversionTask (dict) –
Information about the conversion task.
* ConversionTaskId (string) –
The ID of the conversion task.
* ExpirationTime (string) –
The time when the task expires. If the upload isn’t complete before
the expiration time, we automatically cancel the task.
* ImportInstance (dict) –
If the task is for importing an instance, this contains information
about the import instance task.
· Volumes (list) –
One or more volumes.
· (dict) –
Describes an import volume task.
· BytesConverted (integer) –
The number of bytes converted so far.
· AvailabilityZone (string) –
The Availability Zone where the resulting instance will reside.
· Image (dict) –
The image.
· Format (string) –
The disk image format.
· Size (integer) –
The size of the disk image, in GiB.
· ImportManifestUrl (string) –
A presigned URL for the import manifest stored in Amazon
S3. For information about creating a presigned URL for an
Amazon S3 object, read the “Query String Request Authen-
tication Alternative” section of the Authenticating REST Re-
quests topic in the Amazon Simple Storage Service Developer
Guide .
· Checksum (string) –
The checksum computed for the disk image.
· Volume (dict) –
The volume.
3.1. Services 1371
Boto3 Documentation, Release 1.1.4
· Size (integer) –
The size of the volume, in GiB.
· Id (string) –
The volume identifier.
· Status (string) –
The status of the import of this particular disk image.
· StatusMessage (string) –
The status information or errors related to the disk image.
· Description (string) –
A description of the task.
· InstanceId (string) –
The ID of the instance.
· Platform (string) –
The instance operating system.
· Description (string) –
A description of the task.
* ImportVolume (dict) –
If the task is for importing a volume, this contains information about
the import volume task.
· BytesConverted (integer) –
The number of bytes converted so far.
· AvailabilityZone (string) –
The Availability Zone where the resulting volume will reside.
· Description (string) –
The description you provided when starting the import vol-
ume task.
· Image (dict) –
The image.
· Format (string) –
The disk image format.
· Size (integer) –
The size of the disk image, in GiB.
· ImportManifestUrl (string) –
A presigned URL for the import manifest stored in Amazon
S3. For information about creating a presigned URL for an
Amazon S3 object, read the “Query String Request Authen-
tication Alternative” section of the Authenticating REST Re-
quests topic in the Amazon Simple Storage Service Developer
Guide .
· Checksum (string) –
The checksum computed for the disk image.
· Volume (dict) –
The volume.
1372 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Size (integer) –
The size of the volume, in GiB.
· Id (string) –
The volume identifier.
* State (string) –
The state of the conversion task.
* StatusMessage (string) –
The status message related to the conversion task.
* Tags (list) –
Any tags assigned to the task.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
import_key_pair(**kwargs)
Imports the public key from an RSA key pair that you created with a third-party tool. Compare this with
CreateKeyPair , in which AWS creates the key pair and gives the keys to you (AWS keeps a copy of the
public key). With ImportKeyPair, you create the key pair and give AWS just the public key. The private
key is never transferred between you and AWS.
For more information about key pairs, see Key Pairs in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.import_key_pair(
DryRun=True|False,
KeyName='string',
PublicKeyMaterial=b'bytes'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• KeyName (string) – [REQUIRED]
A unique name for the key pair.
• PublicKeyMaterial (bytes) – [REQUIRED]
The public key. You must base64 encode the public key material before sending
it to AWS.
Return type dict
3.1. Services 1373
Boto3 Documentation, Release 1.1.4
Returns
Response Syntax
{
'KeyName': 'string',
'KeyFingerprint': 'string'
}
Response Structure
• (dict) –
– KeyName (string) –
The key pair name you provided.
– KeyFingerprint (string) –
The MD5 public key fingerprint as specified in section 4 of RFC 4716.
import_snapshot(**kwargs)
Imports a disk into an EBS snapshot.
Request Syntax
response = client.import_snapshot(
DryRun=True|False,
Description='string',
DiskContainer={
'Description': 'string',
'Format': 'string',
'Url': 'string',
'UserBucket': {
'S3Bucket': 'string',
'S3Key': 'string'
}
},
ClientData={
'UploadStart': datetime(2015, 1, 1),
'UploadEnd': datetime(2015, 1, 1),
'UploadSize': 123.0,
'Comment': 'string'
},
ClientToken='string',
RoleName='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Description (string) – The description string for the import snapshot task.
• DiskContainer (dict) – Information about the disk container.
– Description (string) –
The description of the disk image being imported.
– Format (string) –
The format of the disk image being imported.
Valid values: RAW | VHD | VMDK | OVA
1374 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– Url (string) –
The URL to the Amazon S3-based disk image being imported. It can
either be a https URL (https://..) or an Amazon S3 URL (s3://..).
– UserBucket (dict) –
Describes the S3 bucket for the disk image.
* S3Bucket (string) –
The name of the S3 bucket where the disk image is located.
* S3Key (string) –
The key for the disk image.
• ClientData (dict) – The client-specific data.
– UploadStart (datetime) –
The time that the disk upload starts.
– UploadEnd (datetime) –
The time that the disk upload ends.
– UploadSize (float) –
The size of the uploaded disk image, in GiB.
– Comment (string) –
A user-defined comment about the disk upload.
• ClientToken (string) – Token to enable idempotency for VM import requests.
• RoleName (string) – The name of the role to use when not using the default role,
‘vmimport’.
Return type dict
Returns
Response Syntax
{
'ImportTaskId': 'string',
'SnapshotTaskDetail': {
'DiskImageSize': 123.0,
'Description': 'string',
'Format': 'string',
'Url': 'string',
'UserBucket': {
'S3Bucket': 'string',
'S3Key': 'string'
},
'SnapshotId': 'string',
'Progress': 'string',
'StatusMessage': 'string',
'Status': 'string'
},
'Description': 'string'
}
Response Structure
• (dict) –
– ImportTaskId (string) –
The ID of the import snapshot task.
– SnapshotTaskDetail (dict) –
Information about the import snapshot task.
3.1. Services 1375
Boto3 Documentation, Release 1.1.4
* DiskImageSize (float) –
The size of the disk in the snapshot, in GiB.
* Description (string) –
The description of the snapshot.
* Format (string) –
The format of the disk image from which the snapshot is created.
* Url (string) –
The URL of the disk image from which the snapshot is created.
* UserBucket (dict) –
The S3 bucket for the disk image.
· S3Bucket (string) –
The S3 bucket from which the disk image was created.
· S3Key (string) –
The key from which the disk image was created.
* SnapshotId (string) –
The snapshot ID of the disk being imported.
* Progress (string) –
The percentage of completion for the import snapshot task.
* StatusMessage (string) –
A detailed status message for the import snapshot task.
* Status (string) –
A brief status for the import snapshot task.
– Description (string) –
A description of the import snapshot task.
import_volume(**kwargs)
Creates an import volume task using metadata from the specified disk image. After importing the image,
you then upload it using the ec2-import-volume command in the Amazon EC2 command-line in-
terface (CLI) tools. For more information, see Using the Command Line Tools to Import Your Virtual
Machine to Amazon EC2 in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.import_volume(
DryRun=True|False,
AvailabilityZone='string',
Image={
'Format': 'VMDK'|'RAW'|'VHD',
'Bytes': 123,
'ImportManifestUrl': 'string'
},
Description='string',
Volume={
'Size': 123
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
1376 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• AvailabilityZone (string) – [REQUIRED]
The Availability Zone for the resulting EBS volume.
• Image (dict) – [REQUIRED]
The disk image.
– Format (string) – [REQUIRED]
The disk image format.
– Bytes (integer) – [REQUIRED]
The size of the disk image, in GiB.
– ImportManifestUrl (string) – [REQUIRED]
A presigned URL for the import manifest stored in Amazon S3 and pre-
sented here as an Amazon S3 presigned URL. For information about cre-
ating a presigned URL for an Amazon S3 object, read the “Query String
Request Authentication Alternative” section of the Authenticating REST
Requests topic in the Amazon Simple Storage Service Developer Guide .
• Description (string) – A description of the volume.
• Volume (dict) – [REQUIRED]
The volume size.
– Size (integer) – [REQUIRED]
The size of the volume, in GiB.
Return type dict
Returns
Response Syntax
{
'ConversionTask': {
'ConversionTaskId': 'string',
'ExpirationTime': 'string',
'ImportInstance': {
'Volumes': [
{
'BytesConverted': 123,
'AvailabilityZone': 'string',
'Image': {
'Format': 'VMDK'|'RAW'|'VHD',
'Size': 123,
'ImportManifestUrl': 'string',
'Checksum': 'string'
},
'Volume': {
'Size': 123,
'Id': 'string'
},
'Status': 'string',
'StatusMessage': 'string',
'Description': 'string'
},
],
'InstanceId': 'string',
'Platform': 'Windows',
'Description': 'string'
3.1. Services 1377
Boto3 Documentation, Release 1.1.4
},
'ImportVolume': {
'BytesConverted': 123,
'AvailabilityZone': 'string',
'Description': 'string',
'Image': {
'Format': 'VMDK'|'RAW'|'VHD',
'Size': 123,
'ImportManifestUrl': 'string',
'Checksum': 'string'
},
'Volume': {
'Size': 123,
'Id': 'string'
}
},
'State': 'active'|'cancelling'|'cancelled'|'completed',
'StatusMessage': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
• (dict) –
– ConversionTask (dict) –
Information about the conversion task.
* ConversionTaskId (string) –
The ID of the conversion task.
* ExpirationTime (string) –
The time when the task expires. If the upload isn’t complete before
the expiration time, we automatically cancel the task.
* ImportInstance (dict) –
If the task is for importing an instance, this contains information
about the import instance task.
· Volumes (list) –
One or more volumes.
· (dict) –
Describes an import volume task.
· BytesConverted (integer) –
The number of bytes converted so far.
· AvailabilityZone (string) –
The Availability Zone where the resulting instance will reside.
· Image (dict) –
The image.
· Format (string) –
The disk image format.
1378 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Size (integer) –
The size of the disk image, in GiB.
· ImportManifestUrl (string) –
A presigned URL for the import manifest stored in Amazon
S3. For information about creating a presigned URL for an
Amazon S3 object, read the “Query String Request Authen-
tication Alternative” section of the Authenticating REST Re-
quests topic in the Amazon Simple Storage Service Developer
Guide .
· Checksum (string) –
The checksum computed for the disk image.
· Volume (dict) –
The volume.
· Size (integer) –
The size of the volume, in GiB.
· Id (string) –
The volume identifier.
· Status (string) –
The status of the import of this particular disk image.
· StatusMessage (string) –
The status information or errors related to the disk image.
· Description (string) –
A description of the task.
· InstanceId (string) –
The ID of the instance.
· Platform (string) –
The instance operating system.
· Description (string) –
A description of the task.
* ImportVolume (dict) –
If the task is for importing a volume, this contains information about
the import volume task.
· BytesConverted (integer) –
The number of bytes converted so far.
· AvailabilityZone (string) –
The Availability Zone where the resulting volume will reside.
· Description (string) –
The description you provided when starting the import vol-
ume task.
· Image (dict) –
The image.
· Format (string) –
The disk image format.
3.1. Services 1379
Boto3 Documentation, Release 1.1.4
· Size (integer) –
The size of the disk image, in GiB.
· ImportManifestUrl (string) –
A presigned URL for the import manifest stored in Amazon
S3. For information about creating a presigned URL for an
Amazon S3 object, read the “Query String Request Authen-
tication Alternative” section of the Authenticating REST Re-
quests topic in the Amazon Simple Storage Service Developer
Guide .
· Checksum (string) –
The checksum computed for the disk image.
· Volume (dict) –
The volume.
· Size (integer) –
The size of the volume, in GiB.
· Id (string) –
The volume identifier.
* State (string) –
The state of the conversion task.
* StatusMessage (string) –
The status message related to the conversion task.
* Tags (list) –
Any tags assigned to the task.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
modify_image_attribute(**kwargs)
Modifies the specified attribute of the specified AMI. You can specify only one attribute at a time.
Note: AWS Marketplace product codes cannot be modified. Images with an AWS Marketplace product
code cannot be made public.
Request Syntax
response = client.modify_image_attribute(
DryRun=True|False,
ImageId='string',
Attribute='string',
OperationType='add'|'remove',
1380 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
UserIds=[
'string',
],
UserGroups=[
'string',
],
ProductCodes=[
'string',
],
Value='string',
LaunchPermission={
'Add': [
{
'UserId': 'string',
'Group': 'all'
},
],
'Remove': [
{
'UserId': 'string',
'Group': 'all'
},
]
},
Description={
'Value': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageId (string) – [REQUIRED]
The ID of the AMI.
• Attribute (string) – The name of the attribute to modify.
• OperationType (string) – The operation type.
• UserIds (list) – One or more AWS account IDs. This is only valid when modi-
fying the launchPermission attribute.
– (string) –
• UserGroups (list) – One or more user groups. This is only valid when modifying
the launchPermission attribute.
– (string) –
• ProductCodes (list) – One or more product codes. After you add a product
code to an AMI, it can’t be removed. This is only valid when modifying the
productCodes attribute.
– (string) –
• Value (string) – The value of the attribute being modified. This is only valid
when modifying the description attribute.
• LaunchPermission (dict) – A launch permission modification.
– Add (list) –
The AWS account ID to add to the list of launch permissions for the AMI.
* (dict) –
3.1. Services 1381
Boto3 Documentation, Release 1.1.4
Describes a launch permission.
· UserId (string) –
The AWS account ID.
· Group (string) –
The name of the group.
– Remove (list) –
The AWS account ID to remove from the list of launch permissions for the
AMI.
* (dict) –
Describes a launch permission.
· UserId (string) –
The AWS account ID.
· Group (string) –
The name of the group.
• Description (dict) – A description for the AMI.
– Value (string) –
Valid values are case-sensitive and vary by action.
Returns None
modify_instance_attribute(**kwargs)
Modifies the specified attribute of the specified instance. You can specify only one attribute at a time.
To modify some attributes, the instance must be stopped. For more information, see Modifying Attributes
of a Stopped Instance in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.modify_instance_attribute(
DryRun=True|False,
InstanceId='string',
Attribute='instanceType'|'kernel'|'ramdisk'|'userData'|'disableApiTermination'|'instance
Value='string',
BlockDeviceMappings=[
{
'DeviceName': 'string',
'Ebs': {
'VolumeId': 'string',
'DeleteOnTermination': True|False
},
'VirtualName': 'string',
'NoDevice': 'string'
},
],
SourceDestCheck={
'Value': True|False
},
DisableApiTermination={
'Value': True|False
},
InstanceType={
'Value': 'string'
},
Kernel={
'Value': 'string'
1382 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
Ramdisk={
'Value': 'string'
},
UserData={
'Value': b'bytes'
},
InstanceInitiatedShutdownBehavior={
'Value': 'string'
},
Groups=[
'string',
],
EbsOptimized={
'Value': True|False
},
SriovNetSupport={
'Value': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the instance.
• Attribute (string) – The name of the attribute.
• Value (string) – A new value for the attribute. Use only with the
kernel , ramdisk , userData , disableApiTermination , or
instanceInitiatedShutdownBehavior attribute.
• BlockDeviceMappings (list) – Modifies the DeleteOnTermination at-
tribute for volumes that are currently attached. The volume must be owned by
the caller. If no value is specified for DeleteOnTermination , the default is
true and the volume is deleted when the instance is terminated.
To add instance store volumes to an Amazon EBS-backed instance, you must
add them when you launch the instance. For more information, see Updating
the Block Device Mapping when Launching an Instance in the Amazon Elastic
Compute Cloud User Guide .
– (dict) –
Describes a block device mapping entry.
* DeviceName (string) –
The device name exposed to the instance (for example, /dev/sdh
or xvdh ).
* Ebs (dict) –
Parameters used to automatically set up EBS volumes when the in-
stance is launched.
· VolumeId (string) –
The ID of the EBS volume.
· DeleteOnTermination (boolean) –
3.1. Services 1383
Boto3 Documentation, Release 1.1.4
Indicates whether the volume is deleted on instance termina-
tion.
* VirtualName (string) –
The virtual device name.
* NoDevice (string) –
suppress the specified device included in the block device mapping.
• SourceDestCheck (dict) – Specifies whether source/destination checking is en-
abled. A value of true means that checking is enabled, and false means
checking is disabled. This value must be false for a NAT instance to perform
NAT.
– Value (boolean) –
Valid values are true or false .
• DisableApiTermination (dict) – If the value is true , you can’t terminate the
instance using the Amazon EC2 console, CLI, or API; otherwise, you can. You
cannot use this paramater for Spot Instances.
– Value (boolean) –
Valid values are true or false .
• InstanceType (dict) – Changes the instance type to the specified value. For
more information, see Instance Types . If the instance type is not valid, the error
returned is InvalidInstanceAttributeValue .
– Value (string) –
Valid values are case-sensitive and vary by action.
• Kernel (dict) – Changes the instance’s kernel to the specified value. We rec-
ommend that you use PV-GRUB instead of kernels and RAM disks. For more
information, see PV-GRUB .
– Value (string) –
Valid values are case-sensitive and vary by action.
• Ramdisk (dict) – Changes the instance’s RAM disk to the specified value. We
recommend that you use PV-GRUB instead of kernels and RAM disks. For more
information, see PV-GRUB .
– Value (string) –
Valid values are case-sensitive and vary by action.
• UserData (dict) – Changes the instance’s user data to the specified value.
– Value (bytes) –
• InstanceInitiatedShutdownBehavior (dict) – Specifies whether an instance
stops or terminates when you initiate shutdown from the instance (using the op-
erating system command for system shutdown).
– Value (string) –
Valid values are case-sensitive and vary by action.
• Groups (list) – [EC2-VPC] Changes the security groups of the instance. You
must specify at least one security group, even if it’s just the default security
group for the VPC. You must specify the security group ID, not the security
group name.
– (string) –
• EbsOptimized (dict) – Specifies whether the instance is optimized for EBS I/O.
This optimization provides dedicated throughput to Amazon EBS and an opti-
mized configuration stack to provide optimal EBS I/O performance. This opti-
mization isn’t available with all instance types. Additional usage charges apply
when using an EBS Optimized instance.
– Value (boolean) –
1384 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Valid values are true or false .
• SriovNetSupport (dict) – Set to simple to enable enhanced networking for
the instance.
There is no way to disable enhanced networking at this time.
This option is supported only for HVM instances. Specifying this option with a
PV instance can make it unreachable.
– Value (string) –
Valid values are case-sensitive and vary by action.
Returns None
modify_network_interface_attribute(**kwargs)
Modifies the specified network interface attribute. You can specify only one attribute at a time.
Request Syntax
response = client.modify_network_interface_attribute(
DryRun=True|False,
NetworkInterfaceId='string',
Description={
'Value': 'string'
},
SourceDestCheck={
'Value': True|False
},
Groups=[
'string',
],
Attachment={
'AttachmentId': 'string',
'DeleteOnTermination': True|False
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkInterfaceId (string) – [REQUIRED]
The ID of the network interface.
• Description (dict) – A description for the network interface.
– Value (string) –
Valid values are case-sensitive and vary by action.
• SourceDestCheck (dict) – Indicates whether source/destination checking is en-
abled. A value of true means checking is enabled, and false means checking
is disabled. This value must be false for a NAT instance to perform NAT. For
more information, see NAT Instances in the Amazon Virtual Private Cloud User
Guide .
– Value (boolean) –
Valid values are true or false .
• Groups (list) – Changes the security groups for the network interface. The new
set of groups you specify replaces the current set. You must specify at least one
3.1. Services 1385
Boto3 Documentation, Release 1.1.4
group, even if it’s just the default security group in the VPC. You must specify
the ID of the security group, not the name.
– (string) –
• Attachment (dict) – Information about the interface attachment. If modifying
the ‘delete on termination’ attribute, you must specify the ID of the interface
attachment.
– AttachmentId (string) –
The ID of the network interface attachment.
– DeleteOnTermination (boolean) –
Indicates whether the network interface is deleted when the instance is
terminated.
Returns None
modify_reserved_instances(**kwargs)
Modifies the Availability Zone, instance count, instance type, or network platform (EC2-Classic or EC2-
VPC) of your Reserved Instances. The Reserved Instances to be modified must be identical, except for
Availability Zone, network platform, and instance type.
For more information, see Modifying Reserved Instances in the Amazon Elastic Compute Cloud User
Guide.
Request Syntax
response = client.modify_reserved_instances(
ClientToken='string',
ReservedInstancesIds=[
'string',
],
TargetConfigurations=[
{
'AvailabilityZone': 'string',
'Platform': 'string',
'InstanceCount': 123,
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.med
},
]
)
Parameters
• ClientToken (string) – A unique, case-sensitive token you provide to ensure
idempotency of your modification request. For more information, see Ensuring
Idempotency .
• ReservedInstancesIds (list) – [REQUIRED]
The IDs of the Reserved Instances to modify.
– (string) –
• TargetConfigurations (list) – [REQUIRED]
The configuration settings for the Reserved Instances to modify.
– (dict) –
Describes the configuration settings for the modified Reserved Instances.
* AvailabilityZone (string) –
The Availability Zone for the modified Reserved Instances.
* Platform (string) –
1386 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The network platform of the modified Reserved Instances, which is
either EC2-Classic or EC2-VPC.
* InstanceCount (integer) –
The number of modified Reserved Instances.
* InstanceType (string) –
The instance type for the modified Reserved Instances.
Return type dict
Returns
Response Syntax
{
'ReservedInstancesModificationId': 'string'
}
Response Structure
• (dict) –
– ReservedInstancesModificationId (string) –
The ID for the modification.
modify_snapshot_attribute(**kwargs)
Adds or removes permission settings for the specified snapshot. You may add or remove specified AWS
account IDs from a snapshot’s list of create volume permissions, but you cannot do both in a single API
call. If you need to both add and remove account IDs for a snapshot, you must use multiple API calls.
For more information on modifying snapshot permissions, see Sharing Snapshots in the Amazon Elastic
Compute Cloud User Guide .
Note: Snapshots with AWS Marketplace product codes cannot be made public.
Request Syntax
response = client.modify_snapshot_attribute(
DryRun=True|False,
SnapshotId='string',
Attribute='productCodes'|'createVolumePermission',
OperationType='add'|'remove',
UserIds=[
'string',
],
GroupNames=[
'string',
],
CreateVolumePermission={
'Add': [
{
'UserId': 'string',
'Group': 'all'
},
],
'Remove': [
{
'UserId': 'string',
'Group': 'all'
},
]
3.1. Services 1387
Boto3 Documentation, Release 1.1.4
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SnapshotId (string) – [REQUIRED]
The ID of the snapshot.
• Attribute (string) – The snapshot attribute to modify.
Note: Only volume creation permissions may be modified at the customer level.
• OperationType (string) – The type of operation to perform to the attribute.
• UserIds (list) – The account ID to modify for the snapshot.
– (string) –
• GroupNames (list) – The group to modify for the snapshot.
– (string) –
• CreateVolumePermission (dict) – A JSON representation of the snapshot at-
tribute modification.
– Add (list) –
Adds a specific AWS account ID or group to a volume’s list of create
volume permissions.
* (dict) –
Describes the user or group to be added or removed from the per-
missions for a volume.
· UserId (string) –
The specific AWS account ID that is to be added or removed
from a volume’s list of create volume permissions.
· Group (string) –
The specific group that is to be added or removed from a vol-
ume’s list of create volume permissions.
– Remove (list) –
Removes a specific AWS account ID or group from a volume’s list of
create volume permissions.
* (dict) –
Describes the user or group to be added or removed from the per-
missions for a volume.
· UserId (string) –
The specific AWS account ID that is to be added or removed
from a volume’s list of create volume permissions.
· Group (string) –
The specific group that is to be added or removed from a vol-
ume’s list of create volume permissions.
Returns None
modify_subnet_attribute(**kwargs)
Modifies a subnet attribute.
Request Syntax
1388 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
response = client.modify_subnet_attribute(
SubnetId='string',
MapPublicIpOnLaunch={
'Value': True|False
}
)
Parameters
• SubnetId (string) – [REQUIRED]
The ID of the subnet.
• MapPublicIpOnLaunch (dict) – Specify true to indicate that instances
launched into the specified subnet should be assigned public IP address.
– Value (boolean) –
Valid values are true or false .
Returns None
modify_volume_attribute(**kwargs)
Modifies a volume attribute.
By default, all I/O operations for the volume are suspended when the data on the volume is determined to
be potentially inconsistent, to prevent undetectable, latent data corruption. The I/O access to the volume
can be resumed by first enabling I/O access and then checking the data consistency on your volume.
You can change the default behavior to resume I/O operations. We recommend that you change this only
for boot volumes or for volumes that are stateless or disposable.
Request Syntax
response = client.modify_volume_attribute(
DryRun=True|False,
VolumeId='string',
AutoEnableIO={
'Value': True|False
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeId (string) – [REQUIRED]
The ID of the volume.
• AutoEnableIO (dict) – Indicates whether the volume should be auto-enabled for
I/O operations.
– Value (boolean) –
Valid values are true or false .
Returns None
modify_vpc_attribute(**kwargs)
Modifies the specified attribute of the specified VPC.
Request Syntax
3.1. Services 1389
Boto3 Documentation, Release 1.1.4
response = client.modify_vpc_attribute(
VpcId='string',
EnableDnsSupport={
'Value': True|False
},
EnableDnsHostnames={
'Value': True|False
}
)
Parameters
• VpcId (string) – [REQUIRED]
The ID of the VPC.
• EnableDnsSupport (dict) – Indicates whether the DNS resolution is supported
for the VPC. If enabled, queries to the Amazon provided DNS server at the
169.254.169.253 IP address, or the reserved IP address at the base of the VPC
network range “plus two” will succeed. If disabled, the Amazon provided DNS
service in the VPC that resolves public DNS hostnames to IP addresses is not
enabled.
– Value (boolean) –
Valid values are true or false .
• EnableDnsHostnames (dict) – Indicates whether the instances launched in the
VPC get DNS hostnames. If enabled, instances in the VPC get DNS hostnames;
otherwise, they do not.
You can only enable DNS hostnames if you also enable DNS support.
– Value (boolean) –
Valid values are true or false .
Returns None
modify_vpc_endpoint(**kwargs)
Modifies attributes of a specified VPC endpoint. You can modify the policy associated with the endpoint,
and you can add and remove route tables associated with the endpoint.
Request Syntax
response = client.modify_vpc_endpoint(
DryRun=True|False,
VpcEndpointId='string',
ResetPolicy=True|False,
PolicyDocument='string',
AddRouteTableIds=[
'string',
],
RemoveRouteTableIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
1390 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• VpcEndpointId (string) – [REQUIRED]
The ID of the endpoint.
• ResetPolicy (boolean) – Specify true to reset the policy document to the de-
fault policy. The default policy allows access to the service.
• PolicyDocument (string) – A policy document to attach to the endpoint. The
policy must be in valid JSON format.
• AddRouteTableIds (list) – One or more route tables IDs to associate with the
endpoint.
– (string) –
• RemoveRouteTableIds (list) – One or more route table IDs to disassociate from
the endpoint.
– (string) –
Return type dict
Returns
Response Syntax
{
'Return': True|False
}
Response Structure
• (dict) –
– Return (boolean) –
Returns true if the request succeeds; otherwise, it returns an error.
monitor_instances(**kwargs)
Enables monitoring for a running instance. For more information about monitoring instances, see Moni-
toring Your Instances and Volumes in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.monitor_instances(
DryRun=True|False,
InstanceIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – [REQUIRED]
One or more instance IDs.
– (string) –
Return type dict
Returns
Response Syntax
{
'InstanceMonitorings': [
{
3.1. Services 1391
Boto3 Documentation, Release 1.1.4
'InstanceId': 'string',
'Monitoring': {
'State': 'disabled'|'disabling'|'enabled'|'pending'
}
},
]
}
Response Structure
• (dict) –
– InstanceMonitorings (list) –
Monitoring information for one or more instances.
* (dict) –
Describes the monitoring information of the instance.
· InstanceId (string) –
The ID of the instance.
· Monitoring (dict) –
The monitoring information.
· State (string) –
Indicates whether monitoring is enabled for the instance.
move_address_to_vpc(**kwargs)
Moves an Elastic IP address from the EC2-Classic platform to the EC2-VPC platform. The Elastic IP
address must be allocated to your account, and it must not be associated with an instance. After the
Elastic IP address is moved, it is no longer available for use in the EC2-Classic platform, unless you
move it back using the RestoreAddressToClassic request. You cannot move an Elastic IP address that’s
allocated for use in the EC2-VPC platform to the EC2-Classic platform.
Request Syntax
response = client.move_address_to_vpc(
DryRun=True|False,
PublicIp='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• PublicIp (string) – [REQUIRED]
The Elastic IP address.
Return type dict
Returns
Response Syntax
{
'AllocationId': 'string',
'Status': 'MoveInProgress'|'InVpc'|'InClassic'
}
Response Structure
• (dict) –
1392 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– AllocationId (string) –
The allocation ID for the Elastic IP address.
– Status (string) –
The status of the move of the IP address.
purchase_reserved_instances_offering(**kwargs)
Purchases a Reserved Instance for use with your account. With Amazon EC2 Reserved Instances, you
obtain a capacity reservation for a certain instance configuration over a specified period of time and pay a
lower hourly rate compared to on-Demand Instance pricing.
Use DescribeReservedInstancesOfferings to get a list of Reserved Instance offerings that match your
specifications. After you’ve purchased a Reserved Instance, you can check for your new Reserved Instance
with DescribeReservedInstances .
For more information, see Reserved Instances and Reserved Instance Marketplace in the Amazon Elastic
Compute Cloud User Guide .
Request Syntax
response = client.purchase_reserved_instances_offering(
DryRun=True|False,
ReservedInstancesOfferingId='string',
InstanceCount=123,
LimitPrice={
'Amount': 123.0,
'CurrencyCode': 'USD'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ReservedInstancesOfferingId (string) – [REQUIRED]
The ID of the Reserved Instance offering to purchase.
• InstanceCount (integer) – [REQUIRED]
The number of Reserved Instances to purchase.
• LimitPrice (dict) – Specified for Reserved Instance Marketplace offerings to
limit the total order and ensure that the Reserved Instances are not purchased at
unexpected prices.
– Amount (float) –
Used for Reserved Instance Marketplace offerings. Specifies the limit
price on the total order (instanceCount * price).
– CurrencyCode (string) –
The currency in which the limitPrice amount is specified. At this
time, the only supported currency is USD .
Return type dict
Returns
Response Syntax
3.1. Services 1393
Boto3 Documentation, Release 1.1.4
{
'ReservedInstancesId': 'string'
}
Response Structure
• (dict) –
– ReservedInstancesId (string) –
The IDs of the purchased Reserved Instances.
reboot_instances(**kwargs)
Requests a reboot of one or more instances. This operation is asynchronous; it only queues a request
to reboot the specified instances. The operation succeeds if the instances are valid and belong to you.
Requests to reboot terminated instances are ignored.
If a Linux/Unix instance does not cleanly shut down within four minutes, Amazon EC2 performs a hard
reboot.
For more information about troubleshooting, see Getting Console Output and Rebooting Instances in the
Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.reboot_instances(
DryRun=True|False,
InstanceIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – [REQUIRED]
One or more instance IDs.
– (string) –
Returns None
register_image(**kwargs)
Registers an AMI. When you’re creating an AMI, this is the final step you must complete before you can
launch an instance from the AMI. For more information about creating AMIs, see Creating Your Own
AMIs in the Amazon Elastic Compute Cloud User Guide .
Note: For Amazon EBS-backed instances, CreateImage creates and registers the AMI in a single request,
so you don’t have to register the AMI yourself.
You can also use RegisterImage to create an Amazon EBS-backed Linux AMI from a snapshot of
a root device volume. For more information, see Launching an Instance from a Snapshot in the Amazon
Elastic Compute Cloud User Guide .
1394 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Warning: Some Linux distributions, such as Red Hat Enterprise Linux (RHEL) and SUSE Linux
Enterprise Server (SLES), use the EC2 billingProduct code associated with an AMI to verify
subscription status for package updates. Creating an AMI from an EBS snapshot does not maintain
this billing code, and subsequent instances launched from such an AMI will not be able to connect to
package update infrastructure.
Similarly, although you can create a Windows AMI from a snapshot, you can’t successfully launch an
instance from the AMI.
To create Windows AMIs or to create AMIs for Linux operating systems that must retain AMI billing
codes to work properly, see CreateImage .
If needed, you can deregister an AMI at any time. Any modifications you make to an AMI backed by an
instance store volume invalidates its registration. If you make changes to an image, deregister the previous
image and register the new image.
Note: You can’t register an image where a secondary (non-root) snapshot has AWS Marketplace product
codes.
Request Syntax
response = client.register_image(
DryRun=True|False,
ImageLocation='string',
Name='string',
Description='string',
Architecture='i386'|'x86_64',
KernelId='string',
RamdiskId='string',
RootDeviceName='string',
BlockDeviceMappings=[
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
},
],
VirtualizationType='string',
SriovNetSupport='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageLocation (string) – The full path to your AMI manifest in Amazon S3
storage.
• Name (string) – [REQUIRED]
3.1. Services 1395
Boto3 Documentation, Release 1.1.4
A name for your AMI.
Constraints: 3-128 alphanumeric characters, parentheses (()), square brackets
([]), spaces ( ), periods (.), slashes (/), dashes (-), single quotes (‘), at-signs (@),
or underscores(_)
• Description (string) – A description for your AMI.
• Architecture (string) – The architecture of the AMI.
Default: For Amazon EBS-backed AMIs, i386 . For instance store-backed
AMIs, the architecture specified in the manifest file.
• KernelId (string) – The ID of the kernel.
• RamdiskId (string) – The ID of the RAM disk.
• RootDeviceName (string) – The name of the root device (for example,
/dev/sda1 , or /dev/xvda ).
• BlockDeviceMappings (list) – One or more block device mapping entries.
– (dict) –
Describes a block device mapping.
* VirtualName (string) –
The virtual device name (ephemeral N). Instance store volumes
are numbered starting from 0. An instance type with 2 available in-
stance store volumes can specify mappings for ephemeral0 and
ephemeral1 .The number of available instance store volumes de-
pends on the instance type. After you connect to the instance, you
must mount the volume.
Constraints: For M3 instances, you must specify instance store vol-
umes in the block device mapping for the instance. When you
launch an M3 instance, we ignore any instance store volumes spec-
ified in the block device mapping for the AMI.
* DeviceName (string) –
The device name exposed to the instance (for example, /dev/sdh
or xvdh ).
* Ebs (dict) –
Parameters used to automatically set up EBS volumes when the in-
stance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
1396 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
* NoDevice (string) –
Suppresses the specified device included in the block device map-
ping of the AMI.
• VirtualizationType (string) – The type of virtualization.
Default: paravirtual
• SriovNetSupport (string) – Set to simple to enable enhanced networking for
the AMI and any instances that you launch from the AMI.
There is no way to disable enhanced networking at this time.
This option is supported only for HVM AMIs. Specifying this option with a PV
AMI can make instances launched from the AMI unreachable.
Return type dict
Returns
Response Syntax
{
'ImageId': 'string'
}
Response Structure
• (dict) –
– ImageId (string) –
The ID of the newly registered AMI.
reject_vpc_peering_connection(**kwargs)
Rejects a VPC peering connection request. The VPC peering connection must be in the
3.1. Services 1397
Boto3 Documentation, Release 1.1.4
pending-acceptance state. Use the DescribeVpcPeeringConnections request to view your outstand-
ing VPC peering connection requests. To delete an active VPC peering connection, or to delete a VPC
peering connection request that you initiated, use DeleteVpcPeeringConnection .
Request Syntax
response = client.reject_vpc_peering_connection(
DryRun=True|False,
VpcPeeringConnectionId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcPeeringConnectionId (string) – [REQUIRED]
The ID of the VPC peering connection.
Return type dict
Returns
Response Syntax
{
'Return': True|False
}
Response Structure
• (dict) –
– Return (boolean) –
Returns true if the request succeeds; otherwise, it returns an error.
release_address(**kwargs)
Releases the specified Elastic IP address.
After releasing an Elastic IP address, it is released to the IP address pool and might be unavailable to you.
Be sure to update your DNS records and any servers or devices that communicate with the address. If you
attempt to release an Elastic IP address that you already released, you’ll get an AuthFailure error if
the address is already allocated to another AWS account.
[EC2-Classic, default VPC] Releasing an Elastic IP address automatically disassociates it from any in-
stance that it’s associated with. To disassociate an Elastic IP address without releasing it, use Disassoci-
ateAddress .
[Nondefault VPC] You must use DisassociateAddress to disassociate the Elastic IP address before you try
to release it. Otherwise, Amazon EC2 returns an error (InvalidIPAddress.InUse ).
Request Syntax
response = client.release_address(
DryRun=True|False,
PublicIp='string',
AllocationId='string'
)
Parameters
1398 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• PublicIp (string) – [EC2-Classic] The Elastic IP address. Required for EC2-
Classic.
• AllocationId (string) – [EC2-VPC] The allocation ID. Required for EC2-VPC.
Returns None
replace_network_acl_association(**kwargs)
Changes which network ACL a subnet is associated with. By default when you create a subnet, it’s
automatically associated with the default network ACL. For more information about network ACLs, see
Network ACLs in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.replace_network_acl_association(
DryRun=True|False,
AssociationId='string',
NetworkAclId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• AssociationId (string) – [REQUIRED]
The ID of the current association between the original network ACL and the
subnet.
• NetworkAclId (string) – [REQUIRED]
The ID of the new network ACL to associate with the subnet.
Return type dict
Returns
Response Syntax
{
'NewAssociationId': 'string'
}
Response Structure
• (dict) –
– NewAssociationId (string) –
The ID of the new association.
replace_network_acl_entry(**kwargs)
Replaces an entry (rule) in a network ACL. For more information about network ACLs, see Network
ACLs in the Amazon Virtual Private Cloud User Guide .
Request Syntax
response = client.replace_network_acl_entry(
DryRun=True|False,
NetworkAclId='string',
RuleNumber=123,
3.1. Services 1399
Boto3 Documentation, Release 1.1.4
Protocol='string',
RuleAction='allow'|'deny',
Egress=True|False,
CidrBlock='string',
IcmpTypeCode={
'Type': 123,
'Code': 123
},
PortRange={
'From': 123,
'To': 123
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkAclId (string) – [REQUIRED]
The ID of the ACL.
• RuleNumber (integer) – [REQUIRED]
The rule number of the entry to replace.
• Protocol (string) – [REQUIRED]
The IP protocol. You can specify all or -1 to mean all protocols.
• RuleAction (string) – [REQUIRED]
Indicates whether to allow or deny the traffic that matches the rule.
• Egress (boolean) – [REQUIRED]
Indicates whether to replace the egress rule.
Default: If no value is specified, we replace the ingress rule.
• CidrBlock (string) – [REQUIRED]
The network range to allow or deny, in CIDR notation.
• IcmpTypeCode (dict) – ICMP protocol: The ICMP type and code. Required if
specifying 1 (ICMP) for the protocol.
– Type (integer) –
The ICMP code. A value of -1 means all codes for the specified ICMP
type.
– Code (integer) –
The ICMP type. A value of -1 means all types.
• PortRange (dict) – TCP or UDP protocols: The range of ports the rule applies
to. Required if specifying 6 (TCP) or 17 (UDP) for the protocol.
– From (integer) –
The first port in the range.
– To (integer) –
The last port in the range.
Returns None
replace_route(**kwargs)
Replaces an existing route within a route table in a VPC. You must provide only one of the following:
Internet gateway or virtual private gateway, NAT instance, VPC peering connection, or network interface.
1400 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
For more information about route tables, see Route Tables in the Amazon Virtual Private Cloud User
Guide .
Request Syntax
response = client.replace_route(
DryRun=True|False,
RouteTableId='string',
DestinationCidrBlock='string',
GatewayId='string',
InstanceId='string',
NetworkInterfaceId='string',
VpcPeeringConnectionId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• RouteTableId (string) – [REQUIRED]
The ID of the route table.
• DestinationCidrBlock (string) – [REQUIRED]
The CIDR address block used for the destination match. The value you provide
must match the CIDR of an existing route in the table.
• GatewayId (string) – The ID of an Internet gateway or virtual private gateway.
• InstanceId (string) – The ID of a NAT instance in your VPC.
• NetworkInterfaceId (string) – The ID of a network interface.
• VpcPeeringConnectionId (string) – The ID of a VPC peering connection.
Returns None
replace_route_table_association(**kwargs)
Changes the route table associated with a given subnet in a VPC. After the operation completes, the subnet
uses the routes in the new route table it’s associated with. For more information about route tables, see
Route Tables in the Amazon Virtual Private Cloud User Guide .
You can also use ReplaceRouteTableAssociation to change which table is the main route table in the VPC.
You just specify the main route table’s association ID and the route table to be the new main route table.
Request Syntax
response = client.replace_route_table_association(
DryRun=True|False,
AssociationId='string',
RouteTableId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• AssociationId (string) – [REQUIRED]
The association ID.
3.1. Services 1401
Boto3 Documentation, Release 1.1.4
• RouteTableId (string) – [REQUIRED]
The ID of the new route table to associate with the subnet.
Return type dict
Returns
Response Syntax
{
'NewAssociationId': 'string'
}
Response Structure
• (dict) –
– NewAssociationId (string) –
The ID of the new association.
report_instance_status(**kwargs)
Submits feedback about the status of an instance. The instance must be in the running state. If your
experience with the instance differs from the instance status returned by DescribeInstanceStatus , use
ReportInstanceStatus to report your experience with the instance. Amazon EC2 collects this information
to improve the accuracy of status checks.
Use of this action does not change the value returned by DescribeInstanceStatus .
Request Syntax
response = client.report_instance_status(
DryRun=True|False,
Instances=[
'string',
],
Status='ok'|'impaired',
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
ReasonCodes=[
'instance-stuck-in-state'|'unresponsive'|'not-accepting-credentials'|'password-not-a
],
Description='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Instances (list) – [REQUIRED]
One or more instances.
– (string) –
• Status (string) – [REQUIRED]
The status of all instances listed.
• StartTime (datetime) – The time at which the reported instance health state
began.
• EndTime (datetime) – The time at which the reported instance health state
ended.
1402 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• ReasonCodes (list) – [REQUIRED]
One or more reason codes that describes the health state of your instance.
– instance-stuck-in-state : My instance is stuck in a state.
– unresponsive : My instance is unresponsive.
– not-accepting-credentials : My instance is not accepting my
credentials.
– password-not-available : A password is not available for my in-
stance.
– performance-network : My instance is experiencing performance
problems which I believe are network related.
– performance-instance-store : My instance is experiencing per-
formance problems which I believe are related to the instance stores.
– performance-ebs-volume : My instance is experiencing perfor-
mance problems which I believe are related to an EBS volume.
– performance-other : My instance is experiencing performance
problems.
– other : [explain using the description parameter]
– (string) –
• Description (string) – Descriptive text about the health state of your instance.
Returns None
request_spot_fleet(**kwargs)
Creates a Spot fleet request.
You can submit a single request that includes multiple launch specifications that vary by instance type,
AMI, Availability Zone, or subnet.
By default, the Spot fleet requests Spot instances in the Spot pool where the price per unit is the lowest.
Each launch specification can include its own instance weighting that reflects the value of the instance
type to your application workload.
Alternatively, you can specify that the Spot fleet distribute the target capacity across the Spot pools in-
cluded in its launch specifications. By ensuring that the Spot instances in your Spot fleet are in different
Spot pools, you can improve the availability of your fleet.
For more information, see Spot Fleet Requests in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.request_spot_fleet(
DryRun=True|False,
SpotFleetRequestConfig={
'ClientToken': 'string',
'SpotPrice': 'string',
'TargetCapacity': 123,
'ValidFrom': datetime(2015, 1, 1),
'ValidUntil': datetime(2015, 1, 1),
'TerminateInstancesWithExpiration': True|False,
'IamFleetRole': 'string',
'LaunchSpecifications': [
{
'ImageId': 'string',
'KeyName': 'string',
'SecurityGroups': [
{
'GroupName': 'string',
'GroupId': 'string'
3.1. Services 1403
Boto3 Documentation, Release 1.1.4
},
],
'UserData': 'string',
'AddressingType': 'string',
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string'
},
'KernelId': 'string',
'RamdiskId': 'string',
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
},
],
'Monitoring': {
'Enabled': True|False
},
'SubnetId': 'string',
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'DeviceIndex': 123,
'SubnetId': 'string',
'Description': 'string',
'PrivateIpAddress': 'string',
'Groups': [
'string',
],
'DeleteOnTermination': True|False,
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
'SecondaryPrivateIpAddressCount': 123,
'AssociatePublicIpAddress': True|False
},
],
'IamInstanceProfile': {
'Arn': 'string',
'Name': 'string'
},
'EbsOptimized': True|False,
'WeightedCapacity': 123.0,
'SpotPrice': 'string'
1404 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
},
],
'AllocationStrategy': 'lowestPrice'|'diversified'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SpotFleetRequestConfig (dict) – [REQUIRED]
The configuration for the Spot fleet request.
– ClientToken (string) –
A unique, case-sensitive identifier you provide to ensure idempotency of
your listings. This helps avoid duplicate listings. For more information,
see Ensuring Idempotency .
– SpotPrice (string) – [REQUIRED]
The bid price per unit hour.
– TargetCapacity (integer) – [REQUIRED]
The number of units to request. You can choose to set the target capacity
in terms of instances or a performance characteristic that is important to
your application workload, such as vCPUs, memory, or I/O.
– ValidFrom (datetime) –
The start date and time of the request, in UTC format (for example, YYYY
-MM -DD T*HH* :MM :SS Z). The default is to start fulfilling the request
immediately.
– ValidUntil (datetime) –
The end date and time of the request, in UTC format (for example, YYYY -
MM -DD T*HH* :MM :SS Z). At this point, no new Spot instance requests
are placed or enabled to fulfill the request.
– TerminateInstancesWithExpiration (boolean) –
Indicates whether running Spot instances should be terminated when the
Spot fleet request expires.
– IamFleetRole (string) – [REQUIRED]
Grants the Spot fleet permission to terminate Spot instances on your
behalf when you cancel its Spot fleet request using CancelSpot-
FleetRequests or when the Spot fleet request expires, if you set
terminateInstancesWithExpiration .
– LaunchSpecifications (list) – [REQUIRED]
Information about the launch specifications for the Spot fleet request.
* (dict) –
Describes the launch specification for one or more Spot instances.
· ImageId (string) –
The ID of the AMI.
· KeyName (string) –
The name of the key pair.
3.1. Services 1405
Boto3 Documentation, Release 1.1.4
· SecurityGroups (list) –
One or more security groups. To request an instance in a non-
default VPC, you must specify the ID of the security group.
To request an instance in EC2-Classic or a default VPC, you
can specify the name or the ID of the security group.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· UserData (string) –
The Base64-encoded MIME user data to make available to
the instances.
· AddressingType (string) –
Deprecated.
· InstanceType (string) –
The instance type.
· Placement (dict) –
The placement information.
· AvailabilityZone (string) –
The Availability Zone.
· GroupName (string) –
The name of the placement group (for cluster instances).
· KernelId (string) –
The ID of the kernel.
· RamdiskId (string) –
The ID of the RAM disk.
· BlockDeviceMappings (list) –
One or more block device mapping entries.
· (dict) –
Describes a block device mapping.
· VirtualName (string) –
The virtual device name (ephemeral N). Instance store vol-
umes are numbered starting from 0. An instance type with
2 available instance store volumes can specify mappings for
ephemeral0 and ephemeral1 .The number of available
instance store volumes depends on the instance type. After
you connect to the instance, you must mount the volume.
Constraints: For M3 instances, you must specify instance
store volumes in the block device mapping for the instance.
When you launch an M3 instance, we ignore any instance
store volumes specified in the block device mapping for the
AMI.
· DeviceName (string) –
1406 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
· NoDevice (string) –
Suppresses the specified device included in the block device
mapping of the AMI.
3.1. Services 1407
Boto3 Documentation, Release 1.1.4
· Monitoring (dict) –
Enable or disable monitoring for the instances.
· Enabled (boolean) –
Enables monitoring for the instance.
Default: false
· SubnetId (string) –
The ID of the subnet in which to launch the instances.
· NetworkInterfaces (list) –
One or more network interfaces.
· (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· DeviceIndex (integer) –
The index of the device on the instance for the network inter-
face attachment. If you are specifying a network interface in
a RunInstances request, you must provide the device index.
· SubnetId (string) –
The ID of the subnet associated with the network string. Ap-
plies only if creating a network interface when launching an
instance.
· Description (string) –
The description of the network interface. Applies only if cre-
ating a network interface when launching an instance.
· PrivateIpAddress (string) –
The private IP address of the network interface. Applies only
if creating a network interface when launching an instance.
· Groups (list) –
The IDs of the security groups for the network interface. Ap-
plies only if creating a network interface when launching an
instance.
· (string) –
· DeleteOnTermination (boolean) –
If set to true , the interface is deleted when the instance
is terminated. You can specify true only if creating a new
network interface when launching an instance.
· PrivateIpAddresses (list) –
One or more private IP addresses to assign to the network
interface. Only one private IP address can be designated as
primary.
· (dict) –
Describes a secondary private IP address for a network inter-
face.
· PrivateIpAddress (string) – [REQUIRED]
The private IP addresses.
1408 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Primary (boolean) –
Indicates whether the private IP address is the primary private
IP address. Only one IP address can be designated as primary.
· SecondaryPrivateIpAddressCount (integer) –
The number of secondary private IP addresses. You can’t
specify this option and specify more than one private IP ad-
dress using the private IP addresses option.
· AssociatePublicIpAddress (boolean) –
Indicates whether to assign a public IP address to an instance
you launch in a VPC. The public IP address can only be as-
signed to a network interface for eth0, and can only be as-
signed to a new network interface, not an existing one. You
cannot specify more than one network interface in the request.
If launching into a default subnet, the default value is true .
· IamInstanceProfile (dict) –
The IAM instance profile.
· Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
· Name (string) –
The name of the instance profile.
· EbsOptimized (boolean) –
Indicates whether the instances are optimized for EBS I/O.
This optimization provides dedicated throughput to Amazon
EBS and an optimized configuration stack to provide optimal
EBS I/O performance. This optimization isn’t available with
all instance types. Additional usage charges apply when using
an EBS Optimized instance.
Default: false
· WeightedCapacity (float) –
The number of units provided by the specified instance type.
These are the same units that you chose to set the target capac-
ity in terms (instances or a performance characteristic such as
vCPUs, memory, or I/O).
If the target capacity divided by this value is not a whole num-
ber, we round the number of instances to the next whole num-
ber. If this value is not specified, the default is 1.
· SpotPrice (string) –
The bid price per unit hour for the specified instance type.
If this value is not specified, the default is the Spot bid
price specified for the fleet. To determine the bid price
per unit hour, divide the Spot bid price by the value of
WeightedCapacity .
– AllocationStrategy (string) –
Determines how to allocate the target capacity across the Spot pools spec-
ified by the Spot fleet request. The default is lowestPrice .
Return type dict
Returns
3.1. Services 1409
Boto3 Documentation, Release 1.1.4
Response Syntax
{
'SpotFleetRequestId': 'string'
}
Response Structure
• (dict) –
Contains the output of RequestSpotFleet.
– SpotFleetRequestId (string) –
The ID of the Spot fleet request.
request_spot_instances(**kwargs)
Creates a Spot instance request. Spot instances are instances that Amazon EC2 launches when the bid
price that you specify exceeds the current Spot price. Amazon EC2 periodically sets the Spot price based
on available Spot Instance capacity and current Spot instance requests. For more information, see Spot
Instance Requests in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.request_spot_instances(
DryRun=True|False,
SpotPrice='string',
ClientToken='string',
InstanceCount=123,
Type='one-time'|'persistent',
ValidFrom=datetime(2015, 1, 1),
ValidUntil=datetime(2015, 1, 1),
LaunchGroup='string',
AvailabilityZoneGroup='string',
LaunchSpecification={
'ImageId': 'string',
'KeyName': 'string',
'SecurityGroups': [
'string',
],
'UserData': 'string',
'AddressingType': 'string',
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.medium'
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string'
},
'KernelId': 'string',
'RamdiskId': 'string',
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
1410 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'NoDevice': 'string'
},
],
'SubnetId': 'string',
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'DeviceIndex': 123,
'SubnetId': 'string',
'Description': 'string',
'PrivateIpAddress': 'string',
'Groups': [
'string',
],
'DeleteOnTermination': True|False,
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
'SecondaryPrivateIpAddressCount': 123,
'AssociatePublicIpAddress': True|False
},
],
'IamInstanceProfile': {
'Arn': 'string',
'Name': 'string'
},
'EbsOptimized': True|False,
'Monitoring': {
'Enabled': True|False
},
'SecurityGroupIds': [
'string',
]
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SpotPrice (string) – [REQUIRED]
The maximum hourly price (bid) for any Spot instance launched to fulfill the
request.
• ClientToken (string) – Unique, case-sensitive identifier that you provide to en-
sure the idempotency of the request. For more information, see How to Ensure
Idempotency in the Amazon Elastic Compute Cloud User Guide .
• InstanceCount (integer) – The maximum number of Spot instances to launch.
Default: 1
• Type (string) – The Spot instance request type.
Default: one-time
• ValidFrom (datetime) – The start date of the request. If this is a one-time re-
3.1. Services 1411
Boto3 Documentation, Release 1.1.4
quest, the request becomes active at this date and time and remains active until
all instances launch, the request expires, or the request is canceled. If the request
is persistent, the request becomes active at this date and time and remains active
until it expires or is canceled.
Default: The request is effective indefinitely.
• ValidUntil (datetime) – The end date of the request. If this is a one-time request,
the request remains active until all instances launch, the request is canceled,
or this date is reached. If the request is persistent, it remains active until it is
canceled or this date and time is reached.
Default: The request is effective indefinitely.
• LaunchGroup (string) – The instance launch group. Launch groups are Spot
instances that launch together and terminate together.
Default: Instances are launched and terminated individually
• AvailabilityZoneGroup (string) – The user-specified name for a logical group-
ing of bids.
When you specify an Availability Zone group in a Spot Instance request, all Spot
instances in the request are launched in the same Availability Zone. Instance
proximity is maintained with this parameter, but the choice of Availability Zone
is not. The group applies only to bids for Spot Instances of the same instance
type. Any additional Spot instance requests that are specified with the same
Availability Zone group name are launched in that same Availability Zone, as
long as at least one instance from the group is still active.
If there is no active instance running in the Availability Zone group that you
specify for a new Spot instance request (all instances are terminated, the bid is
expired, or the bid falls below current market), then Amazon EC2 launches the
instance in any Availability Zone where the constraint can be met. Consequently,
the subsequent set of Spot instances could be placed in a different zone from the
original request, even if you specified the same Availability Zone group.
Default: Instances are launched in any available Availability Zone.
• LaunchSpecification (dict) – Describes the launch specification for an instance.
– ImageId (string) –
The ID of the AMI.
– KeyName (string) –
The name of the key pair.
– SecurityGroups (list) –
* (string) –
– UserData (string) –
The Base64-encoded MIME user data to make available to the instances.
– AddressingType (string) –
Deprecated.
– InstanceType (string) –
The instance type.
– Placement (dict) –
The placement information for the instance.
* AvailabilityZone (string) –
The Availability Zone.
* GroupName (string) –
1412 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The name of the placement group (for cluster instances).
– KernelId (string) –
The ID of the kernel.
– RamdiskId (string) –
The ID of the RAM disk.
– BlockDeviceMappings (list) –
One or more block device mapping entries.
* (dict) –
Describes a block device mapping.
· VirtualName (string) –
The virtual device name (ephemeral N). Instance store vol-
umes are numbered starting from 0. An instance type with
2 available instance store volumes can specify mappings for
ephemeral0 and ephemeral1 .The number of available
instance store volumes depends on the instance type. After
you connect to the instance, you must mount the volume.
Constraints: For M3 instances, you must specify instance
store volumes in the block device mapping for the instance.
When you launch an M3 instance, we ignore any instance
store volumes specified in the block device mapping for the
AMI.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
3.1. Services 1413
Boto3 Documentation, Release 1.1.4
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
· NoDevice (string) –
Suppresses the specified device included in the block device
mapping of the AMI.
– SubnetId (string) –
The ID of the subnet in which to launch the instance.
– NetworkInterfaces (list) –
One or more network interfaces.
* (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· DeviceIndex (integer) –
The index of the device on the instance for the network inter-
face attachment. If you are specifying a network interface in
a RunInstances request, you must provide the device index.
· SubnetId (string) –
The ID of the subnet associated with the network string. Ap-
plies only if creating a network interface when launching an
instance.
· Description (string) –
The description of the network interface. Applies only if cre-
ating a network interface when launching an instance.
· PrivateIpAddress (string) –
The private IP address of the network interface. Applies only
if creating a network interface when launching an instance.
· Groups (list) –
1414 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The IDs of the security groups for the network interface. Ap-
plies only if creating a network interface when launching an
instance.
· (string) –
· DeleteOnTermination (boolean) –
If set to true , the interface is deleted when the instance
is terminated. You can specify true only if creating a new
network interface when launching an instance.
· PrivateIpAddresses (list) –
One or more private IP addresses to assign to the network
interface. Only one private IP address can be designated as
primary.
· (dict) –
Describes a secondary private IP address for a network inter-
face.
· PrivateIpAddress (string) – [REQUIRED]
The private IP addresses.
· Primary (boolean) –
Indicates whether the private IP address is the primary private
IP address. Only one IP address can be designated as primary.
· SecondaryPrivateIpAddressCount (integer) –
The number of secondary private IP addresses. You can’t
specify this option and specify more than one private IP ad-
dress using the private IP addresses option.
· AssociatePublicIpAddress (boolean) –
Indicates whether to assign a public IP address to an instance
you launch in a VPC. The public IP address can only be as-
signed to a network interface for eth0, and can only be as-
signed to a new network interface, not an existing one. You
cannot specify more than one network interface in the request.
If launching into a default subnet, the default value is true .
– IamInstanceProfile (dict) –
The IAM instance profile.
* Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
* Name (string) –
The name of the instance profile.
– EbsOptimized (boolean) –
Indicates whether the instance is optimized for EBS I/O. This optimization
provides dedicated throughput to Amazon EBS and an optimized config-
uration stack to provide optimal EBS I/O performance. This optimization
isn’t available with all instance types. Additional usage charges apply
when using an EBS Optimized instance.
Default: false
– Monitoring (dict) –
Describes the monitoring for the instance.
* Enabled (boolean) – [REQUIRED]
3.1. Services 1415
Boto3 Documentation, Release 1.1.4
Indicates whether monitoring is enabled for the instance.
– SecurityGroupIds (list) –
* (string) –
Return type dict
Returns
Response Syntax
{
'SpotInstanceRequests': [
{
'SpotInstanceRequestId': 'string',
'SpotPrice': 'string',
'Type': 'one-time'|'persistent',
'State': 'open'|'active'|'closed'|'cancelled'|'failed',
'Fault': {
'Code': 'string',
'Message': 'string'
},
'Status': {
'Code': 'string',
'UpdateTime': datetime(2015, 1, 1),
'Message': 'string'
},
'ValidFrom': datetime(2015, 1, 1),
'ValidUntil': datetime(2015, 1, 1),
'LaunchGroup': 'string',
'AvailabilityZoneGroup': 'string',
'LaunchSpecification': {
'ImageId': 'string',
'KeyName': 'string',
'SecurityGroups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'UserData': 'string',
'AddressingType': 'string',
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.x
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string'
},
'KernelId': 'string',
'RamdiskId': 'string',
'BlockDeviceMappings': [
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
1416 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'NoDevice': 'string'
},
],
'SubnetId': 'string',
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'DeviceIndex': 123,
'SubnetId': 'string',
'Description': 'string',
'PrivateIpAddress': 'string',
'Groups': [
'string',
],
'DeleteOnTermination': True|False,
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
'SecondaryPrivateIpAddressCount': 123,
'AssociatePublicIpAddress': True|False
},
],
'IamInstanceProfile': {
'Arn': 'string',
'Name': 'string'
},
'EbsOptimized': True|False,
'Monitoring': {
'Enabled': True|False
}
},
'InstanceId': 'string',
'CreateTime': datetime(2015, 1, 1),
'ProductDescription': 'Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'LaunchedAvailabilityZone': 'string'
},
]
}
Response Structure
• (dict) –
Contains the output of RequestSpotInstances.
– SpotInstanceRequests (list) –
One or more Spot instance requests.
* (dict) –
Describe a Spot instance request.
· SpotInstanceRequestId (string) –
3.1. Services 1417
Boto3 Documentation, Release 1.1.4
The ID of the Spot instance request.
· SpotPrice (string) –
The maximum hourly price (bid) for any Spot instance
launched to fulfill the request.
· Type (string) –
The Spot instance request type.
· State (string) –
The state of the Spot instance request. Spot bid status infor-
mation can help you track your Spot instance requests. For
more information, see Spot Bid Status in the Amazon Elastic
Compute Cloud User Guide .
· Fault (dict) –
The fault codes for the Spot instance request, if any.
· Code (string) –
The reason code for the Spot instance state change.
· Message (string) –
The message for the Spot instance state change.
· Status (dict) –
The status code and status message describing the Spot in-
stance request.
· Code (string) –
The status code.
· UpdateTime (datetime) –
The date and time of the most recent status update, in UTC
format (for example, YYYY -MM -DD T*HH* :MM :SS Z).
· Message (string) –
The description for the status code.
· ValidFrom (datetime) –
The start date of the request, in UTC format (for example,
YYYY -MM -DD T*HH* :MM :SS Z). If this is a one-time
request, the request becomes active at this date and time and
remains active until all instances launch, the request expires,
or the request is canceled. If the request is persistent, the re-
quest becomes active at this date and time and remains active
until it expires or is canceled.
· ValidUntil (datetime) –
The end date of the request, in UTC format (for example,
YYYY -MM -DD T*HH* :MM :SS Z). If this is a one-time
request, the request remains active until all instances launch,
the request is canceled, or this date is reached. If the request
is persistent, it remains active until it is canceled or this date
is reached.
· LaunchGroup (string) –
The instance launch group. Launch groups are Spot instances
that launch together and terminate together.
· AvailabilityZoneGroup (string) –
1418 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The Availability Zone group. If you specify the same Avail-
ability Zone group for all Spot instance requests, all Spot in-
stances are launched in the same Availability Zone.
· LaunchSpecification (dict) –
Additional information for launching instances.
· ImageId (string) –
The ID of the AMI.
· KeyName (string) –
The name of the key pair.
· SecurityGroups (list) –
One or more security groups. To request an instance in a non-
default VPC, you must specify the ID of the security group.
To request an instance in EC2-Classic or a default VPC, you
can specify the name or the ID of the security group.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· UserData (string) –
The Base64-encoded MIME user data to make available to
the instances.
· AddressingType (string) –
Deprecated.
· InstanceType (string) –
The instance type.
· Placement (dict) –
The placement information for the instance.
· AvailabilityZone (string) –
The Availability Zone.
· GroupName (string) –
The name of the placement group (for cluster instances).
· KernelId (string) –
The ID of the kernel.
· RamdiskId (string) –
The ID of the RAM disk.
· BlockDeviceMappings (list) –
One or more block device mapping entries.
· (dict) –
Describes a block device mapping.
· VirtualName (string) –
The virtual device name (ephemeral N). Instance store vol-
umes are numbered starting from 0. An instance type with
2 available instance store volumes can specify mappings for
3.1. Services 1419
Boto3 Documentation, Release 1.1.4
ephemeral0 and ephemeral1 .The number of available
instance store volumes depends on the instance type. After
you connect to the instance, you must mount the volume.
Constraints: For M3 instances, you must specify instance
store volumes in the block device mapping for the instance.
When you launch an M3 instance, we ignore any instance
store volumes specified in the block device mapping for the
AMI.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
1420 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
· NoDevice (string) –
Suppresses the specified device included in the block device
mapping of the AMI.
· SubnetId (string) –
The ID of the subnet in which to launch the instance.
· NetworkInterfaces (list) –
One or more network interfaces.
· (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· DeviceIndex (integer) –
The index of the device on the instance for the network inter-
face attachment. If you are specifying a network interface in
a RunInstances request, you must provide the device index.
· SubnetId (string) –
The ID of the subnet associated with the network string. Ap-
plies only if creating a network interface when launching an
instance.
· Description (string) –
The description of the network interface. Applies only if cre-
ating a network interface when launching an instance.
· PrivateIpAddress (string) –
The private IP address of the network interface. Applies only
if creating a network interface when launching an instance.
· Groups (list) –
The IDs of the security groups for the network interface. Ap-
plies only if creating a network interface when launching an
instance.
· (string) –
· DeleteOnTermination (boolean) –
If set to true , the interface is deleted when the instance
is terminated. You can specify true only if creating a new
network interface when launching an instance.
· PrivateIpAddresses (list) –
One or more private IP addresses to assign to the network
interface. Only one private IP address can be designated as
primary.
· (dict) –
Describes a secondary private IP address for a network inter-
face.
3.1. Services 1421
Boto3 Documentation, Release 1.1.4
· PrivateIpAddress (string) –
The private IP addresses.
· Primary (boolean) –
Indicates whether the private IP address is the primary private
IP address. Only one IP address can be designated as primary.
· SecondaryPrivateIpAddressCount (integer) –
The number of secondary private IP addresses. You can’t
specify this option and specify more than one private IP ad-
dress using the private IP addresses option.
· AssociatePublicIpAddress (boolean) –
Indicates whether to assign a public IP address to an instance
you launch in a VPC. The public IP address can only be as-
signed to a network interface for eth0, and can only be as-
signed to a new network interface, not an existing one. You
cannot specify more than one network interface in the request.
If launching into a default subnet, the default value is true .
· IamInstanceProfile (dict) –
The IAM instance profile.
· Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
· Name (string) –
The name of the instance profile.
· EbsOptimized (boolean) –
Indicates whether the instance is optimized for EBS I/O. This
optimization provides dedicated throughput to Amazon EBS
and an optimized configuration stack to provide optimal EBS
I/O performance. This optimization isn’t available with all
instance types. Additional usage charges apply when using
an EBS Optimized instance.
Default: false
· Monitoring (dict) –
Describes the monitoring for the instance.
· Enabled (boolean) –
Indicates whether monitoring is enabled for the instance.
· InstanceId (string) –
The instance ID, if an instance has been launched to fulfill the
Spot instance request.
· CreateTime (datetime) –
The date and time when the Spot instance request was created,
in UTC format (for example, YYYY -MM -DD T*HH* :MM
:SS Z).
· ProductDescription (string) –
The product description associated with the Spot instance.
· Tags (list) –
Any tags assigned to the resource.
1422 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· LaunchedAvailabilityZone (string) –
The Availability Zone in which the bid is launched.
reset_image_attribute(**kwargs)
Resets an attribute of an AMI to its default value.
Note: The productCodes attribute can’t be reset.
Request Syntax
response = client.reset_image_attribute(
DryRun=True|False,
ImageId='string',
Attribute='launchPermission'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageId (string) – [REQUIRED]
The ID of the AMI.
• Attribute (string) – [REQUIRED]
The attribute to reset (currently you can only reset the launch permission at-
tribute).
Returns None
reset_instance_attribute(**kwargs)
Resets an attribute of an instance to its default value. To reset the kernel or ramdisk , the instance
must be in a stopped state. To reset the SourceDestCheck , the instance can be either running or
stopped.
The SourceDestCheck attribute controls whether source/destination checking is enabled. The default
value is true , which means checking is enabled. This value must be false for a NAT instance to
perform NAT. For more information, see NAT Instances in the Amazon Virtual Private Cloud User Guide
.
Request Syntax
response = client.reset_instance_attribute(
DryRun=True|False,
3.1. Services 1423
Boto3 Documentation, Release 1.1.4
InstanceId='string',
Attribute='instanceType'|'kernel'|'ramdisk'|'userData'|'disableApiTermination'|'instance
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the instance.
• Attribute (string) – [REQUIRED]
The attribute to reset.
Returns None
reset_network_interface_attribute(**kwargs)
Resets a network interface attribute. You can specify only one attribute at a time.
Request Syntax
response = client.reset_network_interface_attribute(
DryRun=True|False,
NetworkInterfaceId='string',
SourceDestCheck='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• NetworkInterfaceId (string) – [REQUIRED]
The ID of the network interface.
• SourceDestCheck (string) – The source/destination checking attribute. Resets
the value to true .
Returns None
reset_snapshot_attribute(**kwargs)
Resets permission settings for the specified snapshot.
For more information on modifying snapshot permissions, see Sharing Snapshots in the Amazon Elastic
Compute Cloud User Guide .
Request Syntax
response = client.reset_snapshot_attribute(
DryRun=True|False,
SnapshotId='string',
Attribute='productCodes'|'createVolumePermission'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
1424 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• SnapshotId (string) – [REQUIRED]
The ID of the snapshot.
• Attribute (string) – [REQUIRED]
The attribute to reset. Currently, only the attribute for permission to create vol-
umes can be reset.
Returns None
restore_address_to_classic(**kwargs)
Restores an Elastic IP address that was previously moved to the EC2-VPC platform back to the EC2-
Classic platform. You cannot move an Elastic IP address that was originally allocated for use in EC2-VPC.
The Elastic IP address must not be associated with an instance or network interface.
Request Syntax
response = client.restore_address_to_classic(
DryRun=True|False,
PublicIp='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• PublicIp (string) – [REQUIRED]
The Elastic IP address.
Return type dict
Returns
Response Syntax
{
'Status': 'MoveInProgress'|'InVpc'|'InClassic',
'PublicIp': 'string'
}
Response Structure
• (dict) –
– Status (string) –
The move status for the IP address.
– PublicIp (string) –
The Elastic IP address.
revoke_security_group_egress(**kwargs)
Removes one or more egress rules from a security group for EC2-VPC. The values that you specify in the
revoke request (for example, ports) must match the existing rule’s values for the rule to be revoked.
Each rule consists of the protocol and the CIDR range or source security group. For the TCP and UDP
protocols, you must also specify the destination port or range of ports. For the ICMP protocol, you must
also specify the ICMP type and code.
Rule changes are propagated to instances within the security group as quickly as possible. However, a
small delay might occur.
Request Syntax
3.1. Services 1425
Boto3 Documentation, Release 1.1.4
response = client.revoke_security_group_egress(
DryRun=True|False,
GroupId='string',
SourceSecurityGroupName='string',
SourceSecurityGroupOwnerId='string',
IpProtocol='string',
FromPort=123,
ToPort=123,
CidrIp='string',
IpPermissions=[
{
'IpProtocol': 'string',
'FromPort': 123,
'ToPort': 123,
'UserIdGroupPairs': [
{
'UserId': 'string',
'GroupName': 'string',
'GroupId': 'string'
},
],
'IpRanges': [
{
'CidrIp': 'string'
},
],
'PrefixListIds': [
{
'PrefixListId': 'string'
},
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupId (string) – [REQUIRED]
The ID of the security group.
• SourceSecurityGroupName (string) – The name of a destination security
group. To revoke outbound access to a destination security group, we recom-
mend that you use a set of IP permissions instead.
• SourceSecurityGroupOwnerId (string) – The AWS account number for a des-
tination security group. To revoke outbound access to a destination security
group, we recommend that you use a set of IP permissions instead.
• IpProtocol (string) – The IP protocol name (tcp , udp , icmp ) or number (see
Protocol Numbers ). Use -1 to specify all.
• FromPort (integer) – The start of port range for the TCP and UDP protocols, or
an ICMP type number. For the ICMP type number, use -1 to specify all ICMP
types.
• ToPort (integer) – The end of port range for the TCP and UDP protocols, or an
ICMP code number. For the ICMP code number, use -1 to specify all ICMP
1426 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
codes for the ICMP type.
• CidrIp (string) – The CIDR IP address range. You can’t specify this parameter
when specifying a source security group.
• IpPermissions (list) – A set of IP permissions. You can’t specify a destination
security group and a CIDR IP address range.
– (dict) –
Describes a security group rule.
* IpProtocol (string) –
The protocol.
When you call DescribeSecurityGroups , the protocol value returned
is the number. Exception: For TCP, UDP, and ICMP, the value re-
turned is the name (for example, tcp , udp , or icmp ). For a list
of protocol numbers, see Protocol Numbers . (VPC only) When you
call AuthorizeSecurityGroupIngress , you can use -1 to specify all.
* FromPort (integer) –
The start of port range for the TCP and UDP protocols, or an ICMP
type number. A value of -1 indicates all ICMP types.
* ToPort (integer) –
The end of port range for the TCP and UDP protocols, or an ICMP
code. A value of -1 indicates all ICMP codes for the specified
ICMP type.
* UserIdGroupPairs (list) –
One or more security group and AWS account ID pairs.
· (dict) –
Describes a security group and AWS account ID pair.
· UserId (string) –
The ID of an AWS account. EC2-Classic only.
· GroupName (string) –
The name of the security group. In a request, use this parame-
ter for a security group in EC2-Classic or a default VPC only.
For a security group in a nondefault VPC, use GroupId .
· GroupId (string) –
The ID of the security group.
* IpRanges (list) –
One or more IP ranges.
· (dict) –
Describes an IP range.
· CidrIp (string) –
The CIDR range. You can either specify a CIDR range or a
source security group, not both.
* PrefixListIds (list) –
(Valid for AuthorizeSecurityGroupEgress , RevokeSecurity-
GroupEgress and DescribeSecurityGroups only) One or more
prefix list IDs for an AWS service. In an AuthorizeSecurity-
GroupEgress request, this is the AWS service that you want to
access through a VPC endpoint from instances associated with the
security group.
3.1. Services 1427
Boto3 Documentation, Release 1.1.4
· (dict) –
The ID of the prefix.
· PrefixListId (string) –
The ID of the prefix.
Returns None
revoke_security_group_ingress(**kwargs)
Removes one or more ingress rules from a security group. The values that you specify in the revoke
request (for example, ports) must match the existing rule’s values for the rule to be removed.
Each rule consists of the protocol and the CIDR range or source security group. For the TCP and UDP
protocols, you must also specify the destination port or range of ports. For the ICMP protocol, you must
also specify the ICMP type and code.
Rule changes are propagated to instances within the security group as quickly as possible. However, a
small delay might occur.
Request Syntax
response = client.revoke_security_group_ingress(
DryRun=True|False,
GroupName='string',
GroupId='string',
SourceSecurityGroupName='string',
SourceSecurityGroupOwnerId='string',
IpProtocol='string',
FromPort=123,
ToPort=123,
CidrIp='string',
IpPermissions=[
{
'IpProtocol': 'string',
'FromPort': 123,
'ToPort': 123,
'UserIdGroupPairs': [
{
'UserId': 'string',
'GroupName': 'string',
'GroupId': 'string'
},
],
'IpRanges': [
{
'CidrIp': 'string'
},
],
'PrefixListIds': [
{
'PrefixListId': 'string'
},
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
1428 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupName (string) – [EC2-Classic, default VPC] The name of the security
group.
• GroupId (string) – The ID of the security group. Required for a security group
in a nondefault VPC.
• SourceSecurityGroupName (string) – [EC2-Classic, default VPC] The name
of the source security group. You can’t specify this parameter in combination
with the following parameters: the CIDR IP address range, the start of the port
range, the IP protocol, and the end of the port range. For EC2-VPC, the source
security group must be in the same VPC.
• SourceSecurityGroupOwnerId (string) – [EC2-Classic, default VPC] The
AWS account ID of the source security group. For EC2-VPC, the source security
group must be in the same VPC. You can’t specify this parameter in combination
with the following parameters: the CIDR IP address range, the IP protocol, the
start of the port range, and the end of the port range. To revoke a specific rule for
an IP protocol and port range, use a set of IP permissions instead.
• IpProtocol (string) – The IP protocol name (tcp , udp , icmp ) or number (see
Protocol Numbers ). Use -1 to specify all.
• FromPort (integer) – The start of port range for the TCP and UDP protocols, or
an ICMP type number. For the ICMP type number, use -1 to specify all ICMP
types.
• ToPort (integer) – The end of port range for the TCP and UDP protocols, or an
ICMP code number. For the ICMP code number, use -1 to specify all ICMP
codes for the ICMP type.
• CidrIp (string) – The CIDR IP address range. You can’t specify this parameter
when specifying a source security group.
• IpPermissions (list) – A set of IP permissions. You can’t specify a source secu-
rity group and a CIDR IP address range.
– (dict) –
Describes a security group rule.
* IpProtocol (string) –
The protocol.
When you call DescribeSecurityGroups , the protocol value returned
is the number. Exception: For TCP, UDP, and ICMP, the value re-
turned is the name (for example, tcp , udp , or icmp ). For a list
of protocol numbers, see Protocol Numbers . (VPC only) When you
call AuthorizeSecurityGroupIngress , you can use -1 to specify all.
* FromPort (integer) –
The start of port range for the TCP and UDP protocols, or an ICMP
type number. A value of -1 indicates all ICMP types.
* ToPort (integer) –
The end of port range for the TCP and UDP protocols, or an ICMP
code. A value of -1 indicates all ICMP codes for the specified
ICMP type.
* UserIdGroupPairs (list) –
One or more security group and AWS account ID pairs.
· (dict) –
Describes a security group and AWS account ID pair.
· UserId (string) –
3.1. Services 1429
Boto3 Documentation, Release 1.1.4
The ID of an AWS account. EC2-Classic only.
· GroupName (string) –
The name of the security group. In a request, use this parame-
ter for a security group in EC2-Classic or a default VPC only.
For a security group in a nondefault VPC, use GroupId .
· GroupId (string) –
The ID of the security group.
* IpRanges (list) –
One or more IP ranges.
· (dict) –
Describes an IP range.
· CidrIp (string) –
The CIDR range. You can either specify a CIDR range or a
source security group, not both.
* PrefixListIds (list) –
(Valid for AuthorizeSecurityGroupEgress , RevokeSecurity-
GroupEgress and DescribeSecurityGroups only) One or more
prefix list IDs for an AWS service. In an AuthorizeSecurity-
GroupEgress request, this is the AWS service that you want to
access through a VPC endpoint from instances associated with the
security group.
· (dict) –
The ID of the prefix.
· PrefixListId (string) –
The ID of the prefix.
Returns None
run_instances(**kwargs)
Launches the specified number of instances using an AMI for which you have permissions.
When you launch an instance, it enters the pending state. After the instance is ready for you, it enters
the running state. To check the state of your instance, call DescribeInstances .
If you don’t specify a security group when launching an instance, Amazon EC2 uses the default security
group. For more information, see Security Groups in the Amazon Elastic Compute Cloud User Guide .
[EC2-VPC only accounts] If you don’t specify a subnet in the request, we choose a default subnet from
your default VPC for you.
[EC2-Classic accounts] If you’re launching into EC2-Classic and you don’t specify an Availability Zone,
we choose one for you.
Linux instances have access to the public key of the key pair at boot. You can use this key to provide
secure access to the instance. Amazon EC2 public images use this feature to provide secure access
without passwords. For more information, see Key Pairs in the Amazon Elastic Compute Cloud User
Guide .
You can provide optional user data when launching an instance. For more information, see Instance
Metadata in the Amazon Elastic Compute Cloud User Guide .
If any of the AMIs have a product code attached for which the user has not subscribed, RunInstances
fails.
1430 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
T2 instance types can only be launched into a VPC. If you do not have a default VPC, or if you do not
specify a subnet ID in the request, RunInstances fails.
For more information about troubleshooting, see What To Do If An Instance Immediately Terminates ,
and Troubleshooting Connecting to Your Instance in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.run_instances(
DryRun=True|False,
ImageId='string',
MinCount=123,
MaxCount=123,
KeyName='string',
SecurityGroups=[
'string',
],
SecurityGroupIds=[
'string',
],
UserData='string',
InstanceType='t1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.medium'|'m3.la
Placement={
'AvailabilityZone': 'string',
'GroupName': 'string',
'Tenancy': 'default'|'dedicated'
},
KernelId='string',
RamdiskId='string',
BlockDeviceMappings=[
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
},
],
Monitoring={
'Enabled': True|False
},
SubnetId='string',
DisableApiTermination=True|False,
InstanceInitiatedShutdownBehavior='stop'|'terminate',
PrivateIpAddress='string',
ClientToken='string',
AdditionalInfo='string',
NetworkInterfaces=[
{
'NetworkInterfaceId': 'string',
'DeviceIndex': 123,
'SubnetId': 'string',
'Description': 'string',
3.1. Services 1431
Boto3 Documentation, Release 1.1.4
'PrivateIpAddress': 'string',
'Groups': [
'string',
],
'DeleteOnTermination': True|False,
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
'SecondaryPrivateIpAddressCount': 123,
'AssociatePublicIpAddress': True|False
},
],
IamInstanceProfile={
'Arn': 'string',
'Name': 'string'
},
EbsOptimized=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageId (string) – [REQUIRED]
The ID of the AMI, which you can get by calling DescribeImages .
• MinCount (integer) – [REQUIRED]
The minimum number of instances to launch. If you specify a minimum that
is more instances than Amazon EC2 can launch in the target Availability Zone,
Amazon EC2 launches no instances.
Constraints: Between 1 and the maximum number you’re allowed for the spec-
ified instance type. For more information about the default limits, and how to
request an increase, see How many instances can I run in Amazon EC2 in the
Amazon EC2 General FAQ.
• MaxCount (integer) – [REQUIRED]
The maximum number of instances to launch. If you specify more instances than
Amazon EC2 can launch in the target Availability Zone, Amazon EC2 launches
the largest possible number of instances above MinCount .
Constraints: Between 1 and the maximum number you’re allowed for the spec-
ified instance type. For more information about the default limits, and how to
request an increase, see How many instances can I run in Amazon EC2 in the
Amazon EC2 General FAQ.
• KeyName (string) – The name of the key pair. You can create a key pair using
CreateKeyPair or ImportKeyPair .
Warning: If you do not specify a key pair, you can’t connect to the instance
unless you choose an AMI that is configured to allow users another way to
log in.
1432 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• SecurityGroups (list) – [EC2-Classic, default VPC] One or more security group
names. For a nondefault VPC, you must use security group IDs instead.
Default: Amazon EC2 uses the default security group.
– (string) –
• SecurityGroupIds (list) – One or more security group IDs. You can create a
security group using CreateSecurityGroup .
Default: Amazon EC2 uses the default security group.
– (string) –
• UserData (string) – The Base64-encoded MIME user data for the instances.
This value will be base64 encoded automatically. Do not base64
encode this value prior to performing the operation.
• InstanceType (string) – The instance type. For more information, see Instance
Types in the Amazon Elastic Compute Cloud User Guide .
Default: m1.small
• Placement (dict) – The placement for the instance.
– AvailabilityZone (string) –
The Availability Zone of the instance.
– GroupName (string) –
The name of the placement group the instance is in (for cluster compute
instances).
– Tenancy (string) –
The tenancy of the instance (if the instance is running in a VPC). An in-
stance with a tenancy of dedicated runs on single-tenant hardware.
• KernelId (string) – The ID of the kernel.
Warning: We recommend that you use PV-GRUB instead of kernels and
RAM disks. For more information, see PV-GRUB in the Amazon Elastic
Compute Cloud User Guide .
• RamdiskId (string) – The ID of the RAM disk.
Warning: We recommend that you use PV-GRUB instead of kernels and
RAM disks. For more information, see PV-GRUB in the Amazon Elastic
Compute Cloud User Guide .
• BlockDeviceMappings (list) – The block device mapping.
– (dict) –
Describes a block device mapping.
* VirtualName (string) –
The virtual device name (ephemeral N). Instance store volumes
are numbered starting from 0. An instance type with 2 available in-
stance store volumes can specify mappings for ephemeral0 and
ephemeral1 .The number of available instance store volumes de-
pends on the instance type. After you connect to the instance, you
must mount the volume.
Constraints: For M3 instances, you must specify instance store vol-
umes in the block device mapping for the instance. When you
launch an M3 instance, we ignore any instance store volumes spec-
ified in the block device mapping for the AMI.
3.1. Services 1433
Boto3 Documentation, Release 1.1.4
* DeviceName (string) –
The device name exposed to the instance (for example, /dev/sdh
or xvdh ).
* Ebs (dict) –
Parameters used to automatically set up EBS volumes when the in-
stance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
* NoDevice (string) –
Suppresses the specified device included in the block device map-
ping of the AMI.
1434 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• Monitoring (dict) – The monitoring for the instance.
– Enabled (boolean) – [REQUIRED]
Indicates whether monitoring is enabled for the instance.
• SubnetId (string) – [EC2-VPC] The ID of the subnet to launch the instance into.
• DisableApiTermination (boolean) – If you set this parameter to true
, you can’t terminate the instance using the Amazon EC2 console,
CLI, or API; otherwise, you can. If you set this parameter to
true and then later want to be able to terminate the instance, you
must first change the value of the disableApiTermination attribute
to false using ModifyInstanceAttribute . Alternatively, if you set
InstanceInitiatedShutdownBehavior to terminate , you can ter-
minate the instance by running the shutdown command from the instance.
Default: false
• InstanceInitiatedShutdownBehavior (string) – Indicates whether an instance
stops or terminates when you initiate shutdown from the instance (using the op-
erating system command for system shutdown).
Default: stop
• PrivateIpAddress (string) – [EC2-VPC] The primary IP address. You must
specify a value from the IP address range of the subnet.
Only one private IP address can be designated as primary. Therefore, you
can’t specify this parameter if PrivateIpAddresses.n.Primary is set
to true and PrivateIpAddresses.n.PrivateIpAddress is set to an
IP address.
Default: We select an IP address from the IP address range of the subnet.
• ClientToken (string) – Unique, case-sensitive identifier you provide to ensure
the idempotency of the request. For more information, see Ensuring Idempo-
tency .
Constraints: Maximum 64 ASCII characters
• AdditionalInfo (string) – Reserved.
• NetworkInterfaces (list) – One or more network interfaces.
– (dict) –
Describes a network interface.
* NetworkInterfaceId (string) –
The ID of the network interface.
* DeviceIndex (integer) –
The index of the device on the instance for the network interface
attachment. If you are specifying a network interface in a RunIn-
stances request, you must provide the device index.
* SubnetId (string) –
The ID of the subnet associated with the network string. Applies
only if creating a network interface when launching an instance.
* Description (string) –
The description of the network interface. Applies only if creating a
network interface when launching an instance.
* PrivateIpAddress (string) –
The private IP address of the network interface. Applies only if
creating a network interface when launching an instance.
3.1. Services 1435
Boto3 Documentation, Release 1.1.4
* Groups (list) –
The IDs of the security groups for the network interface. Applies
only if creating a network interface when launching an instance.
· (string) –
* DeleteOnTermination (boolean) –
If set to true , the interface is deleted when the instance is ter-
minated. You can specify true only if creating a new network
interface when launching an instance.
* PrivateIpAddresses (list) –
One or more private IP addresses to assign to the network interface.
Only one private IP address can be designated as primary.
· (dict) –
Describes a secondary private IP address for a network inter-
face.
· PrivateIpAddress (string) – [REQUIRED]
The private IP addresses.
· Primary (boolean) –
Indicates whether the private IP address is the primary private
IP address. Only one IP address can be designated as primary.
* SecondaryPrivateIpAddressCount (integer) –
The number of secondary private IP addresses. You can’t specify
this option and specify more than one private IP address using the
private IP addresses option.
* AssociatePublicIpAddress (boolean) –
Indicates whether to assign a public IP address to an instance you
launch in a VPC. The public IP address can only be assigned to
a network interface for eth0, and can only be assigned to a new
network interface, not an existing one. You cannot specify more
than one network interface in the request. If launching into a default
subnet, the default value is true .
• IamInstanceProfile (dict) – The IAM instance profile.
– Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
– Name (string) –
The name of the instance profile.
• EbsOptimized (boolean) – Indicates whether the instance is optimized for EBS
I/O. This optimization provides dedicated throughput to Amazon EBS and an
optimized configuration stack to provide optimal EBS I/O performance. This
optimization isn’t available with all instance types. Additional usage charges
apply when using an EBS-optimized instance.
Default: false
Return type dict
Returns
Response Syntax
{
'ReservationId': 'string',
'OwnerId': 'string',
1436 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'RequesterId': 'string',
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'Instances': [
{
'InstanceId': 'string',
'ImageId': 'string',
'State': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
},
'PrivateDnsName': 'string',
'PublicDnsName': 'string',
'StateTransitionReason': 'string',
'KeyName': 'string',
'AmiLaunchIndex': 123,
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
],
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarg
'LaunchTime': datetime(2015, 1, 1),
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string',
'Tenancy': 'default'|'dedicated'
},
'KernelId': 'string',
'RamdiskId': 'string',
'Platform': 'Windows',
'Monitoring': {
'State': 'disabled'|'disabling'|'enabled'|'pending'
},
'SubnetId': 'string',
'VpcId': 'string',
'PrivateIpAddress': 'string',
'PublicIpAddress': 'string',
'StateReason': {
'Code': 'string',
'Message': 'string'
},
'Architecture': 'i386'|'x86_64',
'RootDeviceType': 'ebs'|'instance-store',
'RootDeviceName': 'string',
'BlockDeviceMappings': [
{
'DeviceName': 'string',
'Ebs': {
'VolumeId': 'string',
'Status': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
3.1. Services 1437
Boto3 Documentation, Release 1.1.4
}
},
],
'VirtualizationType': 'hvm'|'paravirtual',
'InstanceLifecycle': 'spot',
'SpotInstanceRequestId': 'string',
'ClientToken': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'SecurityGroups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'SourceDestCheck': True|False,
'Hypervisor': 'ovm'|'xen',
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'SubnetId': 'string',
'VpcId': 'string',
'Description': 'string',
'OwnerId': 'string',
'Status': 'available'|'attaching'|'in-use'|'detaching',
'MacAddress': 'string',
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'SourceDestCheck': True|False,
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'Attachment': {
'AttachmentId': 'string',
'DeviceIndex': 123,
'Status': 'attaching'|'attached'|'detaching'|'detached',
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
},
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string'
},
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'Primary': True|False,
'Association': {
'PublicIp': 'string',
1438 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'PublicDnsName': 'string',
'IpOwnerId': 'string'
}
},
]
},
],
'IamInstanceProfile': {
'Arn': 'string',
'Id': 'string'
},
'EbsOptimized': True|False,
'SriovNetSupport': 'string'
},
]
}
Response Structure
• (dict) –
One or more reservations.
– ReservationId (string) –
The ID of the reservation.
– OwnerId (string) –
The ID of the AWS account that owns the reservation.
– RequesterId (string) –
The ID of the requester that launched the instances on your behalf (for
example, AWS Management Console or Auto Scaling).
– Groups (list) –
One or more security groups.
* (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
– Instances (list) –
One or more instances.
* (dict) –
Describes an instance.
· InstanceId (string) –
The ID of the instance.
· ImageId (string) –
The ID of the AMI used to launch the instance.
· State (dict) –
The current state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
3.1. Services 1439
Boto3 Documentation, Release 1.1.4
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
· PrivateDnsName (string) –
The private DNS name assigned to the instance. This DNS
name can only be used inside the Amazon EC2 network. This
name is not available until the instance enters the running
state.
· PublicDnsName (string) –
The public DNS name assigned to the instance. This name is
not available until the instance enters the running state.
· StateTransitionReason (string) –
The reason for the most recent state transition. This might be
an empty string.
· KeyName (string) –
The name of the key pair, if this instance was launched with
an associated key pair.
· AmiLaunchIndex (integer) –
The AMI launch index, which can be used to find this instance
in the launch group.
· ProductCodes (list) –
The product codes attached to this instance.
· (dict) –
Describes a product code.
· ProductCodeId (string) –
The product code.
· ProductCodeType (string) –
The type of product code.
· InstanceType (string) –
The instance type.
· LaunchTime (datetime) –
The time the instance was launched.
· Placement (dict) –
The location where the instance launched.
· AvailabilityZone (string) –
The Availability Zone of the instance.
· GroupName (string) –
The name of the placement group the instance is in (for cluster
compute instances).
· Tenancy (string) –
1440 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The tenancy of the instance (if the instance is running in a
VPC). An instance with a tenancy of dedicated runs on
single-tenant hardware.
· KernelId (string) –
The kernel associated with this instance.
· RamdiskId (string) –
The RAM disk associated with this instance.
· Platform (string) –
The value is Windows for Windows instances; otherwise
blank.
· Monitoring (dict) –
The monitoring information for the instance.
· State (string) –
Indicates whether monitoring is enabled for the instance.
· SubnetId (string) –
The ID of the subnet in which the instance is running.
· VpcId (string) –
The ID of the VPC in which the instance is running.
· PrivateIpAddress (string) –
The private IP address assigned to the instance.
· PublicIpAddress (string) –
The public IP address assigned to the instance.
· StateReason (dict) –
The reason for the most recent state transition.
· Code (string) –
The reason code for the state change.
· Message (string) –
The message for the state change.
· Server.SpotInstanceTermination : A Spot In-
stance was terminated due to an increase in the market price.
· Server.InternalError : An internal error occurred
during instance launch, resulting in termination.
· Server.InsufficientInstanceCapacity : There
was insufficient instance capacity to satisfy the launch re-
quest.
· Client.InternalError : A client error caused the in-
stance to terminate on launch.
· Client.InstanceInitiatedShutdown : The in-
stance was shut down using the shutdown -h command
from the instance.
· Client.UserInitiatedShutdown : The instance was
shut down using the Amazon EC2 API.
· Client.VolumeLimitExceeded : The volume limit
was exceeded.
· Client.InvalidSnapshot.NotFound : The speci-
fied snapshot was not found.
· Architecture (string) –
3.1. Services 1441
Boto3 Documentation, Release 1.1.4
The architecture of the image.
· RootDeviceType (string) –
The root device type used by the AMI. The AMI can use an
EBS volume or an instance store volume.
· RootDeviceName (string) –
The root device name (for example, /dev/sda1 or
/dev/xvda ).
· BlockDeviceMappings (list) –
Any block device mapping entries for the instance.
· (dict) –
Describes a block device mapping.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· VolumeId (string) –
The ID of the EBS volume.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the volume is deleted on instance termina-
tion.
· VirtualizationType (string) –
The virtualization type of the instance.
· InstanceLifecycle (string) –
Indicates whether this is a Spot Instance.
· SpotInstanceRequestId (string) –
The ID of the Spot Instance request.
· ClientToken (string) –
The idempotency token you provided when you launched the
instance.
· Tags (list) –
Any tags assigned to the instance.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
1442 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· SecurityGroups (list) –
One or more security groups for the instance.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· SourceDestCheck (boolean) –
Specifies whether to enable an instance launched in a VPC
to perform NAT. This controls whether source/destination
checking is enabled on the instance. A value of true means
checking is enabled, and false means checking is disabled.
The value must be false for the instance to perform NAT.
For more information, see NAT Instances in the Amazon Vir-
tual Private Cloud User Guide .
· Hypervisor (string) –
The hypervisor type of the instance.
· NetworkInterfaces (list) –
[EC2-VPC] One or more network interfaces for the instance.
· (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· SubnetId (string) –
The ID of the subnet.
· VpcId (string) –
The ID of the VPC.
· Description (string) –
The description.
· OwnerId (string) –
The ID of the AWS account that created the network interface.
· Status (string) –
The status of the network interface.
· MacAddress (string) –
The MAC address.
· PrivateIpAddress (string) –
The IP address of the network interface within the subnet.
· PrivateDnsName (string) –
The private DNS name.
3.1. Services 1443
Boto3 Documentation, Release 1.1.4
· SourceDestCheck (boolean) –
Indicates whether to validate network traffic to or from this
network interface.
· Groups (list) –
One or more security groups.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· Attachment (dict) –
The network interface attachment.
· AttachmentId (string) –
The ID of the network interface attachment.
· DeviceIndex (integer) –
The index of the device on the instance for the network inter-
face attachment.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the network interface is deleted when the
instance is terminated.
· Association (dict) –
The association information for an Elastic IP associated with
the network interface.
· PublicIp (string) –
The public IP address or Elastic IP address bound to the net-
work interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the owner of the Elastic IP address.
· PrivateIpAddresses (list) –
The private IP addresses associated with the network inter-
face.
· (dict) –
Describes a private IP address.
· PrivateIpAddress (string) –
The private IP address of the network interface.
· PrivateDnsName (string) –
The private DNS name.
1444 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Primary (boolean) –
Indicates whether this IP address is the primary private IP ad-
dress of the network interface.
· Association (dict) –
The association information for an Elastic IP address for the
network interface.
· PublicIp (string) –
The public IP address or Elastic IP address bound to the net-
work interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the owner of the Elastic IP address.
· IamInstanceProfile (dict) –
The IAM instance profile associated with the instance.
· Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
· Id (string) –
The ID of the instance profile.
· EbsOptimized (boolean) –
Indicates whether the instance is optimized for EBS I/O. This
optimization provides dedicated throughput to Amazon EBS
and an optimized configuration stack to provide optimal I/O
performance. This optimization isn’t available with all in-
stance types. Additional usage charges apply when using an
EBS Optimized instance.
· SriovNetSupport (string) –
Specifies whether enhanced networking is enabled.
start_instances(**kwargs)
Starts an Amazon EBS-backed AMI that you’ve previously stopped.
Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started. When
an instance is stopped, the compute resources are released and you are not billed for hourly instance
usage. However, your root partition Amazon EBS volume remains, continues to persist your data, and
you are charged for Amazon EBS volume usage. You can restart your instance at any time. Each time
you transition an instance from stopped to started, Amazon EC2 charges a full instance hour, even if
transitions happen multiple times within a single hour.
Before stopping an instance, make sure it is in a state from which it can be restarted. Stopping an instance
does not preserve data stored in RAM.
Performing this operation on an instance that uses an instance store as its root device returns an error.
For more information, see Stopping Instances in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.start_instances(
InstanceIds=[
'string',
],
3.1. Services 1445
Boto3 Documentation, Release 1.1.4
AdditionalInfo='string',
DryRun=True|False
)
Parameters
• InstanceIds (list) – [REQUIRED]
One or more instance IDs.
– (string) –
• AdditionalInfo (string) – Reserved.
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
Return type dict
Returns
Response Syntax
{
'StartingInstances': [
{
'InstanceId': 'string',
'CurrentState': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
},
'PreviousState': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
}
},
]
}
Response Structure
• (dict) –
– StartingInstances (list) –
Information about one or more started instances.
* (dict) –
Describes an instance state change.
· InstanceId (string) –
The ID of the instance.
· CurrentState (dict) –
The current state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
1446 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Name (string) –
The current state of the instance.
· PreviousState (dict) –
The previous state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
stop_instances(**kwargs)
Stops an Amazon EBS-backed instance. Each time you transition an instance from stopped to started,
Amazon EC2 charges a full instance hour, even if transitions happen multiple times within a single hour.
You can’t start or stop Spot Instances.
Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started. When
an instance is stopped, the compute resources are released and you are not billed for hourly instance usage.
However, your root partition Amazon EBS volume remains, continues to persist your data, and you are
charged for Amazon EBS volume usage. You can restart your instance at any time.
Before stopping an instance, make sure it is in a state from which it can be restarted. Stopping an instance
does not preserve data stored in RAM.
Performing this operation on an instance that uses an instance store as its root device returns an error.
You can stop, start, and terminate EBS-backed instances. You can only terminate instance store-backed
instances. What happens to an instance differs if you stop it or terminate it. For example, when you stop
an instance, the root device and any other devices attached to the instance persist. When you terminate
an instance, the root device and any other devices attached during the instance launch are automatically
deleted. For more information about the differences between stopping and terminating instances, see
Instance Lifecycle in the Amazon Elastic Compute Cloud User Guide .
For more information about troubleshooting, see Troubleshooting Stopping Your Instance in the Amazon
Elastic Compute Cloud User Guide .
Request Syntax
response = client.stop_instances(
DryRun=True|False,
InstanceIds=[
'string',
],
Force=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
3.1. Services 1447
Boto3 Documentation, Release 1.1.4
• InstanceIds (list) – [REQUIRED]
One or more instance IDs.
– (string) –
• Force (boolean) – Forces the instances to stop. The instances do not have an
opportunity to flush file system caches or file system metadata. If you use this
option, you must perform file system check and repair procedures. This option
is not recommended for Windows instances.
Default: false
Return type dict
Returns
Response Syntax
{
'StoppingInstances': [
{
'InstanceId': 'string',
'CurrentState': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
},
'PreviousState': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
}
},
]
}
Response Structure
• (dict) –
– StoppingInstances (list) –
Information about one or more stopped instances.
* (dict) –
Describes an instance state change.
· InstanceId (string) –
The ID of the instance.
· CurrentState (dict) –
The current state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
· PreviousState (dict) –
1448 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The previous state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
terminate_instances(**kwargs)
Shuts down one or more instances. This operation is idempotent; if you terminate an instance more than
once, each call succeeds.
Terminated instances remain visible after termination (for approximately one hour).
By default, Amazon EC2 deletes all EBS volumes that were attached when the instance launched. Vol-
umes attached after instance launch continue running.
You can stop, start, and terminate EBS-backed instances. You can only terminate instance store-backed
instances. What happens to an instance differs if you stop it or terminate it. For example, when you stop
an instance, the root device and any other devices attached to the instance persist. When you terminate an
instance, any attached EBS volumes with the DeleteOnTermination block device mapping param-
eter set to true are automatically deleted. For more information about the differences between stopping
and terminating instances, see Instance Lifecycle in the Amazon Elastic Compute Cloud User Guide .
For more information about troubleshooting, see Troubleshooting Terminating Your Instance in the Ama-
zon Elastic Compute Cloud User Guide .
Request Syntax
response = client.terminate_instances(
DryRun=True|False,
InstanceIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – [REQUIRED]
One or more instance IDs.
– (string) –
Return type dict
Returns
Response Syntax
{
'TerminatingInstances': [
3.1. Services 1449
Boto3 Documentation, Release 1.1.4
{
'InstanceId': 'string',
'CurrentState': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
},
'PreviousState': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
}
},
]
}
Response Structure
• (dict) –
– TerminatingInstances (list) –
Information about one or more terminated instances.
* (dict) –
Describes an instance state change.
· InstanceId (string) –
The ID of the instance.
· CurrentState (dict) –
The current state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
· PreviousState (dict) –
The previous state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
unassign_private_ip_addresses(**kwargs)
Unassigns one or more secondary private IP addresses from a network interface.
1450 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response = client.unassign_private_ip_addresses(
NetworkInterfaceId='string',
PrivateIpAddresses=[
'string',
]
)
Parameters
• NetworkInterfaceId (string) – [REQUIRED]
The ID of the network interface.
• PrivateIpAddresses (list) – [REQUIRED]
The secondary private IP addresses to unassign from the network interface. You
can specify this option multiple times to unassign more than one IP address.
– (string) –
Returns None
unmonitor_instances(**kwargs)
Disables monitoring for a running instance. For more information about monitoring instances, see Moni-
toring Your Instances and Volumes in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
response = client.unmonitor_instances(
DryRun=True|False,
InstanceIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – [REQUIRED]
One or more instance IDs.
– (string) –
Return type dict
Returns
Response Syntax
{
'InstanceMonitorings': [
{
'InstanceId': 'string',
'Monitoring': {
'State': 'disabled'|'disabling'|'enabled'|'pending'
}
},
]
}
Response Structure
3.1. Services 1451
Boto3 Documentation, Release 1.1.4
• (dict) –
– InstanceMonitorings (list) –
Monitoring information for one or more instances.
* (dict) –
Describes the monitoring information of the instance.
· InstanceId (string) –
The ID of the instance.
· Monitoring (dict) –
The monitoring information.
· State (string) –
Indicates whether monitoring is enabled for the instance.
Paginators
The available paginators are:
• EC2.Paginator.DescribeInstanceStatus
• EC2.Paginator.DescribeInstances
• EC2.Paginator.DescribeReservedInstancesModifications
• EC2.Paginator.DescribeReservedInstancesOfferings
• EC2.Paginator.DescribeSnapshots
• EC2.Paginator.DescribeSpotPriceHistory
• EC2.Paginator.DescribeTags
• EC2.Paginator.DescribeVolumeStatus
class EC2.Paginator.DescribeInstanceStatus
paginator = client.get_paginator('describe_instance_status')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
EC2.Client.describe_instance_status().
Request Syntax
response_iterator = paginator.paginate(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
1452 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
IncludeAllInstances=True|False,
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
Constraints: Maximum 100 explicitly specified instance IDs.
– (string) –
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone of the instance.
– event.code - The code for the scheduled event
(instance-reboot | system-reboot | system-maintenance
| instance-retirement | instance-stop ).
– event.description - A description of the event.
– event.not-after - The latest end time for the scheduled event (for
example, 2014-09-15T17:15:20.000Z ).
– event.not-before - The earliest start time for the scheduled event
(for example, 2014-09-15T17:15:20.000Z ).
– instance-state-code - The code for the instance state, as a 16-bit
unsigned integer. The high byte is an opaque internal value and should
be ignored. The low byte is set based on the state represented. The valid
values are 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-status.reachability - Filters on instance sta-
tus where the name is reachability (passed | failed |
initializing | insufficient-data ).
– instance-status.status - The status of the instance (ok
| impaired | initializing | insufficient-data |
not-applicable ).
– system-status.reachability - Filters on system status where
the name is reachability (passed | failed | initializing
| insufficient-data ).
– system-status.status - The system status of the instance
(ok | impaired | initializing | insufficient-data |
not-applicable ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
3.1. Services 1453
Boto3 Documentation, Release 1.1.4
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• IncludeAllInstances (boolean) – When true , includes the health status for all
instances. When false , includes the health status for running instances only.
Default: false
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'InstanceStatuses': [
{
'InstanceId': 'string',
'AvailabilityZone': 'string',
'Events': [
{
'Code': 'instance-reboot'|'system-reboot'|'system-maintenance'
'Description': 'string',
'NotBefore': datetime(2015, 1, 1),
'NotAfter': datetime(2015, 1, 1)
},
],
'InstanceState': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'stopping
},
'SystemStatus': {
'Status': 'ok'|'impaired'|'insufficient-data'|'not-applicable'|'in
'Details': [
{
'Name': 'reachability',
'Status': 'passed'|'failed'|'insufficient-data'|'initializ
'ImpairedSince': datetime(2015, 1, 1)
},
]
},
'InstanceStatus': {
'Status': 'ok'|'impaired'|'insufficient-data'|'not-applicable'|'in
'Details': [
{
1454 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Name': 'reachability',
'Status': 'passed'|'failed'|'insufficient-data'|'initializ
'ImpairedSince': datetime(2015, 1, 1)
},
]
}
},
],
Response Structure
• (dict) –
– InstanceStatuses (list) –
One or more instance status descriptions.
* (dict) –
Describes the status of an instance.
· InstanceId (string) –
The ID of the instance.
· AvailabilityZone (string) –
The Availability Zone of the instance.
· Events (list) –
Any scheduled events associated with the instance.
· (dict) –
Describes a scheduled event for an instance.
· Code (string) –
The event code.
· Description (string) –
A description of the event.
After a scheduled event is completed, it can still be described
for up to a week. If the event has been completed, this de-
scription starts with the following text: [Completed].
· NotBefore (datetime) –
The earliest scheduled start time for the event.
· NotAfter (datetime) –
The latest scheduled end time for the event.
· InstanceState (dict) –
The intended state of the instance. DescribeInstanceStatus
requires that an instance be in the running state.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
3.1. Services 1455
Boto3 Documentation, Release 1.1.4
· Name (string) –
The current state of the instance.
· SystemStatus (dict) –
Reports impaired functionality that stems from issues related
to the systems that support an instance, such as hardware fail-
ures and network connectivity problems.
· Status (string) –
The status.
· Details (list) –
The system instance health or application instance health.
· (dict) –
Describes the instance status.
· Name (string) –
The type of instance status.
· Status (string) –
The status.
· ImpairedSince (datetime) –
The time when a status check failed. For an instance that was
launched and impaired, this is the time when the instance was
launched.
· InstanceStatus (dict) –
Reports impaired functionality that stems from issues internal
to the instance, such as impaired reachability.
· Status (string) –
The status.
· Details (list) –
The system instance health or application instance health.
· (dict) –
Describes the instance status.
· Name (string) –
The type of instance status.
· Status (string) –
The status.
· ImpairedSince (datetime) –
The time when a status check failed. For an instance that was
launched and impaired, this is the time when the instance was
launched.
class EC2.Paginator.DescribeInstances
paginator = client.get_paginator('describe_instances')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
EC2.Client.describe_instances().
1456 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
response_iterator = paginator.paginate(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
– (string) –
• Filters (list) – One or more filters.
– architecture - The instance architecture (i386 | x86_64 ).
– availability-zone - The Availability Zone of the instance.
– block-device-mapping.attach-time - The attach time
for an EBS volume mapped to the instance, for example,
2010-09-15T17:15:20.000Z .
– block-device-mapping.delete-on-termination - A
Boolean that indicates whether the EBS volume is deleted on instance
termination.
– block-device-mapping.device-name - The device name for the
EBS volume (for example, /dev/sdh or xvdh ).
– block-device-mapping.status - The status for the EBS volume
(attaching | attached | detaching | detached ).
– block-device-mapping.volume-id - The volume ID of the EBS
volume.
– client-token - The idempotency token you provided when you
launched the instance.
– dns-name - The public DNS name of the instance.
– group-id - The ID of the security group for the instance. EC2-Classic
only.
– group-name - The name of the security group for the instance. EC2-
Classic only.
– hypervisor - The hypervisor type of the instance (ovm | xen ).
– iam-instance-profile.arn - The instance profile associated with
the instance. Specified as an ARN.
3.1. Services 1457
Boto3 Documentation, Release 1.1.4
– image-id - The ID of the image used to launch the instance.
– instance-id - The ID of the instance.
– instance-lifecycle - Indicates whether this is a Spot Instance
(spot ).
– instance-state-code - The state of the instance, as a 16-bit un-
signed integer. The high byte is an opaque internal value and should be
ignored. The low byte is set based on the state represented. The valid val-
ues are: 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-type - The type of instance (for example, t2.micro ).
– instance.group-id - The ID of the security group for the instance.
– instance.group-name - The name of the security group for the in-
stance.
– ip-address - The public IP address of the instance.
– kernel-id - The kernel ID.
– key-name - The name of the key pair used when the instance was
launched.
– launch-index - When launching multiple instances, this is the index
for the instance in the launch group (for example, 0, 1, 2, and so on).
– launch-time - The time when the instance was launched.
– monitoring-state - Indicates whether monitoring is enabled for the
instance (disabled | enabled ).
– owner-id - The AWS account ID of the instance owner.
– placement-group-name - The name of the placement group for the
instance.
– platform - The platform. Use windows if you have Windows in-
stances; otherwise, leave blank.
– private-dns-name - The private DNS name of the instance.
– private-ip-address - The private IP address of the instance.
– product-code - The product code associated with the AMI used to
launch the instance.
– product-code.type - The type of product code (devpay |
marketplace ).
– ramdisk-id - The RAM disk ID.
– reason - The reason for the current state of the instance (for example,
shows “User Initiated [date]” when you stop or terminate the instance).
Similar to the state-reason-code filter.
– requester-id - The ID of the entity that launched the instance on
your behalf (for example, AWS Management Console, Auto Scaling, and
so on).
– reservation-id - The ID of the instance’s reservation. A reservation
ID is created any time you launch an instance. A reservation ID has a
one-to-one relationship with an instance launch request, but can be asso-
ciated with more than one instance if you launch multiple instances using
the same launch request. For example, if you launch one instance, you’ll
get one reservation ID. If you launch ten instances using the same launch
request, you’ll also get one reservation ID.
– root-device-name - The name of the root device for the instance (for
example, /dev/sda1 or /dev/xvda ).
– root-device-type - The type of root device that the instance uses
(ebs | instance-store ).
1458 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– source-dest-check - Indicates whether the instance performs
source/destination checking. A value of true means that checking is
enabled, and false means checking is disabled. The value must be
false for the instance to perform network address translation (NAT) in
your VPC.
– spot-instance-request-id - The ID of the Spot Instance request.
– state-reason-code - The reason code for the state change.
– state-reason-message - A message that describes the state change.
– subnet-id - The ID of the subnet for the instance.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource, where tag :key is the tag’s key.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– tenancy - The tenancy of an instance (dedicated | default ).
– virtualization-type - The virtualization type of the instance
(paravirtual | hvm ).
– vpc-id - The ID of the VPC that the instance is running in.
– network-interface.description - The description of the net-
work interface.
– network-interface.subnet-id - The ID of the subnet for the net-
work interface.
– network-interface.vpc-id - The ID of the VPC for the network
interface.
– network-interface.network-interface.id - The ID of the
network interface.
– network-interface.owner-id - The ID of the owner of the net-
work interface.
– network-interface.availability-zone - The Availability
Zone for the network interface.
– network-interface.requester-id - The requester ID for the
network interface.
– network-interface.requester-managed - Indicates whether
the network interface is being managed by AWS.
– network-interface.status - The status of the network interface
(available ) | in-use ).
– network-interface.mac-address - The MAC address of the net-
work interface.
– network-interface-private-dns-name - The private DNS
name of the network interface.
– network-interface.source-dest-check - Whether the net-
work interface performs source/destination checking. A value of true
means checking is enabled, and false means checking is disabled. The
value must be false for the network interface to perform network ad-
dress translation (NAT) in your VPC.
– network-interface.group-id - The ID of a security group asso-
ciated with the network interface.
– network-interface.group-name - The name of a security group
associated with the network interface.
3.1. Services 1459
Boto3 Documentation, Release 1.1.4
– network-interface.attachment.attachment-id - The ID
of the interface attachment.
– network-interface.attachment.instance-id - The ID of
the instance to which the network interface is attached.
– network-interface.attachment.instance-owner-id -
The owner ID of the instance to which the network interface is attached.
– network-interface.addresses.private-ip-address -
The private IP address associated with the network interface.
– network-interface.attachment.device-index - The de-
vice index to which the network interface is attached.
– network-interface.attachment.status - The status of the at-
tachment (attaching | attached | detaching | detached ).
– network-interface.attachment.attach-time - The time
that the network interface was attached to an instance.
– network-interface.attachment.delete-on-termination
- Specifies whether the attachment is deleted when an instance is termi-
nated.
– network-interface.addresses.primary - Specifies whether
the IP address of the network interface is the primary private IP address.
– network-interface.addresses.association.public-ip
- The ID of the association of an Elastic IP address with a network
interface.
– network-interface.addresses.association.ip-owner-id
- The owner ID of the private IP address associated with the network
interface.
– association.public-ip - The address of the Elastic IP address
bound to the network interface.
– association.ip-owner-id - The owner of the Elastic IP address
associated with the network interface.
– association.allocation-id - The allocation ID returned when
you allocated the Elastic IP address for your network interface.
– association.association-id - The association ID returned
when the network interface was associated with an IP address.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
1460 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'Reservations': [
{
'ReservationId': 'string',
'OwnerId': 'string',
'RequesterId': 'string',
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'Instances': [
{
'InstanceId': 'string',
'ImageId': 'string',
'State': {
'Code': 123,
'Name': 'pending'|'running'|'shutting-down'|'terminated'|'
},
'PrivateDnsName': 'string',
'PublicDnsName': 'string',
'StateTransitionReason': 'string',
'KeyName': 'string',
'AmiLaunchIndex': 123,
'ProductCodes': [
{
'ProductCodeId': 'string',
'ProductCodeType': 'devpay'|'marketplace'
},
],
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'
'LaunchTime': datetime(2015, 1, 1),
'Placement': {
'AvailabilityZone': 'string',
'GroupName': 'string',
'Tenancy': 'default'|'dedicated'
},
'KernelId': 'string',
'RamdiskId': 'string',
'Platform': 'Windows',
'Monitoring': {
'State': 'disabled'|'disabling'|'enabled'|'pending'
},
'SubnetId': 'string',
'VpcId': 'string',
'PrivateIpAddress': 'string',
'PublicIpAddress': 'string',
'StateReason': {
'Code': 'string',
'Message': 'string'
3.1. Services 1461
Boto3 Documentation, Release 1.1.4
},
'Architecture': 'i386'|'x86_64',
'RootDeviceType': 'ebs'|'instance-store',
'RootDeviceName': 'string',
'BlockDeviceMappings': [
{
'DeviceName': 'string',
'Ebs': {
'VolumeId': 'string',
'Status': 'attaching'|'attached'|'detaching'|'deta
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
}
},
],
'VirtualizationType': 'hvm'|'paravirtual',
'InstanceLifecycle': 'spot',
'SpotInstanceRequestId': 'string',
'ClientToken': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'SecurityGroups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'SourceDestCheck': True|False,
'Hypervisor': 'ovm'|'xen',
'NetworkInterfaces': [
{
'NetworkInterfaceId': 'string',
'SubnetId': 'string',
'VpcId': 'string',
'Description': 'string',
'OwnerId': 'string',
'Status': 'available'|'attaching'|'in-use'|'detaching'
'MacAddress': 'string',
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'SourceDestCheck': True|False,
'Groups': [
{
'GroupName': 'string',
'GroupId': 'string'
},
],
'Attachment': {
'AttachmentId': 'string',
'DeviceIndex': 123,
'Status': 'attaching'|'attached'|'detaching'|'deta
'AttachTime': datetime(2015, 1, 1),
'DeleteOnTermination': True|False
},
1462 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string'
},
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'PrivateDnsName': 'string',
'Primary': True|False,
'Association': {
'PublicIp': 'string',
'PublicDnsName': 'string',
'IpOwnerId': 'string'
}
},
]
},
],
'IamInstanceProfile': {
'Arn': 'string',
'Id': 'string'
},
'EbsOptimized': True|False,
'SriovNetSupport': 'string'
},
]
},
],
Response Structure
• (dict) –
– Reservations (list) –
One or more reservations.
* (dict) –
Describes a reservation.
· ReservationId (string) –
The ID of the reservation.
· OwnerId (string) –
The ID of the AWS account that owns the reservation.
· RequesterId (string) –
The ID of the requester that launched the instances on your
behalf (for example, AWS Management Console or Auto
Scaling).
· Groups (list) –
One or more security groups.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
3.1. Services 1463
Boto3 Documentation, Release 1.1.4
· GroupId (string) –
The ID of the security group.
· Instances (list) –
One or more instances.
· (dict) –
Describes an instance.
· InstanceId (string) –
The ID of the instance.
· ImageId (string) –
The ID of the AMI used to launch the instance.
· State (dict) –
The current state of the instance.
· Code (integer) –
The low byte represents the state. The high byte is an opaque
internal value and should be ignored.
· 0 : pending
· 16 : running
· 32 : shutting-down
· 48 : terminated
· 64 : stopping
· 80 : stopped
· Name (string) –
The current state of the instance.
· PrivateDnsName (string) –
The private DNS name assigned to the instance. This DNS
name can only be used inside the Amazon EC2 network. This
name is not available until the instance enters the running
state.
· PublicDnsName (string) –
The public DNS name assigned to the instance. This name is
not available until the instance enters the running state.
· StateTransitionReason (string) –
The reason for the most recent state transition. This might be
an empty string.
· KeyName (string) –
The name of the key pair, if this instance was launched with
an associated key pair.
· AmiLaunchIndex (integer) –
The AMI launch index, which can be used to find this instance
in the launch group.
· ProductCodes (list) –
The product codes attached to this instance.
· (dict) –
Describes a product code.
· ProductCodeId (string) –
The product code.
1464 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· ProductCodeType (string) –
The type of product code.
· InstanceType (string) –
The instance type.
· LaunchTime (datetime) –
The time the instance was launched.
· Placement (dict) –
The location where the instance launched.
· AvailabilityZone (string) –
The Availability Zone of the instance.
· GroupName (string) –
The name of the placement group the instance is in (for cluster
compute instances).
· Tenancy (string) –
The tenancy of the instance (if the instance is running in a
VPC). An instance with a tenancy of dedicated runs on
single-tenant hardware.
· KernelId (string) –
The kernel associated with this instance.
· RamdiskId (string) –
The RAM disk associated with this instance.
· Platform (string) –
The value is Windows for Windows instances; otherwise
blank.
· Monitoring (dict) –
The monitoring information for the instance.
· State (string) –
Indicates whether monitoring is enabled for the instance.
· SubnetId (string) –
The ID of the subnet in which the instance is running.
· VpcId (string) –
The ID of the VPC in which the instance is running.
· PrivateIpAddress (string) –
The private IP address assigned to the instance.
· PublicIpAddress (string) –
The public IP address assigned to the instance.
· StateReason (dict) –
The reason for the most recent state transition.
· Code (string) –
The reason code for the state change.
· Message (string) –
The message for the state change.
· Server.SpotInstanceTermination : A Spot In-
stance was terminated due to an increase in the market price.
3.1. Services 1465
Boto3 Documentation, Release 1.1.4
· Server.InternalError : An internal error occurred
during instance launch, resulting in termination.
· Server.InsufficientInstanceCapacity : There
was insufficient instance capacity to satisfy the launch re-
quest.
· Client.InternalError : A client error caused the in-
stance to terminate on launch.
· Client.InstanceInitiatedShutdown : The in-
stance was shut down using the shutdown -h command
from the instance.
· Client.UserInitiatedShutdown : The instance was
shut down using the Amazon EC2 API.
· Client.VolumeLimitExceeded : The volume limit
was exceeded.
· Client.InvalidSnapshot.NotFound : The speci-
fied snapshot was not found.
· Architecture (string) –
The architecture of the image.
· RootDeviceType (string) –
The root device type used by the AMI. The AMI can use an
EBS volume or an instance store volume.
· RootDeviceName (string) –
The root device name (for example, /dev/sda1 or
/dev/xvda ).
· BlockDeviceMappings (list) –
Any block device mapping entries for the instance.
· (dict) –
Describes a block device mapping.
· DeviceName (string) –
The device name exposed to the instance (for example,
/dev/sdh or xvdh ).
· Ebs (dict) –
Parameters used to automatically set up EBS volumes when
the instance is launched.
· VolumeId (string) –
The ID of the EBS volume.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the volume is deleted on instance termina-
tion.
· VirtualizationType (string) –
The virtualization type of the instance.
· InstanceLifecycle (string) –
Indicates whether this is a Spot Instance.
1466 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· SpotInstanceRequestId (string) –
The ID of the Spot Instance request.
· ClientToken (string) –
The idempotency token you provided when you launched the
instance.
· Tags (list) –
Any tags assigned to the instance.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· SecurityGroups (list) –
One or more security groups for the instance.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· SourceDestCheck (boolean) –
Specifies whether to enable an instance launched in a VPC
to perform NAT. This controls whether source/destination
checking is enabled on the instance. A value of true means
checking is enabled, and false means checking is disabled.
The value must be false for the instance to perform NAT.
For more information, see NAT Instances in the Amazon Vir-
tual Private Cloud User Guide .
· Hypervisor (string) –
The hypervisor type of the instance.
· NetworkInterfaces (list) –
[EC2-VPC] One or more network interfaces for the instance.
· (dict) –
Describes a network interface.
· NetworkInterfaceId (string) –
The ID of the network interface.
· SubnetId (string) –
The ID of the subnet.
3.1. Services 1467
Boto3 Documentation, Release 1.1.4
· VpcId (string) –
The ID of the VPC.
· Description (string) –
The description.
· OwnerId (string) –
The ID of the AWS account that created the network interface.
· Status (string) –
The status of the network interface.
· MacAddress (string) –
The MAC address.
· PrivateIpAddress (string) –
The IP address of the network interface within the subnet.
· PrivateDnsName (string) –
The private DNS name.
· SourceDestCheck (boolean) –
Indicates whether to validate network traffic to or from this
network interface.
· Groups (list) –
One or more security groups.
· (dict) –
Describes a security group.
· GroupName (string) –
The name of the security group.
· GroupId (string) –
The ID of the security group.
· Attachment (dict) –
The network interface attachment.
· AttachmentId (string) –
The ID of the network interface attachment.
· DeviceIndex (integer) –
The index of the device on the instance for the network inter-
face attachment.
· Status (string) –
The attachment state.
· AttachTime (datetime) –
The time stamp when the attachment initiated.
· DeleteOnTermination (boolean) –
Indicates whether the network interface is deleted when the
instance is terminated.
· Association (dict) –
The association information for an Elastic IP associated with
the network interface.
· PublicIp (string) –
1468 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
The public IP address or Elastic IP address bound to the net-
work interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the owner of the Elastic IP address.
· PrivateIpAddresses (list) –
The private IP addresses associated with the network inter-
face.
· (dict) –
Describes a private IP address.
· PrivateIpAddress (string) –
The private IP address of the network interface.
· PrivateDnsName (string) –
The private DNS name.
· Primary (boolean) –
Indicates whether this IP address is the primary private IP ad-
dress of the network interface.
· Association (dict) –
The association information for an Elastic IP address for the
network interface.
· PublicIp (string) –
The public IP address or Elastic IP address bound to the net-
work interface.
· PublicDnsName (string) –
The public DNS name.
· IpOwnerId (string) –
The ID of the owner of the Elastic IP address.
· IamInstanceProfile (dict) –
The IAM instance profile associated with the instance.
· Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
· Id (string) –
The ID of the instance profile.
· EbsOptimized (boolean) –
Indicates whether the instance is optimized for EBS I/O. This
optimization provides dedicated throughput to Amazon EBS
and an optimized configuration stack to provide optimal I/O
performance. This optimization isn’t available with all in-
stance types. Additional usage charges apply when using an
EBS Optimized instance.
· SriovNetSupport (string) –
Specifies whether enhanced networking is enabled.
class EC2.Paginator.DescribeReservedInstancesModifications
3.1. Services 1469
Boto3 Documentation, Release 1.1.4
paginator = client.get_paginator('describe_reserved_instances_modifications')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
EC2.Client.describe_reserved_instances_modifications().
Request Syntax
response_iterator = paginator.paginate(
ReservedInstancesModificationIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• ReservedInstancesModificationIds (list) – IDs for the submitted modification
request.
– (string) –
• Filters (list) – One or more filters.
– client-token - The idempotency token for the modification request.
– create-date - The time when the modification request was created.
– effective-date - The time when the modification becomes effective.
– modification-result.reserved-instances-id - The ID for
the Reserved Instances created as part of the modification request. This ID
is only available when the status of the modification is fulfilled .
– modification-result.target-configuration.availability-zone
- The Availability Zone for the new Reserved Instances.
– modification-result.target-configuration.instance-count
- The number of new Reserved Instances.
– modification-result.target-configuration.instance-type
- The instance type of the new Reserved Instances.
– modification-result.target-configuration.platform
- The network platform of the new Reserved Instances (EC2-Classic |
EC2-VPC ).
– reserved-instances-id - The ID of the Reserved Instances modi-
fied.
– reserved-instances-modification-id - The ID of the modi-
fication request.
– status - The status of the Reserved Instances modification request
(processing | fulfilled | failed ).
– status-message - The reason for the status.
1470 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– update-date - The time when the modification request was last up-
dated.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'ReservedInstancesModifications': [
{
'ReservedInstancesModificationId': 'string',
'ReservedInstancesIds': [
{
'ReservedInstancesId': 'string'
},
],
'ModificationResults': [
{
'ReservedInstancesId': 'string',
'TargetConfiguration': {
'AvailabilityZone': 'string',
'Platform': 'string',
'InstanceCount': 123,
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.larg
}
},
],
'CreateDate': datetime(2015, 1, 1),
'UpdateDate': datetime(2015, 1, 1),
'EffectiveDate': datetime(2015, 1, 1),
'Status': 'string',
'StatusMessage': 'string',
'ClientToken': 'string'
3.1. Services 1471
Boto3 Documentation, Release 1.1.4
},
],
Response Structure
• (dict) –
– ReservedInstancesModifications (list) –
The Reserved Instance modification information.
* (dict) –
Describes a Reserved Instance modification.
· ReservedInstancesModificationId (string) –
A unique ID for the Reserved Instance modification.
· ReservedInstancesIds (list) –
The IDs of one or more Reserved Instances.
· (dict) –
Describes the ID of a Reserved Instance.
· ReservedInstancesId (string) –
The ID of the Reserved Instance.
· ModificationResults (list) –
Contains target configurations along with their corresponding
new Reserved Instance IDs.
· (dict) –
· ReservedInstancesId (string) –
The ID for the Reserved Instances that were created as part of
the modification request. This field is only available when the
modification is fulfilled.
· TargetConfiguration (dict) –
The target Reserved Instances configurations supplied as part
of the modification request.
· AvailabilityZone (string) –
The Availability Zone for the modified Reserved Instances.
· Platform (string) –
The network platform of the modified Reserved Instances,
which is either EC2-Classic or EC2-VPC.
· InstanceCount (integer) –
The number of modified Reserved Instances.
· InstanceType (string) –
The instance type for the modified Reserved Instances.
· CreateDate (datetime) –
The time when the modification request was created.
· UpdateDate (datetime) –
The time when the modification request was last updated.
· EffectiveDate (datetime) –
The time for the modification to become effective.
1472 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Status (string) –
The status of the Reserved Instances modification request.
· StatusMessage (string) –
The reason for the status.
· ClientToken (string) –
A unique, case-sensitive key supplied by the client to ensure
that the request is idempotent. For more information, see En-
suring Idempotency .
class EC2.Paginator.DescribeReservedInstancesOfferings
paginator = client.get_paginator('describe_reserved_instances_offerings')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
EC2.Client.describe_reserved_instances_offerings().
Request Syntax
response_iterator = paginator.paginate(
DryRun=True|False,
ReservedInstancesOfferingIds=[
'string',
],
InstanceType='t1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.medium'|'m3.la
AvailabilityZone='string',
ProductDescription='Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'|'Windows (Amazon VPC
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
InstanceTenancy='default'|'dedicated',
OfferingType='Heavy Utilization'|'Medium Utilization'|'Light Utilization'|'No Upfront'|'
IncludeMarketplace=True|False,
MinDuration=123,
MaxDuration=123,
MaxInstanceCount=123,
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ReservedInstancesOfferingIds (list) – One or more Reserved Instances offer-
ing IDs.
3.1. Services 1473
Boto3 Documentation, Release 1.1.4
– (string) –
• InstanceType (string) – The instance type on which the Reserved Instance can
be used. For more information, see Instance Types in the Amazon Elastic Com-
pute Cloud User Guide .
• AvailabilityZone (string) – The Availability Zone in which the Reserved In-
stance can be used.
• ProductDescription (string) – The Reserved Instance product platform descrip-
tion. Instances that include (Amazon VPC) in the description are for use with
Amazon VPC.
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone where the Reserved In-
stance can be used.
– duration - The duration of the Reserved Instance (for example, one
year or three years), in seconds (31536000 | 94608000 ).
– fixed-price - The purchase price of the Reserved Instance (for exam-
ple, 9800.0).
– instance-type - The instance type on which the Reserved Instance
can be used.
– marketplace - Set to true to show only Reserved Instance Market-
place offerings. When this filter is not used, which is the default behavior,
all offerings from AWS and Reserved Instance Marketplace are listed.
– product-description - The Reserved Instance product platform
description. Instances that include (Amazon VPC) in the product plat-
form description will only be displayed to EC2-Classic account holders
and are for use with Amazon VPC. (Linux/UNIX | Linux/UNIX
(Amazon VPC) | SUSE Linux | SUSE Linux (Amazon VPC) |
Red Hat Enterprise Linux | Red Hat Enterprise Linux
(Amazon VPC) | Windows | Windows (Amazon VPC) | Windows
with SQL Server Standard | Windows with SQL Server
Standard (Amazon VPC) | Windows with SQL Server
Web | Windows with SQL Server Web (Amazon VPC) |
Windows with SQL Server Enterprise | Windows with
SQL Server Enterprise (Amazon VPC) )
– reserved-instances-offering-id - The Reserved Instances of-
fering ID.
– usage-price - The usage price of the Reserved Instance, per hour (for
example, 0.84).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• InstanceTenancy (string) – The tenancy of the Reserved Instance offering. A
Reserved Instance with dedicated tenancy runs on single-tenant hardware
and can only be launched within a VPC.
Default: default
• OfferingType (string) – The Reserved Instance offering type. If you are us-
1474 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
ing tools that predate the 2011-11-01 API version, you only have access to the
Medium Utilization Reserved Instance offering type.
• IncludeMarketplace (boolean) – Include Marketplace offerings in the response.
• MinDuration (integer) – The minimum duration (in seconds) to filter when
searching for offerings.
Default: 2592000 (1 month)
• MaxDuration (integer) – The maximum duration (in seconds) to filter when
searching for offerings.
Default: 94608000 (3 years)
• MaxInstanceCount (integer) – The maximum number of instances to filter
when searching for offerings.
Default: 20
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'ReservedInstancesOfferings': [
{
'ReservedInstancesOfferingId': 'string',
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarg
'AvailabilityZone': 'string',
'Duration': 123,
'UsagePrice': ...,
'FixedPrice': ...,
'ProductDescription': 'Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'
'InstanceTenancy': 'default'|'dedicated',
'CurrencyCode': 'USD',
'OfferingType': 'Heavy Utilization'|'Medium Utilization'|'Light Utiliz
'RecurringCharges': [
{
'Frequency': 'Hourly',
'Amount': 123.0
},
],
'Marketplace': True|False,
'PricingDetails': [
{
'Price': 123.0,
'Count': 123
},
3.1. Services 1475
Boto3 Documentation, Release 1.1.4
]
},
],
Response Structure
• (dict) –
– ReservedInstancesOfferings (list) –
A list of Reserved Instances offerings.
* (dict) –
Describes a Reserved Instance offering.
· ReservedInstancesOfferingId (string) –
The ID of the Reserved Instance offering.
· InstanceType (string) –
The instance type on which the Reserved Instance can be
used.
· AvailabilityZone (string) –
The Availability Zone in which the Reserved Instance can be
used.
· Duration (integer) –
The duration of the Reserved Instance, in seconds.
· UsagePrice (float) –
The usage price of the Reserved Instance, per hour.
· FixedPrice (float) –
The purchase price of the Reserved Instance.
· ProductDescription (string) –
The Reserved Instance product platform description.
· InstanceTenancy (string) –
The tenancy of the reserved instance.
· CurrencyCode (string) –
The currency of the Reserved Instance offering you are pur-
chasing. It’s specified using ISO 4217 standard currency
codes. At this time, the only supported currency is USD .
· OfferingType (string) –
The Reserved Instance offering type.
· RecurringCharges (list) –
The recurring charge tag assigned to the resource.
· (dict) –
Describes a recurring charge.
· Frequency (string) –
The frequency of the recurring charge.
· Amount (float) –
The amount of the recurring charge.
1476 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Marketplace (boolean) –
Indicates whether the offering is available through the Re-
served Instance Marketplace (resale) or AWS. If it’s a Re-
served Instance Marketplace offering, this is true .
· PricingDetails (list) –
The pricing details of the Reserved Instance offering.
· (dict) –
Describes a Reserved Instance offering.
· Price (float) –
The price per instance.
· Count (integer) –
The number of instances available for the price.
class EC2.Paginator.DescribeSnapshots
paginator = client.get_paginator('describe_snapshots')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
EC2.Client.describe_snapshots().
Request Syntax
response_iterator = paginator.paginate(
DryRun=True|False,
SnapshotIds=[
'string',
],
OwnerIds=[
'string',
],
RestorableByUserIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
3.1. Services 1477
Boto3 Documentation, Release 1.1.4
• SnapshotIds (list) – One or more snapshot IDs.
Default: Describes snapshots for which you have launch permissions.
– (string) –
• OwnerIds (list) – Returns the snapshots owned by the specified owner. Multiple
owners can be specified.
– (string) –
• RestorableByUserIds (list) – One or more AWS accounts IDs that can create
volumes from the snapshot.
– (string) –
• Filters (list) – One or more filters.
– description - A description of the snapshot.
– owner-alias - The AWS account alias (for example, amazon ) that
owns the snapshot.
– owner-id - The ID of the AWS account that owns the snapshot.
– progress - The progress of the snapshot, as a percentage (for example,
80%).
– snapshot-id - The snapshot ID.
– start-time - The time stamp when the snapshot was initiated.
– status - The status of the snapshot (pending | completed | error
).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– volume-id - The ID of the volume the snapshot is for.
– volume-size - The size of the volume, in GiB.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
1478 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'Snapshots': [
{
'SnapshotId': 'string',
'VolumeId': 'string',
'State': 'pending'|'completed'|'error',
'StateMessage': 'string',
'StartTime': datetime(2015, 1, 1),
'Progress': 'string',
'OwnerId': 'string',
'Description': 'string',
'VolumeSize': 123,
'OwnerAlias': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'Encrypted': True|False,
'KmsKeyId': 'string',
'DataEncryptionKeyId': 'string'
},
],
Response Structure
• (dict) –
– Snapshots (list) –
Information about the snapshots.
* (dict) –
Describes a snapshot.
· SnapshotId (string) –
The ID of the snapshot. Each snapshot receives a unique iden-
tifier when it is created.
· VolumeId (string) –
The ID of the volume that was used to create the snapshot.
· State (string) –
The snapshot state.
· StateMessage (string) –
Encrypted Amazon EBS snapshots are copied asyn-
chronously. If a snapshot copy operation fails (for example, if
the proper AWS Key Management Service (AWS KMS) per-
missions are not obtained) this field displays error state details
to help you diagnose why the error occurred. This parameter
is only returned by the DescribeSnapshots API operation.
3.1. Services 1479
Boto3 Documentation, Release 1.1.4
· StartTime (datetime) –
The time stamp when the snapshot was initiated.
· Progress (string) –
The progress of the snapshot, as a percentage.
· OwnerId (string) –
The AWS account ID of the EBS snapshot owner.
· Description (string) –
The description for the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
· OwnerAlias (string) –
The AWS account alias (for example, amazon , self ) or
AWS account ID that owns the snapshot.
· Tags (list) –
Any tags assigned to the snapshot.
· (dict) –
Describes a tag.
· Key (string) –
The key of the tag.
Constraints: Tag keys are case-sensitive and accept a maxi-
mum of 127 Unicode characters. May not begin with aws:
· Value (string) –
The value of the tag.
Constraints: Tag values are case-sensitive and accept a maxi-
mum of 255 Unicode characters.
· Encrypted (boolean) –
Indicates whether the snapshot is encrypted.
· KmsKeyId (string) –
The full ARN of the AWS Key Management Service (AWS
KMS) customer master key (CMK) that was used to protect
the volume encryption key for the parent volume.
· DataEncryptionKeyId (string) –
The data encryption key identifier for the snapshot. This value
is a unique identifier that corresponds to the data encryption
key that was used to encrypt the original volume or snapshot
copy. Because data encryption keys are inherited by volumes
created from snapshots, and vice versa, if snapshots share the
same data encryption key identifier, then they belong to the
same volume/snapshot lineage. This parameter is only re-
turned by the DescribeSnapshots API operation.
class EC2.Paginator.DescribeSpotPriceHistory
paginator = client.get_paginator('describe_spot_price_history')
1480 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
paginate(**kwargs)
Creates an iterator that will paginate through responses from
EC2.Client.describe_spot_price_history().
Request Syntax
response_iterator = paginator.paginate(
DryRun=True|False,
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
InstanceTypes=[
't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.medium'|'m3.large'|'m3.
],
ProductDescriptions=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
AvailabilityZone='string',
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• StartTime (datetime) – The date and time, up to the past 90 days, from which to
start retrieving the price history data, in UTC format (for example, YYYY -MM
-DD T*HH* :MM :SS Z).
• EndTime (datetime) – The date and time, up to the current date, from which to
stop retrieving the price history data, in UTC format (for example, YYYY -MM
-DD T*HH* :MM :SS Z).
• InstanceTypes (list) – Filters the results by the specified instance types.
– (string) –
• ProductDescriptions (list) – Filters the results by the specified basic product
descriptions.
– (string) –
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone for which prices should
be returned.
– instance-type - The type of instance (for example, m1.small ).
– product-description - The product description for the Spot price
(Linux/UNIX | SUSE Linux | Windows | Linux/UNIX (Amazon
VPC) | SUSE Linux (Amazon VPC) | Windows (Amazon VPC)
).
3.1. Services 1481
Boto3 Documentation, Release 1.1.4
– spot-price - The Spot price. The value must match exactly (or use
wildcards; greater than or less than comparison is not supported).
– timestamp - The timestamp of the Spot price history, in UTC format
(for example, YYYY -MM -DD T*HH* :MM :SS Z). You can use wildcards
(* and ?). Greater than or less than comparison is not supported.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• AvailabilityZone (string) – Filters the results by the specified Availability Zone.
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'SpotPriceHistory': [
{
'InstanceType': 't1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarg
'ProductDescription': 'Linux/UNIX'|'Linux/UNIX (Amazon VPC)'|'Windows'
'SpotPrice': 'string',
'Timestamp': datetime(2015, 1, 1),
'AvailabilityZone': 'string'
},
],
Response Structure
• (dict) –
Contains the output of DescribeSpotPriceHistory.
– SpotPriceHistory (list) –
The historical Spot prices.
* (dict) –
1482 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Describes the maximum hourly price (bid) for any Spot instance
launched to fulfill the request.
· InstanceType (string) –
The instance type.
· ProductDescription (string) –
A general description of the AMI.
· SpotPrice (string) –
The maximum price (bid) that you are willing to pay for a
Spot instance.
· Timestamp (datetime) –
The date and time the request was created, in UTC format (for
example, YYYY -MM -DD T*HH* :MM :SS Z).
· AvailabilityZone (string) –
The Availability Zone.
class EC2.Paginator.DescribeTags
paginator = client.get_paginator('describe_tags')
paginate(**kwargs)
Creates an iterator that will paginate through responses from EC2.Client.describe_tags().
Request Syntax
response_iterator = paginator.paginate(
DryRun=True|False,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Filters (list) – One or more filters.
– key - The tag key.
– resource-id - The resource ID.
– resource-type - The resource type (customer-gateway |
dhcp-options | image | instance | internet-gateway |
network-acl | network-interface | reserved-instances
| route-table | security-group | snapshot |
3.1. Services 1483
Boto3 Documentation, Release 1.1.4
spot-instances-request | subnet | volume | vpc |
vpn-connection | vpn-gateway ).
– value - The tag value.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'Tags': [
{
'ResourceId': 'string',
'ResourceType': 'customer-gateway'|'dhcp-options'|'image'|'instance'|'
'Key': 'string',
'Value': 'string'
},
],
Response Structure
• (dict) –
– Tags (list) –
A list of tags.
* (dict) –
Describes a tag.
· ResourceId (string) –
The ID of the resource. For example, ami-1a2b3c4d .
· ResourceType (string) –
The resource type.
1484 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
· Key (string) –
The tag key.
· Value (string) –
The tag value.
class EC2.Paginator.DescribeVolumeStatus
paginator = client.get_paginator('describe_volume_status')
paginate(**kwargs)
Creates an iterator that will paginate through responses from
EC2.Client.describe_volume_status().
Request Syntax
response_iterator = paginator.paginate(
DryRun=True|False,
VolumeIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeIds (list) – One or more volume IDs.
Default: Describes all your volumes.
– (string) –
• Filters (list) – One or more filters.
– action.code - The action code for the event (for example,
enable-volume-io ).
– action.description - A description of the action.
– action.event-id - The event ID associated with the action.
– availability-zone - The Availability Zone of the instance.
– event.description - A description of the event.
– event.event-id - The event ID.
– event.event-type - The event type (for io-enabled : passed |
failed ; for io-performance : io-performance:degraded
3.1. Services 1485
Boto3 Documentation, Release 1.1.4
| io-performance:severely-degraded |
io-performance:stalled ).
– event.not-after - The latest end time for the event.
– event.not-before - The earliest start time for the event.
– volume-status.details-name - The cause for
volume-status.status (io-enabled | io-performance
).
– volume-status.details-status - The status of
volume-status.details-name (for io-enabled : passed
| failed ; for io-performance : normal | degraded |
severely-degraded | stalled ).
– volume-status.status - The status of the volume (ok | impaired
| warning | insufficient-data ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• PaginationConfig (dict) – A dictionary that provides parameters to control pag-
ination.
– MaxItems (integer) –
The total number of items to return. If the total number of items available
is more than the value specified in max-items then a NextToken will be
provided in the output that you can use to resume pagination.
– PageSize (integer) –
The size of each page.
– StartingToken (string) –
A token to specify where to start paginating. This is the NextToken
from a previous response.
Return type dict
Returns
Response Syntax
{
'VolumeStatuses': [
{
'VolumeId': 'string',
'AvailabilityZone': 'string',
'VolumeStatus': {
'Status': 'ok'|'impaired'|'insufficient-data',
'Details': [
{
'Name': 'io-enabled'|'io-performance',
'Status': 'string'
},
]
},
1486 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'Events': [
{
'EventType': 'string',
'Description': 'string',
'NotBefore': datetime(2015, 1, 1),
'NotAfter': datetime(2015, 1, 1),
'EventId': 'string'
},
],
'Actions': [
{
'Code': 'string',
'Description': 'string',
'EventType': 'string',
'EventId': 'string'
},
]
},
],
Response Structure
• (dict) –
– VolumeStatuses (list) –
A list of volumes.
* (dict) –
Describes the volume status.
· VolumeId (string) –
The volume ID.
· AvailabilityZone (string) –
The Availability Zone of the volume.
· VolumeStatus (dict) –
The volume status.
· Status (string) –
The status of the volume.
· Details (list) –
The details of the volume status.
· (dict) –
Describes a volume status.
· Name (string) –
The name of the volume status.
· Status (string) –
The intended status of the volume status.
· Events (list) –
A list of events associated with the volume.
· (dict) –
Describes a volume status event.
· EventType (string) –
3.1. Services 1487
Boto3 Documentation, Release 1.1.4
The type of this event.
· Description (string) –
A description of the event.
· NotBefore (datetime) –
The earliest start time of the event.
· NotAfter (datetime) –
The latest end time of the event.
· EventId (string) –
The ID of this event.
· Actions (list) –
The details of the operation.
· (dict) –
Describes a volume status operation code.
· Code (string) –
The code identifying the operation, for example,
enable-volume-io .
· Description (string) –
A description of the operation.
· EventType (string) –
The event type associated with this operation.
· EventId (string) –
The ID of the event associated with this operation.
Waiters
The available waiters are:
• EC2.Waiter.BundleTaskComplete
• EC2.Waiter.ConversionTaskCancelled
• EC2.Waiter.ConversionTaskCompleted
• EC2.Waiter.ConversionTaskDeleted
• EC2.Waiter.CustomerGatewayAvailable
• EC2.Waiter.ExportTaskCancelled
• EC2.Waiter.ExportTaskCompleted
• EC2.Waiter.ImageAvailable
• EC2.Waiter.InstanceExists
• EC2.Waiter.InstanceRunning
• EC2.Waiter.InstanceStatusOk
• EC2.Waiter.InstanceStopped
• EC2.Waiter.InstanceTerminated
• EC2.Waiter.PasswordDataAvailable
1488 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
• EC2.Waiter.SnapshotCompleted
• EC2.Waiter.SpotInstanceRequestFulfilled
• EC2.Waiter.SubnetAvailable
• EC2.Waiter.SystemStatusOk
• EC2.Waiter.VolumeAvailable
• EC2.Waiter.VolumeDeleted
• EC2.Waiter.VolumeInUse
• EC2.Waiter.VpcAvailable
• EC2.Waiter.VpnConnectionAvailable
• EC2.Waiter.VpnConnectionDeleted
class EC2.Waiter.BundleTaskComplete
waiter = client.get_waiter('bundle_task_complete')
wait(**kwargs)
Polls EC2.Client.describe_bundle_tasks() every 15 seconds until a successful state is
reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
BundleIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• BundleIds (list) – One or more bundle task IDs.
Default: Describes all your bundle tasks.
– (string) –
• Filters (list) – One or more filters.
– bundle-id - The ID of the bundle task.
– error-code - If the task failed, the error code returned.
– error-message - If the task failed, the error message returned.
– instance-id - The ID of the instance.
3.1. Services 1489
Boto3 Documentation, Release 1.1.4
– progress - The level of task completion, as a percentage (for example,
20%).
– s3-bucket - The Amazon S3 bucket to store the AMI.
– s3-prefix - The beginning of the AMI name.
– start-time - The time the task started (for example, 2013-09-
15T17:15:20.000Z).
– state - The state of the task (pending | waiting-for-shutdown
| bundling | storing | cancelling | complete | failed ).
– update-time - The time of the most recent update for the task.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Returns None
class EC2.Waiter.ConversionTaskCancelled
waiter = client.get_waiter('conversion_task_cancelled')
wait(**kwargs)
Polls EC2.Client.describe_conversion_tasks() every 15 seconds until a successful state
is reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
ConversionTaskIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Filters (list) – One or more filters.
– (dict) –
1490 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• ConversionTaskIds (list) – One or more conversion task IDs.
– (string) –
Returns None
class EC2.Waiter.ConversionTaskCompleted
waiter = client.get_waiter('conversion_task_completed')
wait(**kwargs)
Polls EC2.Client.describe_conversion_tasks() every 15 seconds until a successful state
is reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
ConversionTaskIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Filters (list) – One or more filters.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• ConversionTaskIds (list) – One or more conversion task IDs.
3.1. Services 1491
Boto3 Documentation, Release 1.1.4
– (string) –
Returns None
class EC2.Waiter.ConversionTaskDeleted
waiter = client.get_waiter('conversion_task_deleted')
wait(**kwargs)
Polls EC2.Client.describe_conversion_tasks() every 15 seconds until a successful state
is reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
ConversionTaskIds=[
'string',
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• Filters (list) – One or more filters.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• ConversionTaskIds (list) – One or more conversion task IDs.
– (string) –
Returns None
class EC2.Waiter.CustomerGatewayAvailable
waiter = client.get_waiter('customer_gateway_available')
1492 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
wait(**kwargs)
Polls EC2.Client.describe_customer_gateways() every 15 seconds until a successful state
is reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
CustomerGatewayIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• CustomerGatewayIds (list) – One or more customer gateway IDs.
Default: Describes all your customer gateways.
– (string) –
• Filters (list) – One or more filters.
– bgp-asn - The customer gateway’s Border Gateway Protocol (BGP) Au-
tonomous System Number (ASN).
– customer-gateway-id - The ID of the customer gateway.
– ip-address - The IP address of the customer gateway’s Internet-
routable external interface.
– state - The state of the customer gateway (pending | available |
deleting | deleted ).
– type - The type of customer gateway. Currently, the only supported type
is ipsec.1 .
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
3.1. Services 1493
Boto3 Documentation, Release 1.1.4
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Returns None
class EC2.Waiter.ExportTaskCancelled
waiter = client.get_waiter('export_task_cancelled')
wait(**kwargs)
Polls EC2.Client.describe_export_tasks() every 15 seconds until a successful state is
reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
ExportTaskIds=[
'string',
]
)
Parameters ExportTaskIds (list) – One or more export task IDs.
• (string) –
Returns None
class EC2.Waiter.ExportTaskCompleted
waiter = client.get_waiter('export_task_completed')
wait(**kwargs)
Polls EC2.Client.describe_export_tasks() every 15 seconds until a successful state is
reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
ExportTaskIds=[
'string',
]
)
Parameters ExportTaskIds (list) – One or more export task IDs.
• (string) –
Returns None
class EC2.Waiter.ImageAvailable
waiter = client.get_waiter('image_available')
wait(**kwargs)
Polls EC2.Client.describe_images() every 15 seconds until a successful state is reached. An
error is returned after 40 failed checks.
Request Syntax
1494 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
waiter.wait(
DryRun=True|False,
ImageIds=[
'string',
],
Owners=[
'string',
],
ExecutableUsers=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageIds (list) – One or more image IDs.
Default: Describes all images available to you.
– (string) –
• Owners (list) – Filters the images by the owner. Specify an AWS account ID,
amazon (owner is Amazon), aws-marketplace (owner is AWS Market-
place), self (owner is the sender of the request). Omitting this option returns
all images for which you have launch permissions, regardless of ownership.
– (string) –
• ExecutableUsers (list) – Scopes the images by users with explicit launch per-
missions. Specify an AWS account ID, self (the sender of the request), or all
(public AMIs).
– (string) –
• Filters (list) – One or more filters.
– architecture - The image architecture (i386 | x86_64 ).
– block-device-mapping.delete-on-termination - A
Boolean value that indicates whether the Amazon EBS volume is deleted
on instance termination.
– block-device-mapping.device-name - The device name for the
EBS volume (for example, /dev/sdh ).
– block-device-mapping.snapshot-id - The ID of the snapshot
used for the EBS volume.
– block-device-mapping.volume-size - The volume size of the
EBS volume, in GiB.
– block-device-mapping.volume-type - The volume type of the
EBS volume (gp2 | standard | io1 ).
– description - The description of the image (provided during image
creation).
– hypervisor - The hypervisor type (ovm | xen ).
3.1. Services 1495
Boto3 Documentation, Release 1.1.4
– image-id - The ID of the image.
– image-type - The image type (machine | kernel | ramdisk ).
– is-public - A Boolean that indicates whether the image is public.
– kernel-id - The kernel ID.
– manifest-location - The location of the image manifest.
– name - The name of the AMI (provided during image creation).
– owner-alias - The AWS account alias (for example, amazon ).
– owner-id - The AWS account ID of the image owner.
– platform - The platform. To only list Windows-based AMIs, use
windows .
– product-code - The product code.
– product-code.type - The type of the product code (devpay |
marketplace ).
– ramdisk-id - The RAM disk ID.
– root-device-name - The name of the root device volume (for exam-
ple, /dev/sda1 ).
– root-device-type - The type of the root device volume (ebs |
instance-store ).
– state - The state of the image (available | pending | failed ).
– state-reason-code - The reason code for the state change.
– state-reason-message - The message for the state change.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is in-
dependent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– virtualization-type - The virtualization type (paravirtual |
hvm ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Returns None
class EC2.Waiter.InstanceExists
waiter = client.get_waiter('instance_exists')
wait(**kwargs)
Polls EC2.Client.describe_instances() every 5 seconds until a successful state is reached.
An error is returned after 40 failed checks.
1496 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
waiter.wait(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
– (string) –
• Filters (list) – One or more filters.
– architecture - The instance architecture (i386 | x86_64 ).
– availability-zone - The Availability Zone of the instance.
– block-device-mapping.attach-time - The attach time
for an EBS volume mapped to the instance, for example,
2010-09-15T17:15:20.000Z .
– block-device-mapping.delete-on-termination - A
Boolean that indicates whether the EBS volume is deleted on instance
termination.
– block-device-mapping.device-name - The device name for the
EBS volume (for example, /dev/sdh or xvdh ).
– block-device-mapping.status - The status for the EBS volume
(attaching | attached | detaching | detached ).
– block-device-mapping.volume-id - The volume ID of the EBS
volume.
– client-token - The idempotency token you provided when you
launched the instance.
– dns-name - The public DNS name of the instance.
– group-id - The ID of the security group for the instance. EC2-Classic
only.
– group-name - The name of the security group for the instance. EC2-
Classic only.
– hypervisor - The hypervisor type of the instance (ovm | xen ).
– iam-instance-profile.arn - The instance profile associated with
the instance. Specified as an ARN.
– image-id - The ID of the image used to launch the instance.
– instance-id - The ID of the instance.
3.1. Services 1497
Boto3 Documentation, Release 1.1.4
– instance-lifecycle - Indicates whether this is a Spot Instance
(spot ).
– instance-state-code - The state of the instance, as a 16-bit un-
signed integer. The high byte is an opaque internal value and should be
ignored. The low byte is set based on the state represented. The valid val-
ues are: 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-type - The type of instance (for example, t2.micro ).
– instance.group-id - The ID of the security group for the instance.
– instance.group-name - The name of the security group for the in-
stance.
– ip-address - The public IP address of the instance.
– kernel-id - The kernel ID.
– key-name - The name of the key pair used when the instance was
launched.
– launch-index - When launching multiple instances, this is the index
for the instance in the launch group (for example, 0, 1, 2, and so on).
– launch-time - The time when the instance was launched.
– monitoring-state - Indicates whether monitoring is enabled for the
instance (disabled | enabled ).
– owner-id - The AWS account ID of the instance owner.
– placement-group-name - The name of the placement group for the
instance.
– platform - The platform. Use windows if you have Windows in-
stances; otherwise, leave blank.
– private-dns-name - The private DNS name of the instance.
– private-ip-address - The private IP address of the instance.
– product-code - The product code associated with the AMI used to
launch the instance.
– product-code.type - The type of product code (devpay |
marketplace ).
– ramdisk-id - The RAM disk ID.
– reason - The reason for the current state of the instance (for example,
shows “User Initiated [date]” when you stop or terminate the instance).
Similar to the state-reason-code filter.
– requester-id - The ID of the entity that launched the instance on
your behalf (for example, AWS Management Console, Auto Scaling, and
so on).
– reservation-id - The ID of the instance’s reservation. A reservation
ID is created any time you launch an instance. A reservation ID has a
one-to-one relationship with an instance launch request, but can be asso-
ciated with more than one instance if you launch multiple instances using
the same launch request. For example, if you launch one instance, you’ll
get one reservation ID. If you launch ten instances using the same launch
request, you’ll also get one reservation ID.
– root-device-name - The name of the root device for the instance (for
example, /dev/sda1 or /dev/xvda ).
– root-device-type - The type of root device that the instance uses
(ebs | instance-store ).
– source-dest-check - Indicates whether the instance performs
source/destination checking. A value of true means that checking is
1498 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
enabled, and false means checking is disabled. The value must be
false for the instance to perform network address translation (NAT) in
your VPC.
– spot-instance-request-id - The ID of the Spot Instance request.
– state-reason-code - The reason code for the state change.
– state-reason-message - A message that describes the state change.
– subnet-id - The ID of the subnet for the instance.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource, where tag :key is the tag’s key.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– tenancy - The tenancy of an instance (dedicated | default ).
– virtualization-type - The virtualization type of the instance
(paravirtual | hvm ).
– vpc-id - The ID of the VPC that the instance is running in.
– network-interface.description - The description of the net-
work interface.
– network-interface.subnet-id - The ID of the subnet for the net-
work interface.
– network-interface.vpc-id - The ID of the VPC for the network
interface.
– network-interface.network-interface.id - The ID of the
network interface.
– network-interface.owner-id - The ID of the owner of the net-
work interface.
– network-interface.availability-zone - The Availability
Zone for the network interface.
– network-interface.requester-id - The requester ID for the
network interface.
– network-interface.requester-managed - Indicates whether
the network interface is being managed by AWS.
– network-interface.status - The status of the network interface
(available ) | in-use ).
– network-interface.mac-address - The MAC address of the net-
work interface.
– network-interface-private-dns-name - The private DNS
name of the network interface.
– network-interface.source-dest-check - Whether the net-
work interface performs source/destination checking. A value of true
means checking is enabled, and false means checking is disabled. The
value must be false for the network interface to perform network ad-
dress translation (NAT) in your VPC.
– network-interface.group-id - The ID of a security group asso-
ciated with the network interface.
– network-interface.group-name - The name of a security group
associated with the network interface.
– network-interface.attachment.attachment-id - The ID
of the interface attachment.
3.1. Services 1499
Boto3 Documentation, Release 1.1.4
– network-interface.attachment.instance-id - The ID of
the instance to which the network interface is attached.
– network-interface.attachment.instance-owner-id -
The owner ID of the instance to which the network interface is attached.
– network-interface.addresses.private-ip-address -
The private IP address associated with the network interface.
– network-interface.attachment.device-index - The de-
vice index to which the network interface is attached.
– network-interface.attachment.status - The status of the at-
tachment (attaching | attached | detaching | detached ).
– network-interface.attachment.attach-time - The time
that the network interface was attached to an instance.
– network-interface.attachment.delete-on-termination
- Specifies whether the attachment is deleted when an instance is termi-
nated.
– network-interface.addresses.primary - Specifies whether
the IP address of the network interface is the primary private IP address.
– network-interface.addresses.association.public-ip
- The ID of the association of an Elastic IP address with a network
interface.
– network-interface.addresses.association.ip-owner-id
- The owner ID of the private IP address associated with the network
interface.
– association.public-ip - The address of the Elastic IP address
bound to the network interface.
– association.ip-owner-id - The owner of the Elastic IP address
associated with the network interface.
– association.allocation-id - The allocation ID returned when
you allocated the Elastic IP address for your network interface.
– association.association-id - The association ID returned
when the network interface was associated with an IP address.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to request the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
IDs parameter in the same request.
Returns None
class EC2.Waiter.InstanceRunning
1500 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
waiter = client.get_waiter('instance_running')
wait(**kwargs)
Polls EC2.Client.describe_instances() every 15 seconds until a successful state is reached.
An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
– (string) –
• Filters (list) – One or more filters.
– architecture - The instance architecture (i386 | x86_64 ).
– availability-zone - The Availability Zone of the instance.
– block-device-mapping.attach-time - The attach time
for an EBS volume mapped to the instance, for example,
2010-09-15T17:15:20.000Z .
– block-device-mapping.delete-on-termination - A
Boolean that indicates whether the EBS volume is deleted on instance
termination.
– block-device-mapping.device-name - The device name for the
EBS volume (for example, /dev/sdh or xvdh ).
– block-device-mapping.status - The status for the EBS volume
(attaching | attached | detaching | detached ).
– block-device-mapping.volume-id - The volume ID of the EBS
volume.
– client-token - The idempotency token you provided when you
launched the instance.
– dns-name - The public DNS name of the instance.
– group-id - The ID of the security group for the instance. EC2-Classic
only.
– group-name - The name of the security group for the instance. EC2-
Classic only.
3.1. Services 1501
Boto3 Documentation, Release 1.1.4
– hypervisor - The hypervisor type of the instance (ovm | xen ).
– iam-instance-profile.arn - The instance profile associated with
the instance. Specified as an ARN.
– image-id - The ID of the image used to launch the instance.
– instance-id - The ID of the instance.
– instance-lifecycle - Indicates whether this is a Spot Instance
(spot ).
– instance-state-code - The state of the instance, as a 16-bit un-
signed integer. The high byte is an opaque internal value and should be
ignored. The low byte is set based on the state represented. The valid val-
ues are: 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-type - The type of instance (for example, t2.micro ).
– instance.group-id - The ID of the security group for the instance.
– instance.group-name - The name of the security group for the in-
stance.
– ip-address - The public IP address of the instance.
– kernel-id - The kernel ID.
– key-name - The name of the key pair used when the instance was
launched.
– launch-index - When launching multiple instances, this is the index
for the instance in the launch group (for example, 0, 1, 2, and so on).
– launch-time - The time when the instance was launched.
– monitoring-state - Indicates whether monitoring is enabled for the
instance (disabled | enabled ).
– owner-id - The AWS account ID of the instance owner.
– placement-group-name - The name of the placement group for the
instance.
– platform - The platform. Use windows if you have Windows in-
stances; otherwise, leave blank.
– private-dns-name - The private DNS name of the instance.
– private-ip-address - The private IP address of the instance.
– product-code - The product code associated with the AMI used to
launch the instance.
– product-code.type - The type of product code (devpay |
marketplace ).
– ramdisk-id - The RAM disk ID.
– reason - The reason for the current state of the instance (for example,
shows “User Initiated [date]” when you stop or terminate the instance).
Similar to the state-reason-code filter.
– requester-id - The ID of the entity that launched the instance on
your behalf (for example, AWS Management Console, Auto Scaling, and
so on).
– reservation-id - The ID of the instance’s reservation. A reservation
ID is created any time you launch an instance. A reservation ID has a
one-to-one relationship with an instance launch request, but can be asso-
ciated with more than one instance if you launch multiple instances using
the same launch request. For example, if you launch one instance, you’ll
get one reservation ID. If you launch ten instances using the same launch
request, you’ll also get one reservation ID.
– root-device-name - The name of the root device for the instance (for
1502 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
example, /dev/sda1 or /dev/xvda ).
– root-device-type - The type of root device that the instance uses
(ebs | instance-store ).
– source-dest-check - Indicates whether the instance performs
source/destination checking. A value of true means that checking is
enabled, and false means checking is disabled. The value must be
false for the instance to perform network address translation (NAT) in
your VPC.
– spot-instance-request-id - The ID of the Spot Instance request.
– state-reason-code - The reason code for the state change.
– state-reason-message - A message that describes the state change.
– subnet-id - The ID of the subnet for the instance.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource, where tag :key is the tag’s key.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– tenancy - The tenancy of an instance (dedicated | default ).
– virtualization-type - The virtualization type of the instance
(paravirtual | hvm ).
– vpc-id - The ID of the VPC that the instance is running in.
– network-interface.description - The description of the net-
work interface.
– network-interface.subnet-id - The ID of the subnet for the net-
work interface.
– network-interface.vpc-id - The ID of the VPC for the network
interface.
– network-interface.network-interface.id - The ID of the
network interface.
– network-interface.owner-id - The ID of the owner of the net-
work interface.
– network-interface.availability-zone - The Availability
Zone for the network interface.
– network-interface.requester-id - The requester ID for the
network interface.
– network-interface.requester-managed - Indicates whether
the network interface is being managed by AWS.
– network-interface.status - The status of the network interface
(available ) | in-use ).
– network-interface.mac-address - The MAC address of the net-
work interface.
– network-interface-private-dns-name - The private DNS
name of the network interface.
– network-interface.source-dest-check - Whether the net-
work interface performs source/destination checking. A value of true
means checking is enabled, and false means checking is disabled. The
value must be false for the network interface to perform network ad-
dress translation (NAT) in your VPC.
– network-interface.group-id - The ID of a security group asso-
3.1. Services 1503
Boto3 Documentation, Release 1.1.4
ciated with the network interface.
– network-interface.group-name - The name of a security group
associated with the network interface.
– network-interface.attachment.attachment-id - The ID
of the interface attachment.
– network-interface.attachment.instance-id - The ID of
the instance to which the network interface is attached.
– network-interface.attachment.instance-owner-id -
The owner ID of the instance to which the network interface is attached.
– network-interface.addresses.private-ip-address -
The private IP address associated with the network interface.
– network-interface.attachment.device-index - The de-
vice index to which the network interface is attached.
– network-interface.attachment.status - The status of the at-
tachment (attaching | attached | detaching | detached ).
– network-interface.attachment.attach-time - The time
that the network interface was attached to an instance.
– network-interface.attachment.delete-on-termination
- Specifies whether the attachment is deleted when an instance is termi-
nated.
– network-interface.addresses.primary - Specifies whether
the IP address of the network interface is the primary private IP address.
– network-interface.addresses.association.public-ip
- The ID of the association of an Elastic IP address with a network
interface.
– network-interface.addresses.association.ip-owner-id
- The owner ID of the private IP address associated with the network
interface.
– association.public-ip - The address of the Elastic IP address
bound to the network interface.
– association.ip-owner-id - The owner of the Elastic IP address
associated with the network interface.
– association.allocation-id - The allocation ID returned when
you allocated the Elastic IP address for your network interface.
– association.association-id - The association ID returned
when the network interface was associated with an IP address.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to request the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
IDs parameter in the same request.
1504 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Returns None
class EC2.Waiter.InstanceStatusOk
waiter = client.get_waiter('instance_status_ok')
wait(**kwargs)
Polls EC2.Client.describe_instance_status() every 15 seconds until a successful state is
reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123,
IncludeAllInstances=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
Constraints: Maximum 100 explicitly specified instance IDs.
– (string) –
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone of the instance.
– event.code - The code for the scheduled event
(instance-reboot | system-reboot | system-maintenance
| instance-retirement | instance-stop ).
– event.description - A description of the event.
– event.not-after - The latest end time for the scheduled event (for
example, 2014-09-15T17:15:20.000Z ).
– event.not-before - The earliest start time for the scheduled event
(for example, 2014-09-15T17:15:20.000Z ).
– instance-state-code - The code for the instance state, as a 16-bit
unsigned integer. The high byte is an opaque internal value and should
be ignored. The low byte is set based on the state represented. The valid
values are 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
3.1. Services 1505
Boto3 Documentation, Release 1.1.4
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-status.reachability - Filters on instance sta-
tus where the name is reachability (passed | failed |
initializing | insufficient-data ).
– instance-status.status - The status of the instance (ok
| impaired | initializing | insufficient-data |
not-applicable ).
– system-status.reachability - Filters on system status where
the name is reachability (passed | failed | initializing
| insufficient-data ).
– system-status.status - The system status of the instance
(ok | impaired | initializing | insufficient-data |
not-applicable ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to retrieve the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
IDs parameter in the same request.
• IncludeAllInstances (boolean) – When true , includes the health status for all
instances. When false , includes the health status for running instances only.
Default: false
Returns None
class EC2.Waiter.InstanceStopped
waiter = client.get_waiter('instance_stopped')
wait(**kwargs)
Polls EC2.Client.describe_instances() every 15 seconds until a successful state is reached.
An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
1506 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
– (string) –
• Filters (list) – One or more filters.
– architecture - The instance architecture (i386 | x86_64 ).
– availability-zone - The Availability Zone of the instance.
– block-device-mapping.attach-time - The attach time
for an EBS volume mapped to the instance, for example,
2010-09-15T17:15:20.000Z .
– block-device-mapping.delete-on-termination - A
Boolean that indicates whether the EBS volume is deleted on instance
termination.
– block-device-mapping.device-name - The device name for the
EBS volume (for example, /dev/sdh or xvdh ).
– block-device-mapping.status - The status for the EBS volume
(attaching | attached | detaching | detached ).
– block-device-mapping.volume-id - The volume ID of the EBS
volume.
– client-token - The idempotency token you provided when you
launched the instance.
– dns-name - The public DNS name of the instance.
– group-id - The ID of the security group for the instance. EC2-Classic
only.
– group-name - The name of the security group for the instance. EC2-
Classic only.
– hypervisor - The hypervisor type of the instance (ovm | xen ).
– iam-instance-profile.arn - The instance profile associated with
the instance. Specified as an ARN.
– image-id - The ID of the image used to launch the instance.
– instance-id - The ID of the instance.
– instance-lifecycle - Indicates whether this is a Spot Instance
(spot ).
– instance-state-code - The state of the instance, as a 16-bit un-
signed integer. The high byte is an opaque internal value and should be
ignored. The low byte is set based on the state represented. The valid val-
ues are: 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
3.1. Services 1507
Boto3 Documentation, Release 1.1.4
running | shutting-down | terminated | stopping | stopped
).
– instance-type - The type of instance (for example, t2.micro ).
– instance.group-id - The ID of the security group for the instance.
– instance.group-name - The name of the security group for the in-
stance.
– ip-address - The public IP address of the instance.
– kernel-id - The kernel ID.
– key-name - The name of the key pair used when the instance was
launched.
– launch-index - When launching multiple instances, this is the index
for the instance in the launch group (for example, 0, 1, 2, and so on).
– launch-time - The time when the instance was launched.
– monitoring-state - Indicates whether monitoring is enabled for the
instance (disabled | enabled ).
– owner-id - The AWS account ID of the instance owner.
– placement-group-name - The name of the placement group for the
instance.
– platform - The platform. Use windows if you have Windows in-
stances; otherwise, leave blank.
– private-dns-name - The private DNS name of the instance.
– private-ip-address - The private IP address of the instance.
– product-code - The product code associated with the AMI used to
launch the instance.
– product-code.type - The type of product code (devpay |
marketplace ).
– ramdisk-id - The RAM disk ID.
– reason - The reason for the current state of the instance (for example,
shows “User Initiated [date]” when you stop or terminate the instance).
Similar to the state-reason-code filter.
– requester-id - The ID of the entity that launched the instance on
your behalf (for example, AWS Management Console, Auto Scaling, and
so on).
– reservation-id - The ID of the instance’s reservation. A reservation
ID is created any time you launch an instance. A reservation ID has a
one-to-one relationship with an instance launch request, but can be asso-
ciated with more than one instance if you launch multiple instances using
the same launch request. For example, if you launch one instance, you’ll
get one reservation ID. If you launch ten instances using the same launch
request, you’ll also get one reservation ID.
– root-device-name - The name of the root device for the instance (for
example, /dev/sda1 or /dev/xvda ).
– root-device-type - The type of root device that the instance uses
(ebs | instance-store ).
– source-dest-check - Indicates whether the instance performs
source/destination checking. A value of true means that checking is
enabled, and false means checking is disabled. The value must be
false for the instance to perform network address translation (NAT) in
your VPC.
– spot-instance-request-id - The ID of the Spot Instance request.
– state-reason-code - The reason code for the state change.
– state-reason-message - A message that describes the state change.
– subnet-id - The ID of the subnet for the instance.
– tag :key =*value* - The key/value combination of a tag assigned to the
1508 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
resource, where tag :key is the tag’s key.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– tenancy - The tenancy of an instance (dedicated | default ).
– virtualization-type - The virtualization type of the instance
(paravirtual | hvm ).
– vpc-id - The ID of the VPC that the instance is running in.
– network-interface.description - The description of the net-
work interface.
– network-interface.subnet-id - The ID of the subnet for the net-
work interface.
– network-interface.vpc-id - The ID of the VPC for the network
interface.
– network-interface.network-interface.id - The ID of the
network interface.
– network-interface.owner-id - The ID of the owner of the net-
work interface.
– network-interface.availability-zone - The Availability
Zone for the network interface.
– network-interface.requester-id - The requester ID for the
network interface.
– network-interface.requester-managed - Indicates whether
the network interface is being managed by AWS.
– network-interface.status - The status of the network interface
(available ) | in-use ).
– network-interface.mac-address - The MAC address of the net-
work interface.
– network-interface-private-dns-name - The private DNS
name of the network interface.
– network-interface.source-dest-check - Whether the net-
work interface performs source/destination checking. A value of true
means checking is enabled, and false means checking is disabled. The
value must be false for the network interface to perform network ad-
dress translation (NAT) in your VPC.
– network-interface.group-id - The ID of a security group asso-
ciated with the network interface.
– network-interface.group-name - The name of a security group
associated with the network interface.
– network-interface.attachment.attachment-id - The ID
of the interface attachment.
– network-interface.attachment.instance-id - The ID of
the instance to which the network interface is attached.
– network-interface.attachment.instance-owner-id -
The owner ID of the instance to which the network interface is attached.
– network-interface.addresses.private-ip-address -
The private IP address associated with the network interface.
– network-interface.attachment.device-index - The de-
vice index to which the network interface is attached.
3.1. Services 1509
Boto3 Documentation, Release 1.1.4
– network-interface.attachment.status - The status of the at-
tachment (attaching | attached | detaching | detached ).
– network-interface.attachment.attach-time - The time
that the network interface was attached to an instance.
– network-interface.attachment.delete-on-termination
- Specifies whether the attachment is deleted when an instance is termi-
nated.
– network-interface.addresses.primary - Specifies whether
the IP address of the network interface is the primary private IP address.
– network-interface.addresses.association.public-ip
- The ID of the association of an Elastic IP address with a network
interface.
– network-interface.addresses.association.ip-owner-id
- The owner ID of the private IP address associated with the network
interface.
– association.public-ip - The address of the Elastic IP address
bound to the network interface.
– association.ip-owner-id - The owner of the Elastic IP address
associated with the network interface.
– association.allocation-id - The allocation ID returned when
you allocated the Elastic IP address for your network interface.
– association.association-id - The association ID returned
when the network interface was associated with an IP address.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to request the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
IDs parameter in the same request.
Returns None
class EC2.Waiter.InstanceTerminated
waiter = client.get_waiter('instance_terminated')
wait(**kwargs)
Polls EC2.Client.describe_instances() every 15 seconds until a successful state is reached.
An error is returned after 40 failed checks.
Request Syntax
1510 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
waiter.wait(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
– (string) –
• Filters (list) – One or more filters.
– architecture - The instance architecture (i386 | x86_64 ).
– availability-zone - The Availability Zone of the instance.
– block-device-mapping.attach-time - The attach time
for an EBS volume mapped to the instance, for example,
2010-09-15T17:15:20.000Z .
– block-device-mapping.delete-on-termination - A
Boolean that indicates whether the EBS volume is deleted on instance
termination.
– block-device-mapping.device-name - The device name for the
EBS volume (for example, /dev/sdh or xvdh ).
– block-device-mapping.status - The status for the EBS volume
(attaching | attached | detaching | detached ).
– block-device-mapping.volume-id - The volume ID of the EBS
volume.
– client-token - The idempotency token you provided when you
launched the instance.
– dns-name - The public DNS name of the instance.
– group-id - The ID of the security group for the instance. EC2-Classic
only.
– group-name - The name of the security group for the instance. EC2-
Classic only.
– hypervisor - The hypervisor type of the instance (ovm | xen ).
– iam-instance-profile.arn - The instance profile associated with
the instance. Specified as an ARN.
– image-id - The ID of the image used to launch the instance.
– instance-id - The ID of the instance.
– instance-lifecycle - Indicates whether this is a Spot Instance
(spot ).
3.1. Services 1511
Boto3 Documentation, Release 1.1.4
– instance-state-code - The state of the instance, as a 16-bit un-
signed integer. The high byte is an opaque internal value and should be
ignored. The low byte is set based on the state represented. The valid val-
ues are: 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-type - The type of instance (for example, t2.micro ).
– instance.group-id - The ID of the security group for the instance.
– instance.group-name - The name of the security group for the in-
stance.
– ip-address - The public IP address of the instance.
– kernel-id - The kernel ID.
– key-name - The name of the key pair used when the instance was
launched.
– launch-index - When launching multiple instances, this is the index
for the instance in the launch group (for example, 0, 1, 2, and so on).
– launch-time - The time when the instance was launched.
– monitoring-state - Indicates whether monitoring is enabled for the
instance (disabled | enabled ).
– owner-id - The AWS account ID of the instance owner.
– placement-group-name - The name of the placement group for the
instance.
– platform - The platform. Use windows if you have Windows in-
stances; otherwise, leave blank.
– private-dns-name - The private DNS name of the instance.
– private-ip-address - The private IP address of the instance.
– product-code - The product code associated with the AMI used to
launch the instance.
– product-code.type - The type of product code (devpay |
marketplace ).
– ramdisk-id - The RAM disk ID.
– reason - The reason for the current state of the instance (for example,
shows “User Initiated [date]” when you stop or terminate the instance).
Similar to the state-reason-code filter.
– requester-id - The ID of the entity that launched the instance on
your behalf (for example, AWS Management Console, Auto Scaling, and
so on).
– reservation-id - The ID of the instance’s reservation. A reservation
ID is created any time you launch an instance. A reservation ID has a
one-to-one relationship with an instance launch request, but can be asso-
ciated with more than one instance if you launch multiple instances using
the same launch request. For example, if you launch one instance, you’ll
get one reservation ID. If you launch ten instances using the same launch
request, you’ll also get one reservation ID.
– root-device-name - The name of the root device for the instance (for
example, /dev/sda1 or /dev/xvda ).
– root-device-type - The type of root device that the instance uses
(ebs | instance-store ).
– source-dest-check - Indicates whether the instance performs
source/destination checking. A value of true means that checking is
enabled, and false means checking is disabled. The value must be
false for the instance to perform network address translation (NAT) in
1512 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
your VPC.
– spot-instance-request-id - The ID of the Spot Instance request.
– state-reason-code - The reason code for the state change.
– state-reason-message - A message that describes the state change.
– subnet-id - The ID of the subnet for the instance.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource, where tag :key is the tag’s key.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– tenancy - The tenancy of an instance (dedicated | default ).
– virtualization-type - The virtualization type of the instance
(paravirtual | hvm ).
– vpc-id - The ID of the VPC that the instance is running in.
– network-interface.description - The description of the net-
work interface.
– network-interface.subnet-id - The ID of the subnet for the net-
work interface.
– network-interface.vpc-id - The ID of the VPC for the network
interface.
– network-interface.network-interface.id - The ID of the
network interface.
– network-interface.owner-id - The ID of the owner of the net-
work interface.
– network-interface.availability-zone - The Availability
Zone for the network interface.
– network-interface.requester-id - The requester ID for the
network interface.
– network-interface.requester-managed - Indicates whether
the network interface is being managed by AWS.
– network-interface.status - The status of the network interface
(available ) | in-use ).
– network-interface.mac-address - The MAC address of the net-
work interface.
– network-interface-private-dns-name - The private DNS
name of the network interface.
– network-interface.source-dest-check - Whether the net-
work interface performs source/destination checking. A value of true
means checking is enabled, and false means checking is disabled. The
value must be false for the network interface to perform network ad-
dress translation (NAT) in your VPC.
– network-interface.group-id - The ID of a security group asso-
ciated with the network interface.
– network-interface.group-name - The name of a security group
associated with the network interface.
– network-interface.attachment.attachment-id - The ID
of the interface attachment.
– network-interface.attachment.instance-id - The ID of
the instance to which the network interface is attached.
3.1. Services 1513
Boto3 Documentation, Release 1.1.4
– network-interface.attachment.instance-owner-id -
The owner ID of the instance to which the network interface is attached.
– network-interface.addresses.private-ip-address -
The private IP address associated with the network interface.
– network-interface.attachment.device-index - The de-
vice index to which the network interface is attached.
– network-interface.attachment.status - The status of the at-
tachment (attaching | attached | detaching | detached ).
– network-interface.attachment.attach-time - The time
that the network interface was attached to an instance.
– network-interface.attachment.delete-on-termination
- Specifies whether the attachment is deleted when an instance is termi-
nated.
– network-interface.addresses.primary - Specifies whether
the IP address of the network interface is the primary private IP address.
– network-interface.addresses.association.public-ip
- The ID of the association of an Elastic IP address with a network
interface.
– network-interface.addresses.association.ip-owner-id
- The owner ID of the private IP address associated with the network
interface.
– association.public-ip - The address of the Elastic IP address
bound to the network interface.
– association.ip-owner-id - The owner of the Elastic IP address
associated with the network interface.
– association.allocation-id - The allocation ID returned when
you allocated the Elastic IP address for your network interface.
– association.association-id - The association ID returned
when the network interface was associated with an IP address.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to request the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
IDs parameter in the same request.
Returns None
class EC2.Waiter.PasswordDataAvailable
waiter = client.get_waiter('password_data_available')
1514 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
wait(**kwargs)
Polls EC2.Client.get_password_data() every 15 seconds until a successful state is reached.
An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
InstanceId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceId (string) – [REQUIRED]
The ID of the Windows instance.
Returns None
class EC2.Waiter.SnapshotCompleted
waiter = client.get_waiter('snapshot_completed')
wait(**kwargs)
Polls EC2.Client.describe_snapshots() every 15 seconds until a successful state is reached.
An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
SnapshotIds=[
'string',
],
OwnerIds=[
'string',
],
RestorableByUserIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
3.1. Services 1515
Boto3 Documentation, Release 1.1.4
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SnapshotIds (list) – One or more snapshot IDs.
Default: Describes snapshots for which you have launch permissions.
– (string) –
• OwnerIds (list) – Returns the snapshots owned by the specified owner. Multiple
owners can be specified.
– (string) –
• RestorableByUserIds (list) – One or more AWS accounts IDs that can create
volumes from the snapshot.
– (string) –
• Filters (list) – One or more filters.
– description - A description of the snapshot.
– owner-alias - The AWS account alias (for example, amazon ) that
owns the snapshot.
– owner-id - The ID of the AWS account that owns the snapshot.
– progress - The progress of the snapshot, as a percentage (for example,
80%).
– snapshot-id - The snapshot ID.
– start-time - The time stamp when the snapshot was initiated.
– status - The status of the snapshot (pending | completed | error
).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– volume-id - The ID of the volume the snapshot is for.
– volume-size - The size of the volume, in GiB.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The NextToken value returned from a previous pagi-
nated DescribeSnapshots request where MaxResults was used and the
results exceeded the value of that parameter. Pagination continues from the end
of the previous results that returned the NextToken value. This value is null
when there are no more results to return.
• MaxResults (integer) – The maximum number of snapshot results returned by
DescribeSnapshots in paginated output. When this parameter is used,
DescribeSnapshots only returns MaxResults results in a single page
1516 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
along with a NextToken response element. The remaining results of the ini-
tial request can be seen by sending another DescribeSnapshots request
with the returned NextToken value. This value can be between 5 and 1000; if
MaxResults is given a value larger than 1000, only 1000 results are returned.
If this parameter is not used, then DescribeSnapshots returns all results.
You cannot specify this parameter and the snapshot IDs parameter in the same
request.
Returns None
class EC2.Waiter.SpotInstanceRequestFulfilled
waiter = client.get_waiter('spot_instance_request_fulfilled')
wait(**kwargs)
Polls EC2.Client.describe_spot_instance_requests() every 15 seconds until a success-
ful state is reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
SpotInstanceRequestIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SpotInstanceRequestIds (list) – One or more Spot instance request IDs.
– (string) –
• Filters (list) – One or more filters.
– availability-zone-group - The Availability Zone group.
– create-time - The time stamp when the Spot instance request was
created.
– fault-code - The fault code related to the request.
– fault-message - The fault message related to the request.
– instance-id - The ID of the instance that fulfilled the request.
– launch-group - The Spot instance launch group.
– launch.block-device-mapping.delete-on-termination
- Indicates whether the Amazon EBS volume is deleted on instance
termination.
– launch.block-device-mapping.device-name - The device
name for the Amazon EBS volume (for example, /dev/sdh ).
3.1. Services 1517
Boto3 Documentation, Release 1.1.4
– launch.block-device-mapping.snapshot-id - The ID of the
snapshot used for the Amazon EBS volume.
– launch.block-device-mapping.volume-size - The size of
the Amazon EBS volume, in GiB.
– launch.block-device-mapping.volume-type - The type of
the Amazon EBS volume (gp2 | standard | io1 ).
– launch.group-id - The security group for the instance.
– launch.image-id - The ID of the AMI.
– launch.instance-type - The type of instance (for example,
m1.small ).
– launch.kernel-id - The kernel ID.
– launch.key-name - The name of the key pair the instance launched
with.
– launch.monitoring-enabled - Whether monitoring is enabled for
the Spot instance.
– launch.ramdisk-id - The RAM disk ID.
– network-interface.network-interface-id - The ID of the
network interface.
– network-interface.device-index - The index of the device for
the network interface attachment on the instance.
– network-interface.subnet-id - The ID of the subnet for the in-
stance.
– network-interface.description - A description of the network
interface.
– network-interface.private-ip-address - The primary pri-
vate IP address of the network interface.
– network-interface.delete-on-termination - Indicates
whether the network interface is deleted when the instance is terminated.
– network-interface.group-id - The ID of the security group as-
sociated with the network interface.
– network-interface.group-name - The name of the security
group associated with the network interface.
– network-interface.addresses.primary - Indicates whether
the IP address is the primary private IP address.
– product-description - The product description associated with the
instance (Linux/UNIX | Windows ).
– spot-instance-request-id - The Spot instance request ID.
– spot-price - The maximum hourly price for any Spot instance
launched to fulfill the request.
– state - The state of the Spot instance request (open | active |
closed | cancelled | failed ). Spot bid status information can
help you track your Amazon EC2 Spot instance requests. For more infor-
mation, see Spot Bid Status in the Amazon Elastic Compute Cloud User
Guide.
– status-code - The short code describing the most recent evaluation of
your Spot instance request.
– status-message - The message explaining the status of the Spot in-
stance request.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
1518 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– type - The type of Spot instance request (one-time | persistent ).
– launched-availability-zone - The Availability Zone in which
the bid is launched.
– valid-from - The start date of the request.
– valid-until - The end date of the request.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Returns None
class EC2.Waiter.SubnetAvailable
waiter = client.get_waiter('subnet_available')
wait(**kwargs)
Polls EC2.Client.describe_subnets() every 15 seconds until a successful state is reached. An
error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
SubnetIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• SubnetIds (list) – One or more subnet IDs.
Default: Describes all your subnets.
– (string) –
3.1. Services 1519
Boto3 Documentation, Release 1.1.4
• Filters (list) – One or more filters.
– availabilityZone - The Availability Zone for the subnet. You can
also use availability-zone as the filter name.
– available-ip-address-count - The number of IP addresses in
the subnet that are available.
– cidrBlock - The CIDR block of the subnet. The CIDR block you spec-
ify must exactly match the subnet’s CIDR block for information to be
returned for the subnet. You can also use cidr or cidr-block as the
filter names.
– defaultForAz - Indicates whether this is the default subnet for the
Availability Zone. You can also use default-for-az as the filter
name.
– state - The state of the subnet (pending | available ).
– subnet-id - The ID of the subnet.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-id - The ID of the VPC for the subnet.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Returns None
class EC2.Waiter.SystemStatusOk
waiter = client.get_waiter('system_status_ok')
wait(**kwargs)
Polls EC2.Client.describe_instance_status() every 15 seconds until a successful state is
reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
InstanceIds=[
'string',
],
Filters=[
1520 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123,
IncludeAllInstances=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• InstanceIds (list) – One or more instance IDs.
Default: Describes all your instances.
Constraints: Maximum 100 explicitly specified instance IDs.
– (string) –
• Filters (list) – One or more filters.
– availability-zone - The Availability Zone of the instance.
– event.code - The code for the scheduled event
(instance-reboot | system-reboot | system-maintenance
| instance-retirement | instance-stop ).
– event.description - A description of the event.
– event.not-after - The latest end time for the scheduled event (for
example, 2014-09-15T17:15:20.000Z ).
– event.not-before - The earliest start time for the scheduled event
(for example, 2014-09-15T17:15:20.000Z ).
– instance-state-code - The code for the instance state, as a 16-bit
unsigned integer. The high byte is an opaque internal value and should
be ignored. The low byte is set based on the state represented. The valid
values are 0 (pending), 16 (running), 32 (shutting-down), 48 (terminated),
64 (stopping), and 80 (stopped).
– instance-state-name - The state of the instance (pending |
running | shutting-down | terminated | stopping | stopped
).
– instance-status.reachability - Filters on instance sta-
tus where the name is reachability (passed | failed |
initializing | insufficient-data ).
– instance-status.status - The status of the instance (ok
| impaired | initializing | insufficient-data |
not-applicable ).
– system-status.reachability - Filters on system status where
the name is reachability (passed | failed | initializing
| insufficient-data ).
– system-status.status - The system status of the instance
(ok | impaired | initializing | insufficient-data |
not-applicable ).
– (dict) –
A filter name and value pair that is used to return a more specific list of
3.1. Services 1521
Boto3 Documentation, Release 1.1.4
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The token to retrieve the next page of results.
• MaxResults (integer) – The maximum number of results to return for the request
in a single page. The remaining results of the initial request can be seen by
sending another request with the returned NextToken value. This value can be
between 5 and 1000; if MaxResults is given a value larger than 1000, only
1000 results are returned. You cannot specify this parameter and the instance
IDs parameter in the same request.
• IncludeAllInstances (boolean) – When true , includes the health status for all
instances. When false , includes the health status for running instances only.
Default: false
Returns None
class EC2.Waiter.VolumeAvailable
waiter = client.get_waiter('volume_available')
wait(**kwargs)
Polls EC2.Client.describe_volumes() every 15 seconds until a successful state is reached. An
error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
VolumeIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeIds (list) – One or more volume IDs.
– (string) –
• Filters (list) – One or more filters.
1522 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– attachment.attach-time - The time stamp when the attachment
initiated.
– attachment.delete-on-termination - Whether the volume is
deleted on instance termination.
– attachment.device - The device name that is exposed to the instance
(for example, /dev/sda1 ).
– attachment.instance-id - The ID of the instance the volume is
attached to.
– attachment.status - The attachment state (attaching |
attached | detaching | detached ).
– availability-zone - The Availability Zone in which the volume
was created.
– create-time - The time stamp when the volume was created.
– encrypted - The encryption status of the volume.
– size - The size of the volume, in GiB.
– snapshot-id - The snapshot from which the volume was created.
– status - The status of the volume (creating | available | in-use
| deleting | deleted | error ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– volume-id - The volume ID.
– volume-type - The Amazon EBS volume type. This can be gp2 for
General Purpose (SSD) volumes, io1 for Provisioned IOPS (SSD) vol-
umes, or standard for Magnetic volumes.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The NextToken value returned from a previous pagi-
nated DescribeVolumes request where MaxResults was used and the re-
sults exceeded the value of that parameter. Pagination continues from the end
of the previous results that returned the NextToken value. This value is null
when there are no more results to return.
• MaxResults (integer) – The maximum number of volume results returned
by DescribeVolumes in paginated output. When this parameter is used,
DescribeVolumes only returns MaxResults results in a single page along
with a NextToken response element. The remaining results of the initial
request can be seen by sending another DescribeVolumes request with
the returned NextToken value. This value can be between 5 and 1000; if
3.1. Services 1523
Boto3 Documentation, Release 1.1.4
MaxResults is given a value larger than 1000, only 1000 results are returned.
If this parameter is not used, then DescribeVolumes returns all results. You
cannot specify this parameter and the volume IDs parameter in the same request.
Returns None
class EC2.Waiter.VolumeDeleted
waiter = client.get_waiter('volume_deleted')
wait(**kwargs)
Polls EC2.Client.describe_volumes() every 15 seconds until a successful state is reached. An
error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
VolumeIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeIds (list) – One or more volume IDs.
– (string) –
• Filters (list) – One or more filters.
– attachment.attach-time - The time stamp when the attachment
initiated.
– attachment.delete-on-termination - Whether the volume is
deleted on instance termination.
– attachment.device - The device name that is exposed to the instance
(for example, /dev/sda1 ).
– attachment.instance-id - The ID of the instance the volume is
attached to.
– attachment.status - The attachment state (attaching |
attached | detaching | detached ).
– availability-zone - The Availability Zone in which the volume
was created.
– create-time - The time stamp when the volume was created.
– encrypted - The encryption status of the volume.
– size - The size of the volume, in GiB.
1524 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– snapshot-id - The snapshot from which the volume was created.
– status - The status of the volume (creating | available | in-use
| deleting | deleted | error ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– volume-id - The volume ID.
– volume-type - The Amazon EBS volume type. This can be gp2 for
General Purpose (SSD) volumes, io1 for Provisioned IOPS (SSD) vol-
umes, or standard for Magnetic volumes.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The NextToken value returned from a previous pagi-
nated DescribeVolumes request where MaxResults was used and the re-
sults exceeded the value of that parameter. Pagination continues from the end
of the previous results that returned the NextToken value. This value is null
when there are no more results to return.
• MaxResults (integer) – The maximum number of volume results returned
by DescribeVolumes in paginated output. When this parameter is used,
DescribeVolumes only returns MaxResults results in a single page along
with a NextToken response element. The remaining results of the initial
request can be seen by sending another DescribeVolumes request with
the returned NextToken value. This value can be between 5 and 1000; if
MaxResults is given a value larger than 1000, only 1000 results are returned.
If this parameter is not used, then DescribeVolumes returns all results. You
cannot specify this parameter and the volume IDs parameter in the same request.
Returns None
class EC2.Waiter.VolumeInUse
waiter = client.get_waiter('volume_in_use')
wait(**kwargs)
Polls EC2.Client.describe_volumes() every 15 seconds until a successful state is reached. An
error is returned after 40 failed checks.
Request Syntax
3.1. Services 1525
Boto3 Documentation, Release 1.1.4
waiter.wait(
DryRun=True|False,
VolumeIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VolumeIds (list) – One or more volume IDs.
– (string) –
• Filters (list) – One or more filters.
– attachment.attach-time - The time stamp when the attachment
initiated.
– attachment.delete-on-termination - Whether the volume is
deleted on instance termination.
– attachment.device - The device name that is exposed to the instance
(for example, /dev/sda1 ).
– attachment.instance-id - The ID of the instance the volume is
attached to.
– attachment.status - The attachment state (attaching |
attached | detaching | detached ).
– availability-zone - The Availability Zone in which the volume
was created.
– create-time - The time stamp when the volume was created.
– encrypted - The encryption status of the volume.
– size - The size of the volume, in GiB.
– snapshot-id - The snapshot from which the volume was created.
– status - The status of the volume (creating | available | in-use
| deleting | deleted | error ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– volume-id - The volume ID.
1526 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– volume-type - The Amazon EBS volume type. This can be gp2 for
General Purpose (SSD) volumes, io1 for Provisioned IOPS (SSD) vol-
umes, or standard for Magnetic volumes.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
• NextToken (string) – The NextToken value returned from a previous pagi-
nated DescribeVolumes request where MaxResults was used and the re-
sults exceeded the value of that parameter. Pagination continues from the end
of the previous results that returned the NextToken value. This value is null
when there are no more results to return.
• MaxResults (integer) – The maximum number of volume results returned
by DescribeVolumes in paginated output. When this parameter is used,
DescribeVolumes only returns MaxResults results in a single page along
with a NextToken response element. The remaining results of the initial
request can be seen by sending another DescribeVolumes request with
the returned NextToken value. This value can be between 5 and 1000; if
MaxResults is given a value larger than 1000, only 1000 results are returned.
If this parameter is not used, then DescribeVolumes returns all results. You
cannot specify this parameter and the volume IDs parameter in the same request.
Returns None
class EC2.Waiter.VpcAvailable
waiter = client.get_waiter('vpc_available')
wait(**kwargs)
Polls EC2.Client.describe_vpcs() every 15 seconds until a successful state is reached. An error
is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
VpcIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
3.1. Services 1527
Boto3 Documentation, Release 1.1.4
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcIds (list) – One or more VPC IDs.
Default: Describes all your VPCs.
– (string) –
• Filters (list) – One or more filters.
– cidr - The CIDR block of the VPC. The CIDR block you specify must
exactly match the VPC’s CIDR block for information to be returned for the
VPC. Must contain the slash followed by one or two digits (for example,
/28 ).
– dhcp-options-id - The ID of a set of DHCP options.
– isDefault - Indicates whether the VPC is the default VPC.
– state - The state of the VPC (pending | available ).
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– vpc-id - The ID of the VPC.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Returns None
class EC2.Waiter.VpnConnectionAvailable
waiter = client.get_waiter('vpn_connection_available')
wait(**kwargs)
Polls EC2.Client.describe_vpn_connections() every 15 seconds until a successful state is
reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
VpnConnectionIds=[
1528 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpnConnectionIds (list) – One or more VPN connection IDs.
Default: Describes your VPN connections.
– (string) –
• Filters (list) – One or more filters.
– customer-gateway-configuration - The configuration infor-
mation for the customer gateway.
– customer-gateway-id - The ID of a customer gateway associated
with the VPN connection.
– state - The state of the VPN connection (pending | available |
deleting | deleted ).
– option.static-routes-only - Indicates whether the connection
has static routes only. Used for devices that do not support Border Gate-
way Protocol (BGP).
– route.destination-cidr-block - The destination CIDR block.
This corresponds to the subnet used in a customer data center.
– bgp-asn - The BGP Autonomous System Number (ASN) associated
with a BGP device.
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– type - The type of VPN connection. Currently the only supported type is
ipsec.1 .
– vpn-connection-id - The ID of the VPN connection.
– vpn-gateway-id - The ID of a virtual private gateway associated with
the VPN connection.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
3.1. Services 1529
Boto3 Documentation, Release 1.1.4
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Returns None
class EC2.Waiter.VpnConnectionDeleted
waiter = client.get_waiter('vpn_connection_deleted')
wait(**kwargs)
Polls EC2.Client.describe_vpn_connections() every 15 seconds until a successful state is
reached. An error is returned after 40 failed checks.
Request Syntax
waiter.wait(
DryRun=True|False,
VpnConnectionIds=[
'string',
],
Filters=[
{
'Name': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpnConnectionIds (list) – One or more VPN connection IDs.
Default: Describes your VPN connections.
– (string) –
• Filters (list) – One or more filters.
– customer-gateway-configuration - The configuration infor-
mation for the customer gateway.
– customer-gateway-id - The ID of a customer gateway associated
with the VPN connection.
– state - The state of the VPN connection (pending | available |
deleting | deleted ).
– option.static-routes-only - Indicates whether the connection
has static routes only. Used for devices that do not support Border Gate-
way Protocol (BGP).
– route.destination-cidr-block - The destination CIDR block.
This corresponds to the subnet used in a customer data center.
– bgp-asn - The BGP Autonomous System Number (ASN) associated
with a BGP device.
1530 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
– tag :key =*value* - The key/value combination of a tag assigned to the
resource.
– tag-key - The key of a tag assigned to the resource. This filter is inde-
pendent of the tag-value filter. For example, if you use both the filter
“tag-key=Purpose” and the filter “tag-value=X”, you get any resources as-
signed both the tag key Purpose (regardless of what the tag’s value is), and
the tag value X (regardless of what the tag’s key is). If you want to list
only resources where Purpose is X, see the tag :key =*value* filter.
– tag-value - The value of a tag assigned to the resource. This filter is
independent of the tag-key filter.
– type - The type of VPN connection. Currently the only supported type is
ipsec.1 .
– vpn-connection-id - The ID of the VPN connection.
– vpn-gateway-id - The ID of a virtual private gateway associated with
the VPN connection.
– (dict) –
A filter name and value pair that is used to return a more specific list of
results. Filters can be used to match a set of resources by various criteria,
such as tags, attributes, or IDs.
* Name (string) –
The name of the filter. Filter names are case-sensitive.
* Values (list) –
One or more filter values. Filter values are case-sensitive.
· (string) –
Returns None
Service Resource
class EC2.ServiceResource
A resource representing Amazon Elastic Compute Cloud (EC2):
import boto3
ec2 = boto3.resource('ec2')
These are the resource’s available actions:
•create_dhcp_options()
•create_instances()
•create_internet_gateway()
•create_key_pair()
•create_network_acl()
•create_network_interface()
•create_placement_group()
•create_route_table()
•create_security_group()
•create_snapshot()
•create_subnet()
•create_tags()
•create_volume()
•create_vpc()
•create_vpc_peering_connection()
3.1. Services 1531
Boto3 Documentation, Release 1.1.4
•disassociate_route_table()
•import_key_pair()
•register_image()
These are the resource’s available sub-resources:
•DhcpOptions()
•Image()
•Instance()
•InternetGateway()
•KeyPair()
•NetworkAcl()
•NetworkInterface()
•PlacementGroup()
•RouteTable()
•RouteTableAssociation()
•SecurityGroup()
•Snapshot()
•Subnet()
•Tag()
•Volume()
•Vpc()
•VpcPeeringConnection()
These are the resource’s available collections:
•dhcp_options_sets
•images
•instances
•internet_gateways
•key_pairs
•network_acls
•network_interfaces
•placement_groups
•route_tables
•security_groups
•snapshots
•subnets
•volumes
•vpc_peering_connections
•vpcs
Actions
Actions call operations on resources. They may automatically handle the passing in of arguments set from
identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.
create_dhcp_options(**kwargs)
Creates a set of DHCP options for your VPC. After creating the set, you must associate it with the VPC,
causing all existing and new instances that you launch in the VPC to use this set of DHCP options. The
following are the individual DHCP options you can specify. For more information about the options, see
RFC 2132 .
•domain-name-servers - The IP addresses of up to four domain name servers, or
AmazonProvidedDNS . The default DHCP option set specifies AmazonProvidedDNS . If
specifying more than one domain name server, specify the IP addresses in a single parameter, sep-
arated by commas.
•domain-name - If you’re using AmazonProvidedDNS in us-east-1 , specify
ec2.internal . If you’re using AmazonProvidedDNS in another region, specify
region.compute.internal (for example, ap-northeast-1.compute.internal ).
Otherwise, specify a domain name (for example, MyCompany.com ). Important : Some Linux
1532 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
operating systems accept multiple domain names separated by spaces. However, Windows and
other Linux operating systems treat the value as a single domain, which results in unexpected
behavior. If your DHCP options set is associated with a VPC that has instances with multiple
operating systems, specify only one domain name.
•ntp-servers - The IP addresses of up to four Network Time Protocol (NTP) servers.
•netbios-name-servers - The IP addresses of up to four NetBIOS name servers.
•netbios-node-type - The NetBIOS node type (1, 2, 4, or 8). We recommend that you specify
2 (broadcast and multicast are not currently supported). For more information about these node
types, see RFC 2132 .
Your VPC automatically starts out with a set of DHCP options that includes only a DNS server that we
provide (AmazonProvidedDNS). If you create a set of options, and if your VPC has an Internet gateway,
make sure to set the domain-name-servers option either to AmazonProvidedDNS or to a domain
name server of your choice. For more information about DHCP options, see DHCP Options Sets in the
Amazon Virtual Private Cloud User Guide .
Request Syntax
dhcp_options = ec2.create_dhcp_options(
DryRun=True|False,
DhcpConfigurations=[
{
'Key': 'string',
'Values': [
'string',
]
},
]
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• DhcpConfigurations (list) – [REQUIRED]
A DHCP configuration option.
– (dict) –
* Key (string) –
* Values (list) –
· (string) –
Return type ec2.DhcpOptions
Returns DhcpOptions resource
create_instances(**kwargs)
Launches the specified number of instances using an AMI for which you have permissions.
When you launch an instance, it enters the pending state. After the instance is ready for you, it enters
the running state. To check the state of your instance, call DescribeInstances .
If you don’t specify a security group when launching an instance, Amazon EC2 uses the default security
group. For more information, see Security Groups in the Amazon Elastic Compute Cloud User Guide .
[EC2-VPC only accounts] If you don’t specify a subnet in the request, we choose a default subnet from
your default VPC for you.
[EC2-Classic accounts] If you’re launching into EC2-Classic and you don’t specify an Availability Zone,
we choose one for you.
3.1. Services 1533
Boto3 Documentation, Release 1.1.4
Linux instances have access to the public key of the key pair at boot. You can use this key to provide
secure access to the instance. Amazon EC2 public images use this feature to provide secure access
without passwords. For more information, see Key Pairs in the Amazon Elastic Compute Cloud User
Guide .
You can provide optional user data when launching an instance. For more information, see Instance
Metadata in the Amazon Elastic Compute Cloud User Guide .
If any of the AMIs have a product code attached for which the user has not subscribed, RunInstances
fails.
T2 instance types can only be launched into a VPC. If you do not have a default VPC, or if you do not
specify a subnet ID in the request, RunInstances fails.
For more information about troubleshooting, see What To Do If An Instance Immediately Terminates ,
and Troubleshooting Connecting to Your Instance in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
instance = ec2.create_instances(
DryRun=True|False,
ImageId='string',
MinCount=123,
MaxCount=123,
KeyName='string',
SecurityGroups=[
'string',
],
SecurityGroupIds=[
'string',
],
UserData='string',
InstanceType='t1.micro'|'m1.small'|'m1.medium'|'m1.large'|'m1.xlarge'|'m3.medium'|'m3.la
Placement={
'AvailabilityZone': 'string',
'GroupName': 'string',
'Tenancy': 'default'|'dedicated'
},
KernelId='string',
RamdiskId='string',
BlockDeviceMappings=[
{
'VirtualName': 'string',
'DeviceName': 'string',
'Ebs': {
'SnapshotId': 'string',
'VolumeSize': 123,
'DeleteOnTermination': True|False,
'VolumeType': 'standard'|'io1'|'gp2',
'Iops': 123,
'Encrypted': True|False
},
'NoDevice': 'string'
},
],
Monitoring={
'Enabled': True|False
},
SubnetId='string',
1534 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
DisableApiTermination=True|False,
InstanceInitiatedShutdownBehavior='stop'|'terminate',
PrivateIpAddress='string',
ClientToken='string',
AdditionalInfo='string',
NetworkInterfaces=[
{
'NetworkInterfaceId': 'string',
'DeviceIndex': 123,
'SubnetId': 'string',
'Description': 'string',
'PrivateIpAddress': 'string',
'Groups': [
'string',
],
'DeleteOnTermination': True|False,
'PrivateIpAddresses': [
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
'SecondaryPrivateIpAddressCount': 123,
'AssociatePublicIpAddress': True|False
},
],
IamInstanceProfile={
'Arn': 'string',
'Name': 'string'
},
EbsOptimized=True|False
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• ImageId (string) – [REQUIRED]
The ID of the AMI, which you can get by calling DescribeImages .
• MinCount (integer) – [REQUIRED]
The minimum number of instances to launch. If you specify a minimum that
is more instances than Amazon EC2 can launch in the target Availability Zone,
Amazon EC2 launches no instances.
Constraints: Between 1 and the maximum number you’re allowed for the spec-
ified instance type. For more information about the default limits, and how to
request an increase, see How many instances can I run in Amazon EC2 in the
Amazon EC2 General FAQ.
• MaxCount (integer) – [REQUIRED]
The maximum number of instances to launch. If you specify more instances than
Amazon EC2 can launch in the target Availability Zone, Amazon EC2 launches
the largest possible number of instances above MinCount .
Constraints: Between 1 and the maximum number you’re allowed for the spec-
ified instance type. For more information about the default limits, and how to
3.1. Services 1535
Boto3 Documentation, Release 1.1.4
request an increase, see How many instances can I run in Amazon EC2 in the
Amazon EC2 General FAQ.
• KeyName (string) – The name of the key pair. You can create a key pair using
CreateKeyPair or ImportKeyPair .
Warning: If you do not specify a key pair, you can’t connect to the instance
unless you choose an AMI that is configured to allow users another way to
log in.
• SecurityGroups (list) – [EC2-Classic, default VPC] One or more security group
names. For a nondefault VPC, you must use security group IDs instead.
Default: Amazon EC2 uses the default security group.
– (string) –
• SecurityGroupIds (list) – One or more security group IDs. You can create a
security group using CreateSecurityGroup .
Default: Amazon EC2 uses the default security group.
– (string) –
• UserData (string) – The Base64-encoded MIME user data for the instances.
This value will be base64 encoded automatically. Do not base64
encode this value prior to performing the operation.
• InstanceType (string) – The instance type. For more information, see Instance
Types in the Amazon Elastic Compute Cloud User Guide .
Default: m1.small
• Placement (dict) – The placement for the instance.
– AvailabilityZone (string) –
The Availability Zone of the instance.
– GroupName (string) –
The name of the placement group the instance is in (for cluster compute
instances).
– Tenancy (string) –
The tenancy of the instance (if the instance is running in a VPC). An in-
stance with a tenancy of dedicated runs on single-tenant hardware.
• KernelId (string) – The ID of the kernel.
Warning: We recommend that you use PV-GRUB instead of kernels and
RAM disks. For more information, see PV-GRUB in the Amazon Elastic
Compute Cloud User Guide .
• RamdiskId (string) – The ID of the RAM disk.
Warning: We recommend that you use PV-GRUB instead of kernels and
RAM disks. For more information, see PV-GRUB in the Amazon Elastic
Compute Cloud User Guide .
• BlockDeviceMappings (list) – The block device mapping.
– (dict) –
Describes a block device mapping.
* VirtualName (string) –
The virtual device name (ephemeral N). Instance store volumes
are numbered starting from 0. An instance type with 2 available in-
stance store volumes can specify mappings for ephemeral0 and
1536 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
ephemeral1 .The number of available instance store volumes de-
pends on the instance type. After you connect to the instance, you
must mount the volume.
Constraints: For M3 instances, you must specify instance store vol-
umes in the block device mapping for the instance. When you
launch an M3 instance, we ignore any instance store volumes spec-
ified in the block device mapping for the AMI.
* DeviceName (string) –
The device name exposed to the instance (for example, /dev/sdh
or xvdh ).
* Ebs (dict) –
Parameters used to automatically set up EBS volumes when the in-
stance is launched.
· SnapshotId (string) –
The ID of the snapshot.
· VolumeSize (integer) –
The size of the volume, in GiB.
Constraints: 1-1024 for standard volumes, 1-16384
for gp2 volumes, and 4-16384 for io1 volumes. If you
specify a snapshot, the volume size must be equal to or larger
than the snapshot size.
Default: If you’re creating the volume from a snapshot and
don’t specify a volume size, the default is the snapshot size.
· DeleteOnTermination (boolean) –
Indicates whether the EBS volume is deleted on instance ter-
mination.
· VolumeType (string) –
The volume type. gp2 for General Purpose (SSD) volumes,
io1 for Provisioned IOPS (SSD) volumes, and standard
for Magnetic volumes.
Default: standard
· Iops (integer) –
The number of I/O operations per second (IOPS) that the vol-
ume supports. For Provisioned IOPS (SSD) volumes, this
represents the number of IOPS that are provisioned for the
volume. For General Purpose (SSD) volumes, this represents
the baseline performance of the volume and the rate at which
the volume accumulates I/O credits for bursting. For more in-
formation on General Purpose (SSD) baseline performance,
I/O credits, and bursting, see Amazon EBS Volume Types in
the Amazon Elastic Compute Cloud User Guide .
Constraint: Range is 100 to 20000 for Provisioned IOPS
(SSD) volumes and 3 to 10000 for General Purpose (SSD)
volumes.
Condition: This parameter is required for requests to create
io1 volumes; it is not used in requests to create standard
or gp2 volumes.
3.1. Services 1537
Boto3 Documentation, Release 1.1.4
· Encrypted (boolean) –
Indicates whether the EBS volume is encrypted. Encrypted
Amazon EBS volumes may only be attached to instances that
support Amazon EBS encryption.
* NoDevice (string) –
Suppresses the specified device included in the block device map-
ping of the AMI.
• Monitoring (dict) – The monitoring for the instance.
– Enabled (boolean) – [REQUIRED]
Indicates whether monitoring is enabled for the instance.
• SubnetId (string) – [EC2-VPC] The ID of the subnet to launch the instance into.
• DisableApiTermination (boolean) – If you set this parameter to true
, you can’t terminate the instance using the Amazon EC2 console,
CLI, or API; otherwise, you can. If you set this parameter to
true and then later want to be able to terminate the instance, you
must first change the value of the disableApiTermination attribute
to false using ModifyInstanceAttribute . Alternatively, if you set
InstanceInitiatedShutdownBehavior to terminate , you can ter-
minate the instance by running the shutdown command from the instance.
Default: false
• InstanceInitiatedShutdownBehavior (string) – Indicates whether an instance
stops or terminates when you initiate shutdown from the instance (using the op-
erating system command for system shutdown).
Default: stop
• PrivateIpAddress (string) – [EC2-VPC] The primary IP address. You must
specify a value from the IP address range of the subnet.
Only one private IP address can be designated as primary. Therefore, you
can’t specify this parameter if PrivateIpAddresses.n.Primary is set
to true and PrivateIpAddresses.n.PrivateIpAddress is set to an
IP address.
Default: We select an IP address from the IP address range of the subnet.
• ClientToken (string) – Unique, case-sensitive identifier you provide to ensure
the idempotency of the request. For more information, see Ensuring Idempo-
tency .
Constraints: Maximum 64 ASCII characters
• AdditionalInfo (string) – Reserved.
• NetworkInterfaces (list) – One or more network interfaces.
– (dict) –
Describes a network interface.
* NetworkInterfaceId (string) –
The ID of the network interface.
* DeviceIndex (integer) –
The index of the device on the instance for the network interface
attachment. If you are specifying a network interface in a RunIn-
stances request, you must provide the device index.
* SubnetId (string) –
The ID of the subnet associated with the network string. Applies
only if creating a network interface when launching an instance.
1538 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
* Description (string) –
The description of the network interface. Applies only if creating a
network interface when launching an instance.
* PrivateIpAddress (string) –
The private IP address of the network interface. Applies only if
creating a network interface when launching an instance.
* Groups (list) –
The IDs of the security groups for the network interface. Applies
only if creating a network interface when launching an instance.
· (string) –
* DeleteOnTermination (boolean) –
If set to true , the interface is deleted when the instance is ter-
minated. You can specify true only if creating a new network
interface when launching an instance.
* PrivateIpAddresses (list) –
One or more private IP addresses to assign to the network interface.
Only one private IP address can be designated as primary.
· (dict) –
Describes a secondary private IP address for a network inter-
face.
· PrivateIpAddress (string) – [REQUIRED]
The private IP addresses.
· Primary (boolean) –
Indicates whether the private IP address is the primary private
IP address. Only one IP address can be designated as primary.
* SecondaryPrivateIpAddressCount (integer) –
The number of secondary private IP addresses. You can’t specify
this option and specify more than one private IP address using the
private IP addresses option.
* AssociatePublicIpAddress (boolean) –
Indicates whether to assign a public IP address to an instance you
launch in a VPC. The public IP address can only be assigned to
a network interface for eth0, and can only be assigned to a new
network interface, not an existing one. You cannot specify more
than one network interface in the request. If launching into a default
subnet, the default value is true .
• IamInstanceProfile (dict) – The IAM instance profile.
– Arn (string) –
The Amazon Resource Name (ARN) of the instance profile.
– Name (string) –
The name of the instance profile.
• EbsOptimized (boolean) – Indicates whether the instance is optimized for EBS
I/O. This optimization provides dedicated throughput to Amazon EBS and an
optimized configuration stack to provide optimal EBS I/O performance. This
optimization isn’t available with all instance types. Additional usage charges
apply when using an EBS-optimized instance.
Default: false
3.1. Services 1539
Boto3 Documentation, Release 1.1.4
Return type list(ec2.Instance)
Returns A list of Instance resources
create_internet_gateway(**kwargs)
Creates an Internet gateway for use with a VPC. After creating the Internet gateway, you attach it to a
VPC using AttachInternetGateway .
For more information about your VPC and Internet gateway, see the Amazon Virtual Private Cloud User
Guide .
Request Syntax
internet_gateway = ec2.create_internet_gateway(
DryRun=True|False
)
Parameters DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If you have
the required permissions, the error response is DryRunOperation . Otherwise, it is
UnauthorizedOperation .
Return type ec2.InternetGateway
Returns InternetGateway resource
create_key_pair(**kwargs)
Creates a 2048-bit RSA key pair with the specified name. Amazon EC2 stores the public key and displays
the private key for you to save to a file. The private key is returned as an unencrypted PEM encoded
PKCS#8 private key. If a key with the specified name already exists, Amazon EC2 returns an error.
You can have up to five thousand key pairs per region.
The key pair returned to you is available only in the region in which you create it. To create a key pair
that is available in all regions, use ImportKeyPair .
For more information about key pairs, see Key Pairs in the Amazon Elastic Compute Cloud User Guide .
Request Syntax
key_pair = ec2.create_key_pair(
DryRun=True|False,
KeyName='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• KeyName (string) – [REQUIRED]
A unique name for the key pair.
Constraints: Up to 255 ASCII characters
Return type ec2.KeyPair
Returns KeyPair resource
create_network_acl(**kwargs)
Creates a network ACL in a VPC. Network ACLs provide an optional layer of security (in addition to
security groups) for the instances in your VPC.
For more information about network ACLs, see Network ACLs in the Amazon Virtual Private Cloud User
Guide .
1540 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
network_acl = ec2.create_network_acl(
DryRun=True|False,
VpcId='string'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• VpcId (string) – [REQUIRED]
The ID of the VPC.
Return type ec2.NetworkAcl
Returns NetworkAcl resource
create_network_interface(**kwargs)
Creates a network interface in the specified subnet.
For more information about network interfaces, see Elastic Network Interfaces in the Amazon Elastic
Compute Cloud User Guide .
Request Syntax
network_interface = ec2.create_network_interface(
SubnetId='string',
Description='string',
PrivateIpAddress='string',
Groups=[
'string',
],
PrivateIpAddresses=[
{
'PrivateIpAddress': 'string',
'Primary': True|False
},
],
SecondaryPrivateIpAddressCount=123,
DryRun=True|False
)
Parameters
• SubnetId (string) – [REQUIRED]
The ID of the subnet to associate with the network interface.
• Description (string) – A description for the network interface.
• PrivateIpAddress (string) – The primary private IP address of the network in-
terface. If you don’t specify an IP address, Amazon EC2 selects one for you from
the subnet range. If you specify an IP address, you cannot indicate any IP ad-
dresses specified in privateIpAddresses as primary (only one IP address
can be designated as primary).
• Groups (list) – The IDs of one or more security groups.
– (string) –
• PrivateIpAddresses (list) – One or more private IP addresses.
– (dict) –
Describes a secondary private IP address for a network interface.
3.1. Services 1541
Boto3 Documentation, Release 1.1.4
* PrivateIpAddress (string) – [REQUIRED]
The private IP addresses.
* Primary (boolean) –
Indicates whether the private IP address is the primary private IP
address. Only one IP address can be designated as primary.
• SecondaryPrivateIpAddressCount (integer) – The number of secondary pri-
vate IP addresses to assign to a network interface. When you specify a number
of secondary IP addresses, Amazon EC2 selects these IP addresses within the
subnet range. You can’t specify this option and specify more than one private IP
address using privateIpAddresses .
The number of IP addresses you can assign to a network interface varies by
instance type. For more information, see Private IP Addresses Per ENI Per In-
stance Type in the Amazon Elastic Compute Cloud User Guide .
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
Return type ec2.NetworkInterface
Returns NetworkInterface resource
create_placement_group(**kwargs)
Creates a placement group that you launch cluster instances into. You must give the group a name that’s
unique within the scope of your account.
For more information about placement groups and cluster instances, see Cluster Instances in the Amazon
Elastic Compute Cloud User Guide .
Request Syntax
placement_group = ec2.create_placement_group(
DryRun=True|False,
GroupName='string',
Strategy='cluster'
)
Parameters
• DryRun (boolean) – Checks whether you have the required permissions for the
action, without actually making the request, and provides an error response. If
you have the required permissions, the error response is DryRunOperation .
Otherwise, it is UnauthorizedOperation .
• GroupName (string) – [REQUIRED]
A name for the placement group.
Constraints: Up to 255 ASCII characters
• Strategy (string) – [REQUIRED]
The placement strategy.
Return type ec2.PlacementGroup
Returns PlacementGroup resource
create_route_table(**kwargs)
Creates a route table for the specified VPC. After you create a route table, you can add routes and associate
the table with a subnet.
For more information about route tables, see Route Tables in the Amazon Virtual Private Cloud User
Guide .
1542 Chapter 3. API Reference
Boto3 Documentation, Release 1.1.4
Request Syntax
route_table = ec2.create_route_table(
You might also like
- How To Use Llama 2 With An API On AWS To Power Your AI AppsNo ratings yetHow To Use Llama 2 With An API On AWS To Power Your AI Apps21 pages
- Bots EDI Translator Documentation: Release 3.2.0No ratings yetBots EDI Translator Documentation: Release 3.2.0166 pages
- Getting Started with AWS Lambda and the serverless cloudNo ratings yetGetting Started with AWS Lambda and the serverless cloud25 pages
- Spring Boot Intermediate Microservices: Resilient Microservices with Spring Boot 2 and Spring CloudFrom EverandSpring Boot Intermediate Microservices: Resilient Microservices with Spring Boot 2 and Spring CloudNo ratings yet
- Introduction to Python Programming: Do your first steps into programming with pythonFrom EverandIntroduction to Python Programming: Do your first steps into programming with pythonNo ratings yet
- AWS+Lambda+Full+Course Final 24+Oct 2023 (1)No ratings yetAWS+Lambda+Full+Course Final 24+Oct 2023 (1)163 pages
- Mastering Node.js Web Development: Go on a comprehensive journey from the fundamentals to advanced web development with Node.jsFrom EverandMastering Node.js Web Development: Go on a comprehensive journey from the fundamentals to advanced web development with Node.jsNo ratings yet
- Cisco APIC 3-2 With VMware v1 Network Admin Demo GuideNo ratings yetCisco APIC 3-2 With VMware v1 Network Admin Demo Guide42 pages
- Inter: iRMX® System Debugger Reference ManualNo ratings yetInter: iRMX® System Debugger Reference Manual148 pages
- DIR (Directory) - Displays A List of Files and Subdirectories in A DirectoryNo ratings yetDIR (Directory) - Displays A List of Files and Subdirectories in A Directory5 pages
- Atollic TrueSTUDIO For STMicroelectronics STM32 QuickstartGuideNo ratings yetAtollic TrueSTUDIO For STMicroelectronics STM32 QuickstartGuide124 pages
- IManager U2000 Unified Network ManagemenNo ratings yetIManager U2000 Unified Network Managemen260 pages
- LG - Touch Screen User Manual (ENG) - 04.01.06 - 101028No ratings yetLG - Touch Screen User Manual (ENG) - 04.01.06 - 10102838 pages
- Sage Installation Guide: Release 6.6.beta0No ratings yetSage Installation Guide: Release 6.6.beta042 pages
