Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

SubscribeToShard

This operation establishes an HTTP/2 connection between the consumer you specify in the ConsumerARN parameter and the shard you specify in the ShardId parameter. After the connection is successfully established, Kinesis Data Streams pushes records from the shard to the consumer over this connection. Before you call this operation, call RegisterStreamConsumer to register the consumer with Kinesis Data Streams.

When the SubscribeToShard call succeeds, your consumer starts receiving events of type SubscribeToShardEvent over the HTTP/2 connection for up to 5 minutes, after which time you need to call SubscribeToShard again to renew the subscription if you want to continue to receive records.

You can make one call to SubscribeToShard per second per registered consumer per shard. For example, if you have a 4000 shard stream and two registered stream consumers, you can make one SubscribeToShard request per second for each combination of shard and registered consumer, allowing you to subscribe both consumers to all 4000 shards in one second.

If you call SubscribeToShard again with the same ConsumerARN and ShardId within 5 seconds of a successful call, you'll get a ResourceInUseException. If you call SubscribeToShard 5 seconds or more after a successful call, the second call takes over the subscription and the previous connection expires or fails with a ResourceInUseException.

For an example of how to use this operation, see Enhanced Fan-Out Using the Kinesis Data Streams API.

Request Syntax


{
   "ConsumerARN": "string",
   "ShardId": "string",
   "StartingPosition": { 
      "SequenceNumber": "string",
      "Timestamp": number,
      "Type": "string"
   }
}

Request Parameters

The request accepts the following data in JSON format.

ConsumerARN

For this parameter, use the value you obtained when you called RegisterStreamConsumer.

Type: String

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

Pattern: ^(arn):aws.*:kinesis:.*:\d{12}:.*stream\/[a-zA-Z0-9_.-]+\/consumer\/[a-zA-Z0-9_.-]+:[0-9]+

Required: Yes

ShardId

The ID of the shard you want to subscribe to. To see a list of all the shards for a given stream, use ListShards.

Type: String

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

Pattern: [a-zA-Z0-9_.-]+

Required: Yes

StartingPosition

The starting position in the data stream from which to start streaming.

Type: StartingPosition object

Required: Yes

Response Syntax


{
   "EventStream": { 
      "InternalFailureException": { 
      },
      "KMSAccessDeniedException": { 
      },
      "KMSDisabledException": { 
      },
      "KMSInvalidStateException": { 
      },
      "KMSNotFoundException": { 
      },
      "KMSOptInRequired": { 
      },
      "KMSThrottlingException": { 
      },
      "ResourceInUseException": { 
      },
      "ResourceNotFoundException": { 
      },
      "SubscribeToShardEvent": { 
         "ChildShards": [ 
            { 
               "HashKeyRange": { 
                  "EndingHashKey": "string",
                  "StartingHashKey": "string"
               },
               "ParentShards": [ "string" ],
               "ShardId": "string"
            }
         ],
         "ContinuationSequenceNumber": "string",
         "MillisBehindLatest": number,
         "Records": [ 
            { 
               "ApproximateArrivalTimestamp": number,
               "Data": blob,
               "EncryptionType": "string",
               "PartitionKey": "string",
               "SequenceNumber": "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.

EventStream

The event stream that your consumer can use to read records from the shard.

Type: SubscribeToShardEventStream object

Errors

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

AccessDeniedException

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

HTTP Status Code: 400

InvalidArgumentException

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

HTTP Status Code: 400

LimitExceededException

The requested resource exceeds the maximum number allowed, or the number of concurrent stream requests exceeds the maximum number allowed.

HTTP Status Code: 400

ResourceInUseException

The resource is not available for this operation. For successful operation, the resource must be in the ACTIVE state.

HTTP Status Code: 400

ResourceNotFoundException

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

HTTP Status Code: 400