get_shard_iterator ¶

def get_shard_iterator(
    self,
    stream_arn: "capo_dynamodb_streams.types.stream_arn.StreamArn",
    shard_id: "capo_dynamodb_streams.types.shard_id.ShardId",
    shard_iterator_type: "capo_dynamodb_streams.types.shard_iterator_type.ShardIteratorType",
    *,
    config_overrides: Optional[DynamoDBStreamsClientConfig] = None,
    sequence_number: Optional[
        "capo_dynamodb_streams.types.sequence_number.SequenceNumber"
    ] = None,
    timestamp: Optional["capo_dynamodb_streams.types.timestamp.Timestamp"] = None,
) -> "capo_dynamodb_streams.types.get_shard_iterator_output.GetShardIteratorOutput":
    """<p>Returns a shard iterator. A shard iterator provides information about how to retrieve the stream records from within a shard. Use the shard iterator in a subsequent <code>GetRecords</code> request to read the stream records from the shard.</p> <note> <p>A shard iterator expires 15 minutes after it is returned to the requester.</p> </note>

    Args:
        stream_arn: <p>The Amazon Resource Name (ARN) for the stream.</p>
        shard_id: <p>The identifier of the shard. The iterator will be returned for this shard ID.</p>
        shard_iterator_type: <p>Determines how the shard iterator is used to start reading stream records from the shard:</p> <ul> <li> <p> <code>AT_SEQUENCE_NUMBER</code> - Start reading exactly from the position denoted by a specific sequence number.</p> </li> <li> <p> <code>AFTER_SEQUENCE_NUMBER</code> - Start reading right after the position denoted by a specific sequence number.</p> </li> <li> <p> <code>TRIM_HORIZON</code> - Start reading at the last (untrimmed) stream record, which is the oldest record in the shard. In DynamoDB Streams, there is a 24 hour limit on data retention. Stream records whose age exceeds this limit are subject to removal (trimming) from the stream.</p> </li> <li> <p> <code>LATEST</code> - Start reading just after the most recent stream record in the shard, so that you always read the most recent data in the shard.</p> </li> <li> <p> <code>AT_TIMESTAMP</code> - Start reading from the position denoted by a specific timestamp, provided in the parameter <code>Timestamp</code>.</p> </li> </ul>
        sequence_number: <p>The sequence number of a stream record in the shard from which to start reading.</p>
        timestamp: <p>The timestamp of the stream record from which to start reading. Used with shard iterator type <code>AT_TIMESTAMP</code>. A timestamp is the Unix epoch date with precision in milliseconds. For example, <code>1791316726.480</code>. The iterator points to the first stream record whose <code>ApproximateCreationDateTime</code> is at or after the specified timestamp. If no record with that exact timestamp exists, the iterator points to the next (later) record. If the timestamp is older than the current trim horizon, the iterator points to the oldest untrimmed stream record (<code>TRIM_HORIZON</code>). If the timestamp is in the future, the request returns a <code>ValidationException</code>.</p>

    Raises:
        capo_dynamodb_streams.errors.internal_server_error.InternalServerError: <p>An error occurred on the server side.</p>
        capo_dynamodb_streams.errors.resource_not_found_exception.ResourceNotFoundException: <p>The operation tried to access a nonexistent table or index. The resource might not be specified correctly, or its status might not be <code>ACTIVE</code>.</p>
        capo_dynamodb_streams.errors.trimmed_data_access_exception.TrimmedDataAccessException: <p>The operation attempted to read past the oldest stream record in a shard.</p> <p>In DynamoDB Streams, there is a 24 hour limit on data retention. Stream records whose age exceeds this limit are subject to removal (trimming) from the stream. You might receive a TrimmedDataAccessException if:</p> <ul> <li> <p>You request a shard iterator with a sequence number older than the trim point (24 hours).</p> </li> <li> <p>You obtain a shard iterator, but before you use the iterator in a <code>GetRecords</code> request, a stream record in the shard exceeds the 24 hour period and is trimmed. This causes the iterator to access a record that no longer exists.</p> </li> </ul>
        capo_dynamodb_streams.errors.UnknownServiceError: The service returned an error code this client does not model.

    Examples:
        To obtain a shard iterator for the provided stream ARN and shard ID
        The following example returns a shard iterator for the provided stream ARN and shard ID.

        >>> client.get_shard_iterator(stream_arn='arn:aws:dynamodb:us-west-2:111122223333:table/Forum/stream/2015-05-20T20:51:10.252', shard_id='00000001414576573621-f55eea83', shard_iterator_type='TRIM_HORIZON')
    """

    def _handler(
        req: "OperationRequest[capo_dynamodb_streams.types.get_shard_iterator_input.GetShardIteratorInput]",
    ) -> OperationResponse[
        "capo_dynamodb_streams.types.get_shard_iterator_output.GetShardIteratorOutput"
    ]:
        import capo_dynamodb_streams._operations.dynamo_db_streams_20120810.get_shard_iterator

        output, http_response = (
            capo_dynamodb_streams._operations.dynamo_db_streams_20120810.get_shard_iterator.get_shard_iterator(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("GetShardIterator")
    )
    input_: capo_dynamodb_streams.types.get_shard_iterator_input.GetShardIteratorInput = {
        "stream_arn": stream_arn,
        "shard_id": shard_id,
        "shard_iterator_type": shard_iterator_type,
    }
    if sequence_number is not None:
        input_["sequence_number"] = sequence_number
    if timestamp is not None:
        input_["timestamp"] = timestamp

    response = execute_pipeline(
        OperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    response.response.close()
    return response.output