Skip to content

subscribe_to_shard

Operation

Async only

This operation uses an event stream, so only the asynchronous client supports it.

subscribe_to_shard async

subscribe_to_shard(request: SubscribeToShardInput | SubscribeToShardInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[SubscribeToShardInputDict]) -> AsyncOutputEventStream[SubscribeToShardEventStream, SubscribeToShardOutput]

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.

Parameters:

Name Type Description Default
request SubscribeToShardInput | SubscribeToShardInputDict | None

The input as a model or dictionary. Pass this or keyword arguments, not both.

None
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

None
**kwargs Unpack[SubscribeToShardInputDict]

The input fields as keyword arguments.

{}

Returns:

Type Description
AsyncOutputEventStream[SubscribeToShardEventStream, SubscribeToShardOutput]

An AsyncOutputEventStream for server-to-client streaming.

Input

Pass the input as keyword arguments, a positional dictionary, or a positional model object. Pass plugins separately as a keyword argument.

SubscribeToShardInputDict

Bases: TypedDict

Dictionary form of SubscribeToShardInput.

Attributes

consumer_arn instance-attribute
consumer_arn: Required[str]

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

dry_run instance-attribute
dry_run: bool | None

Checks if your request will succeed. DryRun is an optional parameter.

shard_id instance-attribute
shard_id: Required[str]

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

starting_position instance-attribute

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

stream_id instance-attribute
stream_id: str | None

Not Implemented. Reserved for future use.

SubscribeToShardInput dataclass

Bases: _SerdeShape

Dataclass for SubscribeToShardInput structure.

Attributes

consumer_arn class-attribute instance-attribute
consumer_arn: str | None = ...

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

dry_run class-attribute instance-attribute
dry_run: bool | None = ...

Checks if your request will succeed. DryRun is an optional parameter.

shard_id class-attribute instance-attribute
shard_id: str | None = ...

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

starting_position class-attribute instance-attribute
starting_position: StartingPosition | None = ...

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

stream_id class-attribute instance-attribute
stream_id: str | None = ...

Not Implemented. Reserved for future use.

Output

This operation returns an AsyncOutputEventStream for server-to-client streaming.

Event Stream Structure

Output Event Type

SubscribeToShardEventStream

Initial Response Structure

SubscribeToShardOutput dataclass

Bases: _SerdeShape

Dataclass for SubscribeToShardOutput structure.

Attributes
response_metadata class-attribute instance-attribute
response_metadata: ResponseMetadata = ...

Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.