:doc:`IoTAnalytics <../../iotanalytics>` / Client / describe_channel

****************
describe_channel
****************



.. py:method:: IoTAnalytics.Client.describe_channel(**kwargs)

  

  Retrieves information about a channel.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/iotanalytics-2017-11-27/DescribeChannel>`_  


  **Request Syntax**
  ::

    response = client.describe_channel(
        channelName='string',
        includeStatistics=True|False
    )
    
  :type channelName: string
  :param channelName: **[REQUIRED]** 

    The name of the channel whose information is retrieved.

    

  
  :type includeStatistics: boolean
  :param includeStatistics: 

    If true, additional statistical information about the channel is included in the response. This feature can't be used with a channel whose S3 storage is customer-managed.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'channel': {
              'name': 'string',
              'storage': {
                  'serviceManagedS3': {},
                  'customerManagedS3': {
                      'bucket': 'string',
                      'keyPrefix': 'string',
                      'roleArn': 'string'
                  }
              },
              'arn': 'string',
              'status': 'CREATING'|'ACTIVE'|'DELETING',
              'retentionPeriod': {
                  'unlimited': True|False,
                  'numberOfDays': 123
              },
              'creationTime': datetime(2015, 1, 1),
              'lastUpdateTime': datetime(2015, 1, 1),
              'lastMessageArrivalTime': datetime(2015, 1, 1)
          },
          'statistics': {
              'size': {
                  'estimatedSizeInBytes': 123.0,
                  'estimatedOn': datetime(2015, 1, 1)
              }
          }
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **channel** *(dict) --* 

        An object that contains information about the channel.

        
        

        - **name** *(string) --* 

          The name of the channel.

          
        

        - **storage** *(dict) --* 

          Where channel data is stored. You can choose one of ``serviceManagedS3`` or ``customerManagedS3`` storage. If not specified, the default is ``serviceManagedS3``. You can't change this storage option after the channel is created.

          
          

          - **serviceManagedS3** *(dict) --* 

            Used to store channel data in an S3 bucket managed by IoT Analytics. You can't change the choice of S3 storage after the data store is created.

            
        
          

          - **customerManagedS3** *(dict) --* 

            Used to store channel data in an S3 bucket that you manage. If customer managed storage is selected, the ``retentionPeriod`` parameter is ignored. You can't change the choice of S3 storage after the data store is created.

            
            

            - **bucket** *(string) --* 

              The name of the S3 bucket in which channel data is stored.

              
            

            - **keyPrefix** *(string) --* 

              (Optional) The prefix used to create the keys of the channel data objects. Each object in an S3 bucket has a key that is its unique identifier in the bucket. Each object in a bucket has exactly one key. The prefix must end with a forward slash (/).

              
            

            - **roleArn** *(string) --* 

              The ARN of the role that grants IoT Analytics permission to interact with your Amazon S3 resources.

              
        
      
        

        - **arn** *(string) --* 

          The ARN of the channel.

          
        

        - **status** *(string) --* 

          The status of the channel.

          
        

        - **retentionPeriod** *(dict) --* 

          How long, in days, message data is kept for the channel.

          
          

          - **unlimited** *(boolean) --* 

            If true, message data is kept indefinitely.

            
          

          - **numberOfDays** *(integer) --* 

            The number of days that message data is kept. The ``unlimited`` parameter must be false.

            
      
        

        - **creationTime** *(datetime) --* 

          When the channel was created.

          
        

        - **lastUpdateTime** *(datetime) --* 

          When the channel was last updated.

          
        

        - **lastMessageArrivalTime** *(datetime) --* 

          The last time when a new message arrived in the channel.

           

          IoT Analytics updates this value at most once per minute for one channel. Hence, the ``lastMessageArrivalTime`` value is an approximation.

           

          This feature only applies to messages that arrived in the data store after October 23, 2020.

          
    
      

      - **statistics** *(dict) --* 

        Statistics about the channel. Included if the ``includeStatistics`` parameter is set to ``true`` in the request.

        
        

        - **size** *(dict) --* 

          The estimated size of the channel.

          
          

          - **estimatedSizeInBytes** *(float) --* 

            The estimated size of the resource, in bytes.

            
          

          - **estimatedOn** *(datetime) --* 

            The time when the estimate of the size of the resource was made.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`IoTAnalytics.Client.exceptions.InvalidRequestException`

  
  *   :py:class:`IoTAnalytics.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`IoTAnalytics.Client.exceptions.InternalFailureException`

  
  *   :py:class:`IoTAnalytics.Client.exceptions.ServiceUnavailableException`

  
  *   :py:class:`IoTAnalytics.Client.exceptions.ThrottlingException`

  