Kinesis / Client / subscribe_to_shard

subscribe_to_shard#

Kinesis.Client.subscribe_to_shard(**kwargs)#

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

response = client.subscribe_to_shard(
    ConsumerARN='string',
    ShardId='string',
    StartingPosition={
        'Type': 'AT_SEQUENCE_NUMBER'|'AFTER_SEQUENCE_NUMBER'|'TRIM_HORIZON'|'LATEST'|'AT_TIMESTAMP',
        'SequenceNumber': 'string',
        'Timestamp': datetime(2015, 1, 1)
    }
)

Parameters:

ConsumerARN (string) –
[REQUIRED]

For this parameter, use the value you obtained when you called RegisterStreamConsumer.
ShardId (string) –
[REQUIRED]

The ID of the shard you want to subscribe to. To see a list of all the shards for a given stream, use ListShards.
StartingPosition (dict) –
[REQUIRED]

The starting position in the data stream from which to start streaming.
- Type (string) – [REQUIRED]
  
  You can set the starting position to one of the following values:
  
  AT_SEQUENCE_NUMBER: Start streaming from the position denoted by the sequence number specified in the SequenceNumber field.
  
  AFTER_SEQUENCE_NUMBER: Start streaming right after the position denoted by the sequence number specified in the SequenceNumber field.
  
  AT_TIMESTAMP: Start streaming from the position denoted by the time stamp specified in the Timestamp field.
  
  TRIM_HORIZON: Start streaming at the last untrimmed record in the shard, which is the oldest data record in the shard.
  
  LATEST: Start streaming just after the most recent record in the shard, so that you always read the most recent data in the shard.
- SequenceNumber (string) –
  
  The sequence number of the data record in the shard from which to start streaming. To specify a sequence number, set StartingPosition to AT_SEQUENCE_NUMBER or AFTER_SEQUENCE_NUMBER.
- Timestamp (datetime) –
  
  The time stamp of the data record from which to start reading. To specify a time stamp, set StartingPosition to Type AT_TIMESTAMP. A time stamp is the Unix epoch date with precision in milliseconds. For example, 2016-04-04T19:58:46.480-00:00 or 1459799926.480. If a record with this exact time stamp does not exist, records will be streamed from the next (later) record. If the time stamp is older than the current trim horizon, records will be streamed from the oldest untrimmed data record ( TRIM_HORIZON).

Return type:

dict

Returns:

The response of this operation contains an EventStream member. When iterated the EventStream will yield events based on the structure below, where only one of the top level keys will be present for any given event.

Response Syntax

{
    'EventStream': EventStream({
        'SubscribeToShardEvent': {
            'Records': [
                {
                    'SequenceNumber': 'string',
                    'ApproximateArrivalTimestamp': datetime(2015, 1, 1),
                    'Data': b'bytes',
                    'PartitionKey': 'string',
                    'EncryptionType': 'NONE'|'KMS'
                },
            ],
            'ContinuationSequenceNumber': 'string',
            'MillisBehindLatest': 123,
            'ChildShards': [
                {
                    'ShardId': 'string',
                    'ParentShards': [
                        'string',
                    ],
                    'HashKeyRange': {
                        'StartingHashKey': 'string',
                        'EndingHashKey': 'string'
                    }
                },
            ]
        },
        'ResourceNotFoundException': {
            'message': 'string'
        },
        'ResourceInUseException': {
            'message': 'string'
        },
        'KMSDisabledException': {
            'message': 'string'
        },
        'KMSInvalidStateException': {
            'message': 'string'
        },
        'KMSAccessDeniedException': {
            'message': 'string'
        },
        'KMSNotFoundException': {
            'message': 'string'
        },
        'KMSOptInRequired': {
            'message': 'string'
        },
        'KMSThrottlingException': {
            'message': 'string'
        },
        'InternalFailureException': {
            'message': 'string'
        }
    })
}

Response Structure

