2026/11/17 - Amazon Kinesis - 12 new 1 updated api methods
Changes Adds support for queues on on-demand streams with new CreateQueue, UpdateQueue, DeleteQueue, DescribeQueue, ListQueues, ReceiveQueueRecords, AcknowledgeQueueRecords, and UpdateQueueRecordsVisibility APIs, plus four dead-letter APIs, for Amazon Kinesis Data Streams.
Receives up to 10 records from the specified queue. Each record is returned with a receipt handle, which is the identifier you use to acknowledge the record or change its visibility.
A record returned by ReceiveQueueRecords becomes in flight: it is not visible to any consumer instance for the duration of its visibility timeout, so subsequent receive requests do not return it while your queue consumer processes it. Acknowledge the record with AcknowledgeQueueRecords when you finish processing it. A record that is not acknowledged before its visibility timeout expires becomes visible in the queue again and can be received by any consumer instance.
Use WaitTimeSeconds to control how long the call waits for a record to become visible before returning. If a record becomes visible sooner, the call returns sooner. If the wait time expires and no records are visible, the call returns an empty list of records.
Records are not necessarily received in the order they were written to the data stream.
A queue delivers records while it is in the ACTIVE state.
On rare occasions, a queue can deliver a record more than once. Design your queue consumer to be idempotent, so that processing the same record more than once is safe.
See also: AWS API Documentation
Request Syntax
client.receive_queue_records(
QueueARN='string',
Limit=123,
WaitTimeSeconds=123,
VisibilityTimeoutSeconds=123
)
string
[REQUIRED]
The ARN of the queue to receive records from.
integer
The maximum number of records to return. The queue never returns more records than this value, and might return fewer. The default is 10.
integer
The duration, in seconds, that the call waits for a record to become visible before returning. The default is 9.
integer
The duration, in seconds, that the records returned by this request are in flight and not visible to any consumer instance. If you do not specify this value, the queue's visibility timeout is used.
dict
Response Syntax
{
'QueueRecords': [
{
'ReceiptHandle': 'string',
'RecordId': 'string',
'PartitionKey': 'string',
'Data': b'bytes',
'ApproximateArrivalTimestamp': datetime(2015, 1, 1),
'FirstReceiveTimestamp': datetime(2015, 1, 1),
'ReceiveCount': 123
},
]
}
Response Structure
(dict) --
QueueRecords (list) --
The records received from the queue. This list is empty when no records are visible.
(dict) --
A data stream record, as delivered through a queue.
ReceiptHandle (string) --
The identifier you use to acknowledge this record, change its visibility, or restore it after it becomes a dead-letter record. A new receipt handle is issued each time the record is received.
RecordId (string) --
The unique identifier of the record. This value stays the same across every delivery of the record, and it is the same in every queue on the stream that delivers the record. To identify a single delivery, use ReceiptHandle instead.
PartitionKey (string) --
The partition key the record was written to the data stream with.
Data (bytes) --
The data blob of the record. Amazon Kinesis Data Streams does not inspect, interpret, or change the data.
ApproximateArrivalTimestamp (datetime) --
The approximate time the record arrived in the data stream. The difference between this value and the current time is how long the record took to reach your queue consumer.
FirstReceiveTimestamp (datetime) --
The approximate time the record was first received from the queue.
ReceiveCount (integer) --
The number of times this record has been received without being acknowledged.
Creates a queue on the specified data stream. A queue delivers records from the stream to a queue consumer, tracks the delivery state of each record, and redelivers any record that is not acknowledged before its visibility timeout expires.
A queue does not extend how long the stream keeps a record. When a record reaches the end of the data stream's retention period, the queue stops delivering it.
Your queue consumer calls ReceiveQueueRecords to receive up to 10 records at a time. After it processes records, it calls AcknowledgeQueueRecords so the queue does not deliver them again.
Queues are supported only on data streams in on-demand capacity mode.
Creating a queue does not change how producers write to the stream, and it does not change how existing stream consumers read from it. A queue counts as a registered consumer on the stream and shares the stream's registered consumer limit with enhanced fan-out consumers: 20 on On-demand Standard and 50 on On-demand Advantage.
Use StartingPosition to set the position in the stream where delivery begins. The default is LATEST.
CreateQueue is an asynchronous operation. Upon receiving a CreateQueue request, Amazon Kinesis Data Streams immediately returns a queue description with a QueueStatus of CREATING. After the queue is created, Kinesis Data Streams sets the QueueStatus to ACTIVE. You can begin receiving records after the queue is ACTIVE. Use DescribeQueue to check the status of the queue.
Each queue has built-in dead-letter handling. When a record has been received MaxReceiveCount times without being acknowledged, it becomes a dead-letter record, and ReceiveQueueRecords no longer returns it. You work with dead-letter records through a separate set of operations that use the same queue ARN: ReceiveDeadLetterQueueRecords, AcknowledgeDeadLetterQueueRecords, UpdateDeadLetterQueueRecordsVisibility, and RestoreDeadLetterQueueRecords.
Dead-letter handling is enabled by default, with a MaxReceiveCount of 6. To use a different value, or to turn dead-letter handling off, specify DeadLetterConfiguration in QueueAttributes.
See also: AWS API Documentation
Request Syntax
client.create_queue(
QueueName='string',
StreamConfigurationList=[
{
'StreamARN': 'string',
'StartingPosition': {
'Type': 'TRIM_HORIZON'|'LATEST'|'AT_TIMESTAMP',
'Timestamp': datetime(2015, 1, 1)
}
},
],
QueueAttributes={
'VisibilityTimeoutSeconds': 123,
'DeadLetterConfiguration': {
'TargetType': 'BUILT_IN'|'NONE',
'MaxReceiveCount': 123
}
},
Tags={
'string': 'string'
}
)
string
[REQUIRED]
A name for the queue. The name is scoped to the Amazon Web Services account and Region used by the request, so two queues in different accounts, or in the same account and different Regions, can have the same name.
list
[REQUIRED]
The data stream the queue delivers records from, and the position in that stream where delivery begins. The list must contain exactly one entry, because a queue delivers records from a single data stream.
(dict) --
The data stream a queue delivers records from, and the position in that stream where delivery begins.
StreamARN (string) -- [REQUIRED]
The ARN of the data stream.
StartingPosition (dict) --
The position in the stream from which the queue begins delivering records. The default is LATEST.
Type (string) -- [REQUIRED]
You can set the starting position to one of the following values:
LATEST: Delivers records that arrive after you create the queue. This is the default.
TRIM_HORIZON: Start delivering at the last untrimmed record in the stream, which is the oldest record the stream still retains.
AT_TIMESTAMP: Delivers records that arrive at or after a time stamp that you provide.
Timestamp (datetime) --
The approximate time from which the queue begins delivering records. Records that arrive at approximately this time or later are delivered.
In a request, specify this value only when Type is AT_TIMESTAMP. It is required in that case, and specifying it for any other type returns a ValidationException.
In a response, this value is approximate and reflects the queue's effective starting position. While the queue is CREATING, the response echoes what you configured: for AT_TIMESTAMP, the timestamp you provided, and for TRIM_HORIZON and LATEST, this member is absent because the effective position is not yet determined. Once the queue is ACTIVE, the response always includes this member. For AT_TIMESTAMP, it is the timestamp you provided or the earliest time the stream can be read from, whichever is later.
dict
The configuration attributes for the queue, including its visibility timeout and its dead-letter handling configuration.
VisibilityTimeoutSeconds (integer) --
The duration, in seconds, that a record is in flight and not visible to any consumer instance after it is received. A record that is not acknowledged before this duration elapses becomes visible in the queue again and can be received by any consumer instance. If you omit this attribute when you create a queue, the queue uses 30 seconds.
DeadLetterConfiguration (dict) --
The dead-letter handling configuration for the queue. If you omit this attribute, dead-letter handling is enabled with a MaxReceiveCount of 6. If you specify it with a TargetType of BUILT_IN, you must also specify MaxReceiveCount.
TargetType (string) -- [REQUIRED]
Whether dead-letter handling is enabled for the queue. BUILT_IN enables it: when a record has been received MaxReceiveCount times without being acknowledged, it becomes a dead-letter record and ReceiveQueueRecords no longer returns it. NONE disables it, and an unacknowledged record continues to be redelivered until it is acknowledged or its retention period ends.
MaxReceiveCount (integer) --
The number of times a record can be received without being acknowledged before it becomes a dead-letter record. Required when TargetType is BUILT_IN. A queue that you create without DeadLetterConfiguration gets a MaxReceiveCount of 6.
dict
A set of up to 50 key-value pairs to apply to the queue. You can also add, change, and remove tags after the queue is created with TagResource and UntagResource.
(string) --
(string) --
dict
Response Syntax
{
'QueueDescription': {
'QueueName': 'string',
'QueueARN': 'string',
'QueueStatus': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING',
'QueueCreationTimestamp': datetime(2015, 1, 1),
'StreamConfigurationList': [
{
'StreamARN': 'string',
'StartingPosition': {
'Type': 'TRIM_HORIZON'|'LATEST'|'AT_TIMESTAMP',
'Timestamp': datetime(2015, 1, 1)
}
},
],
'QueueAttributes': {
'VisibilityTimeoutSeconds': 123,
'DeadLetterConfiguration': {
'TargetType': 'BUILT_IN'|'NONE',
'MaxReceiveCount': 123
}
}
}
}
Response Structure
(dict) --
QueueDescription (dict) --
A description of the queue that was created.
QueueName (string) --
The name of the queue.
QueueARN (string) --
The ARN of the queue. The resource identifier in the ARN is generated when the queue is created and is not derived from QueueName. Use the returned QueueARN to identify the queue in subsequent requests.
QueueStatus (string) --
The current status of the queue.
QueueCreationTimestamp (datetime) --
The time the queue was created.
StreamConfigurationList (list) --
The data stream the queue delivers records from, and the position in that stream where delivery begins. The list contains exactly one entry, because a queue delivers records from a single data stream.
(dict) --
The data stream a queue delivers records from, and the position in that stream where delivery begins.
StreamARN (string) --
The ARN of the data stream.
StartingPosition (dict) --
The position in the stream from which the queue begins delivering records. The default is LATEST.
Type (string) --
You can set the starting position to one of the following values:
LATEST: Delivers records that arrive after you create the queue. This is the default.
TRIM_HORIZON: Start delivering at the last untrimmed record in the stream, which is the oldest record the stream still retains.
AT_TIMESTAMP: Delivers records that arrive at or after a time stamp that you provide.
Timestamp (datetime) --
The approximate time from which the queue begins delivering records. Records that arrive at approximately this time or later are delivered.
In a request, specify this value only when Type is AT_TIMESTAMP. It is required in that case, and specifying it for any other type returns a ValidationException.
In a response, this value is approximate and reflects the queue's effective starting position. While the queue is CREATING, the response echoes what you configured: for AT_TIMESTAMP, the timestamp you provided, and for TRIM_HORIZON and LATEST, this member is absent because the effective position is not yet determined. Once the queue is ACTIVE, the response always includes this member. For AT_TIMESTAMP, it is the timestamp you provided or the earliest time the stream can be read from, whichever is later.
QueueAttributes (dict) --
The configuration attributes of the queue.
VisibilityTimeoutSeconds (integer) --
The duration, in seconds, that a record is in flight and not visible to any consumer instance after it is received. A record that is not acknowledged before this duration elapses becomes visible in the queue again and can be received by any consumer instance. If you omit this attribute when you create a queue, the queue uses 30 seconds.
DeadLetterConfiguration (dict) --
The dead-letter handling configuration for the queue. If you omit this attribute, dead-letter handling is enabled with a MaxReceiveCount of 6. If you specify it with a TargetType of BUILT_IN, you must also specify MaxReceiveCount.
TargetType (string) --
Whether dead-letter handling is enabled for the queue. BUILT_IN enables it: when a record has been received MaxReceiveCount times without being acknowledged, it becomes a dead-letter record and ReceiveQueueRecords no longer returns it. NONE disables it, and an unacknowledged record continues to be redelivered until it is acknowledged or its retention period ends.
MaxReceiveCount (integer) --
The number of times a record can be received without being acknowledged before it becomes a dead-letter record. Required when TargetType is BUILT_IN. A queue that you create without DeadLetterConfiguration gets a MaxReceiveCount of 6.
Acknowledges up to 10 dead-letter records in the specified queue, so the queue doesn't return them again. The result for each entry is reported individually in the response.
Acknowledging a record does not affect the record in the data stream. That record remains available to stream consumers and to other queues on the same stream for the rest of its retention period.
Because the request can result in a combination of successful and unsuccessful entries, check the Failed list even when the call returns an HTTP status code of 200.
See also: AWS API Documentation
Request Syntax
client.acknowledge_dead_letter_queue_records(
QueueARN='string',
Entries=[
{
'ReceiptHandle': 'string'
},
]
)
string
[REQUIRED]
The ARN of the queue whose dead-letter records are acknowledged.
list
[REQUIRED]
The dead-letter records to acknowledge, identified by their receipt handles.
(dict) --
A dead-letter record to acknowledge, identified by its receipt handle.
ReceiptHandle (string) -- [REQUIRED]
The receipt handle of the record to acknowledge, as returned by ReceiveDeadLetterQueueRecords.
dict
Response Syntax
{
'Successful': [
{
'ReceiptHandle': 'string'
},
],
'Failed': [
{
'ReceiptHandle': 'string',
'ErrorCode': 'string',
'ErrorMessage': 'string'
},
]
}
Response Structure
(dict) --
Successful (list) --
The records that were acknowledged.
(dict) --
A dead-letter record that was acknowledged.
ReceiptHandle (string) --
The receipt handle of the record that was acknowledged.
Failed (list) --
The records that were not acknowledged, each with the reason the entry failed.
(dict) --
A dead-letter record that was not acknowledged, and why.
ReceiptHandle (string) --
The receipt handle of the record that was not acknowledged.
ErrorCode (string) --
A code identifying the type of failure. One of ResourceNotFoundException, InvalidArgumentException, ThrottlingException, or InternalFailureException.
ErrorMessage (string) --
A description of the cause of the failure.
Changes the visibility timeout of up to 10 dead-letter records that you have received from the specified queue but not yet acknowledged. The result for each entry is reported individually in the response.
Because the request can result in a combination of successful and unsuccessful entries, check the Failed list even when the call returns an HTTP status code of 200.
See also: AWS API Documentation
Request Syntax
client.update_dead_letter_queue_records_visibility(
QueueARN='string',
Entries=[
{
'ReceiptHandle': 'string',
'VisibilityTimeoutSeconds': 123
},
]
)
string
[REQUIRED]
The ARN of the queue whose dead-letter records are updated.
list
[REQUIRED]
The dead-letter records whose visibility timeout is changed, identified by their receipt handles, and the new visibility timeout for each.
(dict) --
A dead-letter record whose visibility timeout is changed, and the new visibility timeout.
ReceiptHandle (string) -- [REQUIRED]
The receipt handle of the record, as returned by ReceiveDeadLetterQueueRecords.
VisibilityTimeoutSeconds (integer) -- [REQUIRED]
The new duration, in seconds, that the record is in flight and not visible to any consumer instance, measured from when this request is processed. Specify 0 to make the record visible immediately.
dict
Response Syntax
{
'Successful': [
{
'ReceiptHandle': 'string'
},
],
'Failed': [
{
'ReceiptHandle': 'string',
'ErrorCode': 'string',
'ErrorMessage': 'string'
},
]
}
Response Structure
(dict) --
Successful (list) --
The records whose visibility timeout was changed.
(dict) --
A dead-letter record whose visibility timeout was changed.
ReceiptHandle (string) --
The receipt handle of the record whose visibility timeout was changed.
Failed (list) --
The records whose visibility timeout was not changed, each with the reason the entry failed.
(dict) --
A dead-letter record whose visibility timeout was not changed, and why.
ReceiptHandle (string) --
The receipt handle of the record whose visibility timeout was not changed.
ErrorCode (string) --
A code identifying the type of failure. One of ResourceNotFoundException, InvalidArgumentException, ThrottlingException, or InternalFailureException.
ErrorMessage (string) --
A description of the cause of the failure.
Restores up to 10 dead-letter records in the specified queue. Restoring a record clears its dead-letter state and resets its receive count, so ReceiveQueueRecords can return it again, up to MaxReceiveCount times before it becomes a dead-letter record again. The result for each entry is reported individually in the response.
Restore records after you have corrected the condition that prevented your queue consumer from processing them.
Because the request can result in a combination of successful and unsuccessful entries, check the Failed list even when the call returns an HTTP status code of 200.
See also: AWS API Documentation
Request Syntax
client.restore_dead_letter_queue_records(
QueueARN='string',
Entries=[
{
'ReceiptHandle': 'string'
},
]
)
string
[REQUIRED]
The ARN of the queue whose dead-letter records are restored.
list
[REQUIRED]
The dead-letter records to restore, identified by their receipt handles.
(dict) --
A dead-letter record to restore, identified by its receipt handle.
ReceiptHandle (string) -- [REQUIRED]
The receipt handle of the record to restore, as returned by ReceiveDeadLetterQueueRecords.
dict
Response Syntax
{
'Successful': [
{
'ReceiptHandle': 'string'
},
],
'Failed': [
{
'ReceiptHandle': 'string',
'ErrorCode': 'string',
'ErrorMessage': 'string'
},
]
}
Response Structure
(dict) --
Successful (list) --
The records that were restored.
(dict) --
A dead-letter record that was restored.
ReceiptHandle (string) --
The receipt handle of the record that was restored.
Failed (list) --
The records that were not restored, each with the reason the entry failed.
(dict) --
A dead-letter record that was not restored, and why.
ReceiptHandle (string) --
The receipt handle of the record that was not restored.
ErrorCode (string) --
A code identifying the type of failure. One of ResourceNotFoundException, InvalidArgumentException, ThrottlingException, or InternalFailureException.
ErrorMessage (string) --
A description of the cause of the failure.
Returns a summary of each queue in the Amazon Web Services account and Region used by the request. Use StreamFilter to list only the queues on a particular data stream.
If the response contains a NextToken, more queues are available. Call ListQueues again with that value to retrieve the next page.
See also: AWS API Documentation
Request Syntax
client.list_queues(
MaxResults=123,
NextToken='string',
StreamFilter=[
{
'StreamARN': 'string',
'StreamCreationTimestamp': datetime(2015, 1, 1)
},
]
)
integer
The maximum number of queue summaries to return in one response. The response might contain fewer summaries than this value, and might contain a NextToken even when it contains fewer.
string
The NextToken returned by a previous ListQueues request. Use it to retrieve the next page of queue summaries.
list
Lists only the queues created on the specified data stream.
(dict) --
Filters the queues returned by ListQueues to those created on a particular data stream.
StreamARN (string) -- [REQUIRED]
The ARN of the data stream to filter on.
StreamCreationTimestamp (datetime) --
The time the data stream was created. Specify this value to distinguish between a deleted stream and a stream that was recreated with the same name.
dict
Response Syntax
{
'QueueSummaries': [
{
'QueueName': 'string',
'QueueARN': 'string',
'QueueStatus': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING',
'QueueCreationTimestamp': datetime(2015, 1, 1),
'Streams': [
{
'StreamARN': 'string',
'StreamCreationTimestamp': datetime(2015, 1, 1)
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
QueueSummaries (list) --
A summary of each queue that matched the request.
(dict) --
A summary of a queue. Returned by ListQueues. To retrieve a queue's configuration attributes, use DescribeQueue.
QueueName (string) --
The name of the queue.
QueueARN (string) --
The ARN of the queue.
QueueStatus (string) --
The current status of the queue.
QueueCreationTimestamp (datetime) --
The time the queue was created.
Streams (list) --
The data stream the queue delivers records from.
(dict) --
Identifies a data stream associated with a queue.
StreamARN (string) --
The ARN of the data stream.
StreamCreationTimestamp (datetime) --
The time the data stream was created.
NextToken (string) --
The token to pass to the next ListQueues request to retrieve the next page of queue summaries. This member is absent when no more queues are available.
Acknowledges up to 10 records from the specified queue. After a record is acknowledged, the queue does not deliver it again. The result for each entry is reported individually in the response.
Acknowledging a record does not affect the record in the data stream. That record remains available to stream consumers and to other queues on the same stream for the rest of its retention period.
Because the request can result in a combination of successful and unsuccessful entries, check the Failed list even when the call returns an HTTP status code of 200.
On rare occasions, you can receive a record again after you acknowledge it. Design your queue consumer to be idempotent, so that processing the same record more than once is safe.
See also: AWS API Documentation
Request Syntax
client.acknowledge_queue_records(
QueueARN='string',
Entries=[
{
'ReceiptHandle': 'string'
},
]
)
string
[REQUIRED]
The ARN of the queue the records were received from.
list
[REQUIRED]
The records to acknowledge, identified by their receipt handles.
(dict) --
A record to acknowledge, identified by its receipt handle.
ReceiptHandle (string) -- [REQUIRED]
The receipt handle of the record to acknowledge, as returned by ReceiveQueueRecords.
dict
Response Syntax
{
'Successful': [
{
'ReceiptHandle': 'string'
},
],
'Failed': [
{
'ReceiptHandle': 'string',
'ErrorCode': 'string',
'ErrorMessage': 'string'
},
]
}
Response Structure
(dict) --
Successful (list) --
The records that were acknowledged.
(dict) --
A record that was acknowledged.
ReceiptHandle (string) --
The receipt handle of the record that was acknowledged.
Failed (list) --
The records that were not acknowledged, each with the reason the entry failed.
(dict) --
A record that was not acknowledged, and why.
ReceiptHandle (string) --
The receipt handle of the record that was not acknowledged.
ErrorCode (string) --
A code identifying the type of failure. One of ResourceNotFoundException, InvalidArgumentException, ThrottlingException, or InternalFailureException.
ErrorMessage (string) --
A description of the cause of the failure.
Updates the configuration attributes of the specified queue. You can change the queue's visibility timeout, its dead-letter handling configuration, or both.
A new visibility timeout applies to records received after the update completes. Records that are already in flight keep the visibility timeout they were received with. To change the visibility timeout of a record that is already in flight, use UpdateQueueRecordsVisibility.
UpdateQueue is an asynchronous operation. Upon receiving an UpdateQueue request, Amazon Kinesis Data Streams sets the QueueStatus to UPDATING, and sets it back to ACTIVE when the update is complete. You can continue to receive and acknowledge records while the queue is UPDATING.
You can't change the data stream or the starting position of a queue after you create it. To read from a different stream or position, create a new queue.
See also: AWS API Documentation
Request Syntax
client.update_queue(
QueueARN='string',
QueueAttributes={
'VisibilityTimeoutSeconds': 123,
'DeadLetterConfiguration': {
'TargetType': 'BUILT_IN'|'NONE',
'MaxReceiveCount': 123
}
}
)
string
[REQUIRED]
The ARN of the queue to update.
dict
[REQUIRED]
The configuration attributes to apply to the queue. Attributes you do not specify are left unchanged.
VisibilityTimeoutSeconds (integer) --
The duration, in seconds, that a record is in flight and not visible to any consumer instance after it is received. A record that is not acknowledged before this duration elapses becomes visible in the queue again and can be received by any consumer instance. If you omit this attribute when you create a queue, the queue uses 30 seconds.
DeadLetterConfiguration (dict) --
The dead-letter handling configuration for the queue. If you omit this attribute, dead-letter handling is enabled with a MaxReceiveCount of 6. If you specify it with a TargetType of BUILT_IN, you must also specify MaxReceiveCount.
TargetType (string) -- [REQUIRED]
Whether dead-letter handling is enabled for the queue. BUILT_IN enables it: when a record has been received MaxReceiveCount times without being acknowledged, it becomes a dead-letter record and ReceiveQueueRecords no longer returns it. NONE disables it, and an unacknowledged record continues to be redelivered until it is acknowledged or its retention period ends.
MaxReceiveCount (integer) --
The number of times a record can be received without being acknowledged before it becomes a dead-letter record. Required when TargetType is BUILT_IN. A queue that you create without DeadLetterConfiguration gets a MaxReceiveCount of 6.
dict
Response Syntax
{
'QueueDescription': {
'QueueName': 'string',
'QueueARN': 'string',
'QueueStatus': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING',
'QueueCreationTimestamp': datetime(2015, 1, 1),
'StreamConfigurationList': [
{
'StreamARN': 'string',
'StartingPosition': {
'Type': 'TRIM_HORIZON'|'LATEST'|'AT_TIMESTAMP',
'Timestamp': datetime(2015, 1, 1)
}
},
],
'QueueAttributes': {
'VisibilityTimeoutSeconds': 123,
'DeadLetterConfiguration': {
'TargetType': 'BUILT_IN'|'NONE',
'MaxReceiveCount': 123
}
}
}
}
Response Structure
(dict) --
QueueDescription (dict) --
A description of the queue, including the updated attributes.
QueueName (string) --
The name of the queue.
QueueARN (string) --
The ARN of the queue. The resource identifier in the ARN is generated when the queue is created and is not derived from QueueName. Use the returned QueueARN to identify the queue in subsequent requests.
QueueStatus (string) --
The current status of the queue.
QueueCreationTimestamp (datetime) --
The time the queue was created.
StreamConfigurationList (list) --
The data stream the queue delivers records from, and the position in that stream where delivery begins. The list contains exactly one entry, because a queue delivers records from a single data stream.
(dict) --
The data stream a queue delivers records from, and the position in that stream where delivery begins.
StreamARN (string) --
The ARN of the data stream.
StartingPosition (dict) --
The position in the stream from which the queue begins delivering records. The default is LATEST.
Type (string) --
You can set the starting position to one of the following values:
LATEST: Delivers records that arrive after you create the queue. This is the default.
TRIM_HORIZON: Start delivering at the last untrimmed record in the stream, which is the oldest record the stream still retains.
AT_TIMESTAMP: Delivers records that arrive at or after a time stamp that you provide.
Timestamp (datetime) --
The approximate time from which the queue begins delivering records. Records that arrive at approximately this time or later are delivered.
In a request, specify this value only when Type is AT_TIMESTAMP. It is required in that case, and specifying it for any other type returns a ValidationException.
In a response, this value is approximate and reflects the queue's effective starting position. While the queue is CREATING, the response echoes what you configured: for AT_TIMESTAMP, the timestamp you provided, and for TRIM_HORIZON and LATEST, this member is absent because the effective position is not yet determined. Once the queue is ACTIVE, the response always includes this member. For AT_TIMESTAMP, it is the timestamp you provided or the earliest time the stream can be read from, whichever is later.
QueueAttributes (dict) --
The configuration attributes of the queue.
VisibilityTimeoutSeconds (integer) --
The duration, in seconds, that a record is in flight and not visible to any consumer instance after it is received. A record that is not acknowledged before this duration elapses becomes visible in the queue again and can be received by any consumer instance. If you omit this attribute when you create a queue, the queue uses 30 seconds.
DeadLetterConfiguration (dict) --
The dead-letter handling configuration for the queue. If you omit this attribute, dead-letter handling is enabled with a MaxReceiveCount of 6. If you specify it with a TargetType of BUILT_IN, you must also specify MaxReceiveCount.
TargetType (string) --
Whether dead-letter handling is enabled for the queue. BUILT_IN enables it: when a record has been received MaxReceiveCount times without being acknowledged, it becomes a dead-letter record and ReceiveQueueRecords no longer returns it. NONE disables it, and an unacknowledged record continues to be redelivered until it is acknowledged or its retention period ends.
MaxReceiveCount (integer) --
The number of times a record can be received without being acknowledged before it becomes a dead-letter record. Required when TargetType is BUILT_IN. A queue that you create without DeadLetterConfiguration gets a MaxReceiveCount of 6.
Returns a description of the specified queue, including its status, the data stream it delivers records from, and its configuration attributes.
See also: AWS API Documentation
Request Syntax
client.describe_queue(
QueueARN='string'
)
string
[REQUIRED]
The ARN of the queue to describe.
dict
Response Syntax
{
'QueueDescription': {
'QueueName': 'string',
'QueueARN': 'string',
'QueueStatus': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING',
'QueueCreationTimestamp': datetime(2015, 1, 1),
'StreamConfigurationList': [
{
'StreamARN': 'string',
'StartingPosition': {
'Type': 'TRIM_HORIZON'|'LATEST'|'AT_TIMESTAMP',
'Timestamp': datetime(2015, 1, 1)
}
},
],
'QueueAttributes': {
'VisibilityTimeoutSeconds': 123,
'DeadLetterConfiguration': {
'TargetType': 'BUILT_IN'|'NONE',
'MaxReceiveCount': 123
}
}
}
}
Response Structure
(dict) --
QueueDescription (dict) --
A description of the queue.
QueueName (string) --
The name of the queue.
QueueARN (string) --
The ARN of the queue. The resource identifier in the ARN is generated when the queue is created and is not derived from QueueName. Use the returned QueueARN to identify the queue in subsequent requests.
QueueStatus (string) --
The current status of the queue.
QueueCreationTimestamp (datetime) --
The time the queue was created.
StreamConfigurationList (list) --
The data stream the queue delivers records from, and the position in that stream where delivery begins. The list contains exactly one entry, because a queue delivers records from a single data stream.
(dict) --
The data stream a queue delivers records from, and the position in that stream where delivery begins.
StreamARN (string) --
The ARN of the data stream.
StartingPosition (dict) --
The position in the stream from which the queue begins delivering records. The default is LATEST.
Type (string) --
You can set the starting position to one of the following values:
LATEST: Delivers records that arrive after you create the queue. This is the default.
TRIM_HORIZON: Start delivering at the last untrimmed record in the stream, which is the oldest record the stream still retains.
AT_TIMESTAMP: Delivers records that arrive at or after a time stamp that you provide.
Timestamp (datetime) --
The approximate time from which the queue begins delivering records. Records that arrive at approximately this time or later are delivered.
In a request, specify this value only when Type is AT_TIMESTAMP. It is required in that case, and specifying it for any other type returns a ValidationException.
In a response, this value is approximate and reflects the queue's effective starting position. While the queue is CREATING, the response echoes what you configured: for AT_TIMESTAMP, the timestamp you provided, and for TRIM_HORIZON and LATEST, this member is absent because the effective position is not yet determined. Once the queue is ACTIVE, the response always includes this member. For AT_TIMESTAMP, it is the timestamp you provided or the earliest time the stream can be read from, whichever is later.
QueueAttributes (dict) --
The configuration attributes of the queue.
VisibilityTimeoutSeconds (integer) --
The duration, in seconds, that a record is in flight and not visible to any consumer instance after it is received. A record that is not acknowledged before this duration elapses becomes visible in the queue again and can be received by any consumer instance. If you omit this attribute when you create a queue, the queue uses 30 seconds.
DeadLetterConfiguration (dict) --
The dead-letter handling configuration for the queue. If you omit this attribute, dead-letter handling is enabled with a MaxReceiveCount of 6. If you specify it with a TargetType of BUILT_IN, you must also specify MaxReceiveCount.
TargetType (string) --
Whether dead-letter handling is enabled for the queue. BUILT_IN enables it: when a record has been received MaxReceiveCount times without being acknowledged, it becomes a dead-letter record and ReceiveQueueRecords no longer returns it. NONE disables it, and an unacknowledged record continues to be redelivered until it is acknowledged or its retention period ends.
MaxReceiveCount (integer) --
The number of times a record can be received without being acknowledged before it becomes a dead-letter record. Required when TargetType is BUILT_IN. A queue that you create without DeadLetterConfiguration gets a MaxReceiveCount of 6.
Receives up to 10 dead-letter records from the specified queue. Each queue has built-in dead-letter handling: when a record has been received MaxReceiveCount times without being acknowledged, it becomes a dead-letter record, which usually means your queue consumer could not process it. The dead-letter record stays in the same queue, and ReceiveQueueRecords no longer returns it.
Dead-letter records carry the same data and partition key as when they were first delivered, and are returned with a receipt handle. Use the receipt handle to acknowledge the record with AcknowledgeDeadLetterQueueRecords, which discards it, to change its visibility with UpdateDeadLetterQueueRecordsVisibility, or to restore it with RestoreDeadLetterQueueRecords, which returns it to the normal receive path so that ReceiveQueueRecords can return it again.
Use this operation to inspect the records your queue consumer could not process, so you can correct the cause and then either acknowledge or restore them.
A queue delivers dead-letter records while it is in the ACTIVE state.
See also: AWS API Documentation
Request Syntax
client.receive_dead_letter_queue_records(
QueueARN='string',
Limit=123,
WaitTimeSeconds=123,
VisibilityTimeoutSeconds=123
)
string
[REQUIRED]
The ARN of the queue whose dead-letter records are received.
integer
The maximum number of records to return. The queue never returns more dead-letter records than this value, and might return fewer. The default is 10.
integer
The duration, in seconds, that the call waits for a record to become visible before returning. The default is 9.
integer
The duration, in seconds, that the records returned by this request are in flight and not visible to any consumer instance. If you do not specify this value, the queue's visibility timeout is used.
dict
Response Syntax
{
'QueueRecords': [
{
'ReceiptHandle': 'string',
'RecordId': 'string',
'PartitionKey': 'string',
'Data': b'bytes',
'ApproximateArrivalTimestamp': datetime(2015, 1, 1),
'FirstReceiveTimestamp': datetime(2015, 1, 1),
'ReceiveCount': 123
},
]
}
Response Structure
(dict) --
QueueRecords (list) --
The dead-letter records received from the queue. This list is empty when no dead-letter records are visible.
(dict) --
A data stream record, as delivered through a queue.
ReceiptHandle (string) --
The identifier you use to acknowledge this record, change its visibility, or restore it after it becomes a dead-letter record. A new receipt handle is issued each time the record is received.
RecordId (string) --
The unique identifier of the record. This value stays the same across every delivery of the record, and it is the same in every queue on the stream that delivers the record. To identify a single delivery, use ReceiptHandle instead.
PartitionKey (string) --
The partition key the record was written to the data stream with.
Data (bytes) --
The data blob of the record. Amazon Kinesis Data Streams does not inspect, interpret, or change the data.
ApproximateArrivalTimestamp (datetime) --
The approximate time the record arrived in the data stream. The difference between this value and the current time is how long the record took to reach your queue consumer.
FirstReceiveTimestamp (datetime) --
The approximate time the record was first received from the queue.
ReceiveCount (integer) --
The number of times this record has been received without being acknowledged.
Deletes the specified queue. Records that are in flight when you delete the queue are not delivered again, and receipt handles issued by the queue stop being valid.
Deleting a queue does not delete the data stream the queue was created on, and does not delete any records in that stream. Those records remain available to stream consumers and to other queues on the same stream for the rest of their retention period.
DeleteQueue is an asynchronous operation. Upon receiving a DeleteQueue request, Amazon Kinesis Data Streams sets the QueueStatus to DELETING. The queue is deleted when the operation completes. A queue in the DELETING state does not deliver records.
You must delete every queue on a data stream before you can delete the stream, or switch it from on-demand to provisioned capacity mode.
See also: AWS API Documentation
Request Syntax
client.delete_queue(
QueueARN='string'
)
string
[REQUIRED]
The ARN of the queue to delete.
None
Changes the visibility timeout of up to 10 records that you have received from the specified queue but not yet acknowledged. The result for each entry is reported individually in the response.
Extend the visibility timeout of a record when your queue consumer needs more time to finish processing it, so the record does not become visible and get redelivered while it is still being processed. Set the visibility timeout to 0 to make a record visible in the queue immediately, so that it can be received again without waiting for its current timeout to expire.
Because the request can result in a combination of successful and unsuccessful entries, check the Failed list even when the call returns an HTTP status code of 200.
See also: AWS API Documentation
Request Syntax
client.update_queue_records_visibility(
QueueARN='string',
Entries=[
{
'ReceiptHandle': 'string',
'VisibilityTimeoutSeconds': 123
},
]
)
string
[REQUIRED]
The ARN of the queue the records were received from.
list
[REQUIRED]
The records whose visibility timeout is changed, identified by their receipt handles, and the new visibility timeout for each.
(dict) --
A record whose visibility timeout is changed, and the new visibility timeout.
ReceiptHandle (string) -- [REQUIRED]
The receipt handle of the record, as returned by ReceiveQueueRecords.
VisibilityTimeoutSeconds (integer) -- [REQUIRED]
The new duration, in seconds, that the record is in flight and not visible to any consumer instance, measured from when this request is processed. Specify 0 to make the record visible in the queue immediately.
dict
Response Syntax
{
'Successful': [
{
'ReceiptHandle': 'string'
},
],
'Failed': [
{
'ReceiptHandle': 'string',
'ErrorCode': 'string',
'ErrorMessage': 'string'
},
]
}
Response Structure
(dict) --
Successful (list) --
The records whose visibility timeout was changed.
(dict) --
A record whose visibility timeout was changed.
ReceiptHandle (string) --
The receipt handle of the record whose visibility timeout was changed.
Failed (list) --
The records whose visibility timeout was not changed, each with the reason the entry failed.
(dict) --
A record whose visibility timeout was not changed, and why.
ReceiptHandle (string) --
The receipt handle of the record whose visibility timeout was not changed.
ErrorCode (string) --
A code identifying the type of failure. One of ResourceNotFoundException, InvalidArgumentException, ThrottlingException, or InternalFailureException.
ErrorMessage (string) --
A description of the cause of the failure.
{'StreamDescriptionSummary': {'QueueCount': 'integer'}}
Provides a summarized description of the specified Kinesis data stream without the shard list.
The information returned includes the stream name, Amazon Resource Name (ARN), status, record retention period, approximate creation time, monitoring, encryption details, and open shard count.
DescribeStreamSummary has a limit of 20 transactions per second per account.
See also: AWS API Documentation
Request Syntax
client.describe_stream_summary(
StreamName='string',
StreamARN='string',
StreamId='string'
)
string
The name of the stream to describe.
string
The ARN of the stream.
string
Not Implemented. Reserved for future use.
dict
Response Syntax
{
'StreamDescriptionSummary': {
'StreamName': 'string',
'StreamARN': 'string',
'StreamId': 'string',
'StreamStatus': 'CREATING'|'DELETING'|'ACTIVE'|'UPDATING',
'StreamModeDetails': {
'StreamMode': 'PROVISIONED'|'ON_DEMAND'
},
'RetentionPeriodHours': 123,
'StreamCreationTimestamp': datetime(2015, 1, 1),
'EnhancedMonitoring': [
{
'ShardLevelMetrics': [
'IncomingBytes'|'IncomingRecords'|'OutgoingBytes'|'OutgoingRecords'|'WriteProvisionedThroughputExceeded'|'ReadProvisionedThroughputExceeded'|'IteratorAgeMilliseconds'|'ALL',
]
},
],
'EncryptionType': 'NONE'|'KMS',
'KeyId': 'string',
'OpenShardCount': 123,
'ConsumerCount': 123,
'WarmThroughput': {
'TargetMiBps': 123,
'CurrentMiBps': 123
},
'MaxRecordSizeInKiB': 123,
'ChannelCount': 123,
'RecordDistributionStrategy': 'AUTO'|'USER_PARTITION_KEY',
'QueueCount': 123
}
}
Response Structure
(dict) --
StreamDescriptionSummary (dict) --
A StreamDescriptionSummary containing information about the stream.
StreamName (string) --
The name of the stream being described.
StreamARN (string) --
The Amazon Resource Name (ARN) for the stream being described.
StreamId (string) --
Not Implemented. Reserved for future use.
StreamStatus (string) --
The current status of the stream being described. The stream status is one of the following states:
CREATING - The stream is being created. Kinesis Data Streams immediately returns and sets StreamStatus to CREATING.
DELETING - The stream is being deleted. The specified stream is in the DELETING state until Kinesis Data Streams completes the deletion.
ACTIVE - The stream exists and is ready for read and write operations or deletion. You should perform read and write operations only on an ACTIVE stream.
UPDATING - Shards in the stream are being merged or split. Read and write operations continue to work while the stream is in the UPDATING state.
StreamModeDetails (dict) --
Specifies the capacity mode to which you want to set your data stream. Currently, in Kinesis Data Streams, you can choose between an on-demand capacity mode and a provisioned capacity mode for your data streams.
StreamMode (string) --
Specifies the capacity mode to which you want to set your data stream. Currently, in Kinesis Data Streams, you can choose between an on-demand capacity mode and a provisioned capacity mode for your data streams.
RetentionPeriodHours (integer) --
The current retention period, in hours.
StreamCreationTimestamp (datetime) --
The approximate time that the stream was created.
EnhancedMonitoring (list) --
Represents the current enhanced monitoring settings of the stream.
(dict) --
Represents enhanced metrics types.
ShardLevelMetrics (list) --
List of shard-level metrics.
The following are the valid shard-level metrics. The value " ALL" enhances every metric.
IncomingBytes
IncomingRecords
OutgoingBytes
OutgoingRecords
WriteProvisionedThroughputExceeded
ReadProvisionedThroughputExceeded
IteratorAgeMilliseconds
ALL
For more information, see Monitoring the Amazon Kinesis Data Streams Service with Amazon CloudWatch in the Amazon Kinesis Data Streams Developer Guide.
(string) --
EncryptionType (string) --
The encryption type used. This value is one of the following:
KMS
NONE
KeyId (string) --
The GUID for the customer-managed Amazon Web Services KMS key to use for encryption. This value can be a globally unique identifier, a fully specified ARN to either an alias or a key, or an alias name prefixed by "alias/".You can also use a master key owned by Kinesis Data Streams by specifying the alias aws/kinesis.
Key ARN example: arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
Alias ARN example: arn:aws:kms:us-east-1:123456789012:alias/MyAliasName
Globally unique key ID example: 12345678-1234-1234-1234-123456789012
Alias name example: alias/MyAliasName
Master key owned by Kinesis Data Streams: alias/aws/kinesis
OpenShardCount (integer) --
The number of open shards in the stream.
ConsumerCount (integer) --
The number of enhanced fan-out consumers registered with the stream. Queues are not included in this count, even though they share the stream's registered consumer limit with enhanced fan-out consumers. QueueCount reports the number of queues.
WarmThroughput (dict) --
The warm throughput in MB/s for the stream. This represents the throughput capacity that will be immediately available for write operations.
TargetMiBps (integer) --
The target warm throughput value on the stream. This indicates that the stream is currently scaling towards this target value.
CurrentMiBps (integer) --
The current warm throughput value on the stream. This is the write throughput in MiBps that the stream is currently scaled to handle.
MaxRecordSizeInKiB (integer) --
The maximum record size of a single record in kibibyte (KiB) that you can write to, and read from a stream.
ChannelCount (integer) --
The number of channels associated with the stream.
RecordDistributionStrategy (string) --
The record distribution strategy that the stream currently uses. A value of AUTO indicates that Amazon Kinesis Data Streams distributes records across shards using service-managed algorithms. A value of USER_PARTITION_KEY indicates that shard placement is determined by the partition key that producers supply. This field is only present for streams that use the on-demand capacity mode.
QueueCount (integer) --
The number of queues created on the data stream.