SUBSCRIBETOSHARD()`¶

About 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.

Method Signature¶

IMPORTING¶

Required arguments:¶

`iv_consumerarn` `TYPE /AWS1/KNSCONSUMERARN` `/AWS1/KNSCONSUMERARN`¶

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

`iv_shardid` `TYPE /AWS1/KNSSHARDID` `/AWS1/KNSSHARDID`¶

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

`io_startingposition` `TYPE REF TO /AWS1/CL_KNSSTARTINGPOSITION` `/AWS1/CL_KNSSTARTINGPOSITION`¶

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

RETURNING¶

`oo_output` `TYPE REF TO /aws1/cl_knssubtoshardoutput` `/AWS1/CL_KNSSUBTOSHARDOUTPUT`¶

Domain /AWS1/RT_ACCOUNT_ID

Primitive Type NUMC

Examples¶

Syntax Example¶

This is an example of the syntax for calling the method. It includes every possible argument and initializes every possible value. The data provided is not necessarily semantically accurate (for example the value "string" may be provided for something that is intended to be an instance ID, or in some cases two arguments may be mutually exclusive). The syntax shows the ABAP syntax for creating the various data structures.

DATA(lo_result) = lo_client->/aws1/if_kns~subscribetoshard(
  io_startingposition = new /aws1/cl_knsstartingposition(
    iv_sequencenumber = |string|
    iv_timestamp = '20150101000000.0000000'
    iv_type = |string|
  )
  iv_consumerarn = |string|
  iv_shardid = |string|
).

This is an example of reading all possible response values

lo_result = lo_result.
IF lo_result IS NOT INITIAL.
  TRY.
    WHILE lo_result->get_eventstream( )->/aws1/if_rt_stream_reader~data_available( ) = ABAP_TRUE.
      lo_event = lo_result->get_eventstream( )->READ( ).
      IF lo_event->get_subscribetoshardevent( ) IS NOT INITIAL.
        " process this kind of event
      ENDIF.
    ENDWHILE.
  CATCH /aws1/cx_knsinternalfailureex.
    " handle error in stream
  CATCH /aws1/cx_knskmsaccessdeniedex.
    " handle error in stream
  CATCH /aws1/cx_knskmsnotfoundex.
    " handle error in stream
  CATCH /aws1/cx_knskmsoptinrequired.
    " handle error in stream
  CATCH /aws1/cx_knsresourceinuseex.
    " handle error in stream
  CATCH /aws1/cx_knskmsdisabledex.
    " handle error in stream
  CATCH /aws1/cx_knsresourcenotfoundex.
    " handle error in stream
  CATCH /aws1/cx_knskmsthrottlingex.
    " handle error in stream
  CATCH /aws1/cx_knskmsinvalidstateex.
    " handle error in stream
  ENDTRY.
ENDIF.

/AWS1/CL_KNS=>SUBSCRIBETOSHARD()¶