View a markdown version of this page

ReceiveQueueRecords - Amazon Kinesis Data Streams Service

ReceiveQueueRecords

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.

Request Syntax

{ "Limit": number, "QueueARN": "string", "VisibilityTimeoutSeconds": number, "WaitTimeSeconds": number }

Request Parameters

The request accepts the following data in JSON format.

Limit

The maximum number of records to return. The queue never returns more records than this value, and might return fewer. The default is 10.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 10.

Required: No

QueueARN

The ARN of the queue to receive records from.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: arn:aws.*:kinesis:.*:\d{12}:queue/\S+

Required: Yes

VisibilityTimeoutSeconds

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.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 43200.

Required: No

WaitTimeSeconds

The duration, in seconds, that the call waits for a record to become visible before returning. The default is 9.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 20.

Required: No

Response Syntax

{ "QueueRecords": [ { "ApproximateArrivalTimestamp": number, "Data": blob, "FirstReceiveTimestamp": number, "PartitionKey": "string", "ReceiptHandle": "string", "ReceiveCount": number, "RecordId": "string" } ] }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

QueueRecords

The records received from the queue. This list is empty when no records are visible.

Type: Array of QueueRecord objects

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

Specifies that you do not have the permissions required to perform this operation.

HTTP Status Code: 400

InternalFailureException

The processing of the request failed because of an unknown error, exception, or failure.

HTTP Status Code: 500

InvalidArgumentException

A specified parameter exceeds its restrictions, is not supported, or can't be used. For more information, see the returned message.

message

A message that provides information about the error.

HTTP Status Code: 400

KMSAccessDeniedException

The ciphertext references a key that doesn't exist or that you don't have access to.

message

A message that provides information about the error.

HTTP Status Code: 400

KMSDisabledException

The request was rejected because the specified KMS key isn't enabled.

message

A message that provides information about the error.

HTTP Status Code: 400

KMSInvalidStateException

The request was rejected because the state of the specified resource isn't valid for this request. For more information, see How Key State Affects Use of a Customer Master Key in the AWS Key Management Service Developer Guide.

message

A message that provides information about the error.

HTTP Status Code: 400

KMSNotFoundException

The request was rejected because the specified entity or resource can't be found.

message

A message that provides information about the error.

HTTP Status Code: 400

KMSOptInRequired

The AWS access key ID needs a subscription for the service.

message

A message that provides information about the error.

HTTP Status Code: 400

KMSThrottlingException

The request was denied due to request throttling. For more information about throttling, see Limits in the AWS Key Management Service Developer Guide.

message

A message that provides information about the error.

HTTP Status Code: 400

ResourceNotFoundException

The requested resource could not be found. The stream might not be specified correctly.

message

A message that provides information about the error.

HTTP Status Code: 400

ThrottlingException

The request was denied because the request rate is too high. Reduce the frequency of your requests, and retry them with exponential backoff.

message

A message that provides information about the error.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: