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 |
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
¶
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
¶
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
¶
starting_position: Required[StartingPosition | StartingPositionDict]
The starting position in the data stream from which to start streaming.
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.
Output¶
This operation returns an AsyncOutputEventStream for server-to-client streaming.
Event Stream Structure¶
Output Event Type¶
Initial Response Structure¶
SubscribeToShardOutput
dataclass
¶
Bases: _SerdeShape
Dataclass for SubscribeToShardOutput structure.