(dict) –
- EventStream (EventStream) –
  
  The event stream that your consumer can use to read records from the shard.
  - SubscribeToShardEvent (dict) –
    
    After you call SubscribeToShard, Kinesis Data Streams sends events of this type to your consumer. For an example of how to handle these events, see Enhanced Fan-Out Using the Kinesis Data Streams API.
    - Records (list) –
      - (dict) –
        
        The unit of data of the Kinesis data stream, which is composed of a sequence number, a partition key, and a data blob.
        
        SequenceNumber (string) –
        
        The unique identifier of the record within its shard.
        
        ApproximateArrivalTimestamp (datetime) –
        
        The approximate time that the record was inserted into the stream.
        
        Data (bytes) –
        
        The data blob. The data in the blob is both opaque and immutable to Kinesis Data Streams, which does not inspect, interpret, or change the data in the blob in any way. When the data blob (the payload before base64-encoding) is added to the partition key size, the total size must not exceed the maximum record size (1 MiB).
        
        PartitionKey (string) –
        
        Identifies which shard in the stream the data record is assigned to.
        
        EncryptionType (string) –
        
        The encryption type used on the record. This parameter can be one of the following values:
        
        NONE: Do not encrypt the records in the stream.
        
        KMS: Use server-side encryption on the records in the stream using a customer-managed Amazon Web Services KMS key.
    - ContinuationSequenceNumber (string) –
      
      Use this as SequenceNumber in the next call to SubscribeToShard, with StartingPosition set to AT_SEQUENCE_NUMBER or AFTER_SEQUENCE_NUMBER. Use ContinuationSequenceNumber for checkpointing because it captures your shard progress even when no data is written to the shard.
    - MillisBehindLatest (integer) –
      
      The number of milliseconds the read records are from the tip of the stream, indicating how far behind current time the consumer is. A value of zero indicates that record processing is caught up, and there are no new records to process at this moment.
    - ChildShards (list) –
      
      The list of the child shards of the current shard, returned only at the end of the current shard.
      - (dict) –
        
        Output parameter of the GetRecords API. The existing child shard of the current shard.
        
        ShardId (string) –
        
        The shard ID of the existing child shard of the current shard.
        
        ParentShards (list) –
        
        The current shard that is the parent of the existing child shard.
        
        (string) –
        
        HashKeyRange (dict) –
        
        The range of possible hash key values for the shard, which is a set of ordered contiguous positive integers.
        
        StartingHashKey (string) –
        
        The starting hash key of the hash key range.
        
        EndingHashKey (string) –
        
        The ending hash key of the hash key range.
  - ResourceNotFoundException (dict) –
    
    The requested resource could not be found. The stream might not be specified correctly.
    - message (string) –
      
      A message that provides information about the error.
  - ResourceInUseException (dict) –
    
    The resource is not available for this operation. For successful operation, the resource must be in the ACTIVE state.
    - message (string) –
      
      A message that provides information about the error.
  - KMSDisabledException (dict) –
    
    The request was rejected because the specified customer master key (CMK) isn’t enabled.
    - message (string) –
      
      A message that provides information about the error.
  - KMSInvalidStateException (dict) –
    
    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 Amazon Web Services Key Management Service Developer Guide.
    - message (string) –
      
      A message that provides information about the error.
  - KMSAccessDeniedException (dict) –
    
    The ciphertext references a key that doesn’t exist or that you don’t have access to.
    - message (string) –
      
      A message that provides information about the error.
  - KMSNotFoundException (dict) –
    
    The request was rejected because the specified entity or resource can’t be found.
    - message (string) –
      
      A message that provides information about the error.
  - KMSOptInRequired (dict) –
    
    The Amazon Web Services access key ID needs a subscription for the service.
    - message (string) –
      
      A message that provides information about the error.
  - KMSThrottlingException (dict) –
    
    The request was denied due to request throttling. For more information about throttling, see Limits in the Amazon Web Services Key Management Service Developer Guide.
    - message (string) –
      
      A message that provides information about the error.
  - InternalFailureException (dict) –
    
    The processing of the request failed because of an unknown error, exception, or failure.
    - message (string) –

Exceptions

Kinesis.Client.exceptions.ResourceNotFoundException
Kinesis.Client.exceptions.InvalidArgumentException
Kinesis.Client.exceptions.ResourceInUseException
Kinesis.Client.exceptions.LimitExceededException
Kinesis.Client.exceptions.AccessDeniedException