{-# LANGUAGE DeriveDataTypeable #-} {-# LANGUAGE DeriveGeneric #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE RecordWildCards #-} {-# LANGUAGE TypeFamilies #-} {-# OPTIONS_GHC -fno-warn-unused-imports #-} {-# OPTIONS_GHC -fno-warn-unused-binds #-} {-# OPTIONS_GHC -fno-warn-unused-matches #-} -- Derived from AWS service descriptions, licensed under Apache 2.0. -- | -- Module : Network.AWS.Kinesis.GetRecords -- Copyright : (c) 2013-2015 Brendan Hay -- License : Mozilla Public License, v. 2.0. -- Maintainer : Brendan Hay -- Stability : auto-generated -- Portability : non-portable (GHC extensions) -- -- Gets data records from a shard. -- -- Specify a shard iterator using the 'ShardIterator' parameter. The shard -- iterator specifies the position in the shard from which you want to -- start reading data records sequentially. If there are no records -- available in the portion of the shard that the iterator points to, -- GetRecords returns an empty list. Note that it might take multiple calls -- to get to a portion of the shard that contains records. -- -- You can scale by provisioning multiple shards. Your application should -- have one thread per shard, each reading continuously from its stream. To -- read from a stream continually, call GetRecords in a loop. Use -- GetShardIterator to get the shard iterator to specify in the first -- GetRecords call. GetRecords returns a new shard iterator in -- 'NextShardIterator'. Specify the shard iterator returned in -- 'NextShardIterator' in subsequent calls to GetRecords. Note that if the -- shard has been closed, the shard iterator can\'t return more data and -- GetRecords returns 'null' in 'NextShardIterator'. You can terminate the -- loop when the shard is closed, or when the shard iterator reaches the -- record with the sequence number or other attribute that marks it as the -- last record to process. -- -- Each data record can be up to 50 KB in size, and each shard can read up -- to 2 MB per second. You can ensure that your calls don\'t exceed the -- maximum supported size or throughput by using the 'Limit' parameter to -- specify the maximum number of records that GetRecords can return. -- Consider your average record size when determining this limit. For -- example, if your average record size is 40 KB, you can limit the data -- returned to about 1 MB per call by specifying 25 as the limit. -- -- The size of the data returned by GetRecords will vary depending on the -- utilization of the shard. The maximum size of data that GetRecords can -- return is 10 MB. If a call returns this amount of data, subsequent calls -- made within the next 5 seconds throw -- 'ProvisionedThroughputExceededException'. If there is insufficient -- provisioned throughput on the shard, subsequent calls made within the -- next 1 second throw 'ProvisionedThroughputExceededException'. Note that -- GetRecords won\'t return any data when it throws an exception. For this -- reason, we recommend that you wait one second between calls to -- GetRecords; however, it\'s possible that the application will get -- exceptions for longer than 1 second. -- -- To detect whether the application is falling behind in processing, you -- can use the 'MillisBehindLatest' response attribute. You can also -- monitor the amount of data in a stream using the CloudWatch metrics. For -- more information, see -- -- in the /Amazon Kinesis Developer Guide/. -- -- /See:/ for GetRecords. module Network.AWS.Kinesis.GetRecords ( -- * Creating a Request getRecords , GetRecords -- * Request Lenses , grLimit , grShardIterator -- * Destructuring the Response , getRecordsResponse , GetRecordsResponse -- * Response Lenses , grrsNextShardIterator , grrsMillisBehindLatest , grrsResponseStatus , grrsRecords ) where import Network.AWS.Kinesis.Types import Network.AWS.Kinesis.Types.Product import Network.AWS.Prelude import Network.AWS.Request import Network.AWS.Response -- | Represents the input for GetRecords. -- -- /See:/ 'getRecords' smart constructor. data GetRecords = GetRecords' { _grLimit :: !(Maybe Nat) , _grShardIterator :: !Text } deriving (Eq,Read,Show,Data,Typeable,Generic) -- | Creates a value of 'GetRecords' with the minimum fields required to make a request. -- -- Use one of the following lenses to modify other fields as desired: -- -- * 'grLimit' -- -- * 'grShardIterator' getRecords :: Text -- ^ 'grShardIterator' -> GetRecords getRecords pShardIterator_ = GetRecords' { _grLimit = Nothing , _grShardIterator = pShardIterator_ } -- | The maximum number of records to return. Specify a value of up to -- 10,000. If you specify a value that is greater than 10,000, GetRecords -- throws 'InvalidArgumentException'. grLimit :: Lens' GetRecords (Maybe Natural) grLimit = lens _grLimit (\ s a -> s{_grLimit = a}) . mapping _Nat; -- | The position in the shard from which you want to start sequentially -- reading data records. A shard iterator specifies this position using the -- sequence number of a data record in the shard. grShardIterator :: Lens' GetRecords Text grShardIterator = lens _grShardIterator (\ s a -> s{_grShardIterator = a}); instance AWSRequest GetRecords where type Rs GetRecords = GetRecordsResponse request = postJSON kinesis response = receiveJSON (\ s h x -> GetRecordsResponse' <$> (x .?> "NextShardIterator") <*> (x .?> "MillisBehindLatest") <*> (pure (fromEnum s)) <*> (x .?> "Records" .!@ mempty)) instance ToHeaders GetRecords where toHeaders = const (mconcat ["X-Amz-Target" =# ("Kinesis_20131202.GetRecords" :: ByteString), "Content-Type" =# ("application/x-amz-json-1.1" :: ByteString)]) instance ToJSON GetRecords where toJSON GetRecords'{..} = object (catMaybes [("Limit" .=) <$> _grLimit, Just ("ShardIterator" .= _grShardIterator)]) instance ToPath GetRecords where toPath = const "/" instance ToQuery GetRecords where toQuery = const mempty -- | Represents the output for GetRecords. -- -- /See:/ 'getRecordsResponse' smart constructor. data GetRecordsResponse = GetRecordsResponse' { _grrsNextShardIterator :: !(Maybe Text) , _grrsMillisBehindLatest :: !(Maybe Nat) , _grrsResponseStatus :: !Int , _grrsRecords :: ![Record] } deriving (Eq,Read,Show,Data,Typeable,Generic) -- | Creates a value of 'GetRecordsResponse' with the minimum fields required to make a request. -- -- Use one of the following lenses to modify other fields as desired: -- -- * 'grrsNextShardIterator' -- -- * 'grrsMillisBehindLatest' -- -- * 'grrsResponseStatus' -- -- * 'grrsRecords' getRecordsResponse :: Int -- ^ 'grrsResponseStatus' -> GetRecordsResponse getRecordsResponse pResponseStatus_ = GetRecordsResponse' { _grrsNextShardIterator = Nothing , _grrsMillisBehindLatest = Nothing , _grrsResponseStatus = pResponseStatus_ , _grrsRecords = mempty } -- | The next position in the shard from which to start sequentially reading -- data records. If set to 'null', the shard has been closed and the -- requested iterator will not return any more data. grrsNextShardIterator :: Lens' GetRecordsResponse (Maybe Text) grrsNextShardIterator = lens _grrsNextShardIterator (\ s a -> s{_grrsNextShardIterator = a}); -- | The number of milliseconds the GetRecords response is from the tip of -- the stream, indicating how far behind current time the consumer is. A -- value of zero indicates record processing is caught up, and there are no -- new records to process at this moment. grrsMillisBehindLatest :: Lens' GetRecordsResponse (Maybe Natural) grrsMillisBehindLatest = lens _grrsMillisBehindLatest (\ s a -> s{_grrsMillisBehindLatest = a}) . mapping _Nat; -- | The response status code. grrsResponseStatus :: Lens' GetRecordsResponse Int grrsResponseStatus = lens _grrsResponseStatus (\ s a -> s{_grrsResponseStatus = a}); -- | The data records retrieved from the shard. grrsRecords :: Lens' GetRecordsResponse [Record] grrsRecords = lens _grrsRecords (\ s a -> s{_grrsRecords = a}) . _Coerce;