Kinesis / Client / describe_channel

describe_channel¶

Kinesis.Client.describe_channel(**kwargs)¶

Describes the specified channel, including its configuration and current status.

Use this operation to verify that a channel reached the ACTIVE state after creation, or to diagnose a channel in the FAILED state by reading the ChannelStatusReason.

This operation has a call limit of 5 transactions per second (TPS) for each Amazon Web Services account. Exceeding 5 TPS results in a LimitExceededException.

Request Syntax

response = client.describe_channel(
    ChannelARN='string'
)

Parameters:

ChannelARN (string) –

[REQUIRED]

The Amazon Resource Name (ARN) of the channel to describe.

Return type:

dict

Returns:

Response Syntax

{
    'ChannelDescription': {
        'ChannelName': 'string',
        'ChannelARN': 'string',
        'ChannelId': 'string',
        'ChannelStatus': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING'|'FAILED',
        'ChannelStatusReason': 'string',
        'ChannelCreationTimestamp': datetime(2015, 1, 1),
        'ServiceExecutionRoleARN': 'string',
        'StreamConfigurationList': [
            {
                'StreamARN': 'string',
                'StreamCreationTimestamp': datetime(2015, 1, 1),
                'RecordConfiguration': {
                    'RecordFormatType': 'GSR_JSON'|'JSON'|'STRING'|'BYTE_ARRAY',
                    'GSRSchemaARN': 'string'
                }
            },
        ],
        'S3DestinationConfiguration': {
            'DataFreshnessInSeconds': 123,
            'DeadLetterQueueS3Configuration': {
                'BucketARN': 'string',
                'ExpectedBucketOwner': 'string',
                'ErrorOutputPrefix': 'string'
            },
            'StorageConfiguration': {
                'BucketARN': 'string',
                'ExpectedBucketOwner': 'string',
                'OutputKeyTemplate': 'string',
                'StorageClass': 'STANDARD'|'INTELLIGENT_TIERING'|'GLACIER_IR',
                'CompressionType': 'NONE'|'GZIP'|'ZSTD'
            }
        },
        'S3TablesDestinationConfiguration': {
            'DataFreshnessInSeconds': 123,
            'DeadLetterQueueS3Configuration': {
                'BucketARN': 'string',
                'ExpectedBucketOwner': 'string',
                'ErrorOutputPrefix': 'string'
            },
            'S3TablesConfigurationList': [
                {
                    'TableBucketARN': 'string',
                    'Namespace': 'string',
                    'TableName': 'string',
                    'CompressionType': 'NONE'|'ZSTD'|'SNAPPY',
                    'PartitionSpec': {
                        'PartitionFields': [
                            {
                                'Transform': 'TIME_HOUR',
                                'SourceName': 'string'
                            },
                        ]
                    }
                },
            ]
        },
        'EncryptionConfiguration': {
            'EncryptionType': 'KMS',
            'KeyId': 'string'
        },
        'LoggingConfiguration': {
            'CloudWatchLogs': {
                'Enabled': True|False,
                'LogGroupName': 'string',
                'LogStreamName': 'string'
            }
        }
    }
}

Response Structure

(dict) –
- ChannelDescription (dict) –
  
  The configuration and current status of the channel.
  - ChannelName (string) –
    
    The name of the channel.
  - ChannelARN (string) –
    
    The Amazon Resource Name (ARN) of the channel.
  - ChannelId (string) –
    
    The unique identifier of the channel.
  - ChannelStatus (string) –
    
    The current status of the channel. Valid values:
    - CREATING - The channel is being created.
    - ACTIVE - The channel is ready to deliver records.
    - UPDATING - The channel configuration is being updated.
    - DELETING - The channel is being deleted.
    - FAILED - See ChannelStatusReason for the failure cause.
  - ChannelStatusReason (string) –
    
    A message describing the reason for a FAILED status.
  - ChannelCreationTimestamp (datetime) –
    
    The time at which the channel was created.
  - ServiceExecutionRoleARN (string) –
    
    The Amazon Resource Name (ARN) of the IAM role that Amazon Kinesis Data Streams assumes to write records to the destination.
  - StreamConfigurationList (list) –
    
    The source stream configuration for the channel.
    - (dict) –
      
      Describes the source stream of a channel.
      - StreamARN (string) –
        
        The Amazon Resource Name (ARN) of the source Kinesis data stream.
      - StreamCreationTimestamp (datetime) –
        
        The time at which the source stream was created.
      - RecordConfiguration (dict) –
        
        The record format configuration for the source stream.
        
        RecordFormatType (string) –
        
        The format of records on the source stream. Valid values:
        
        GSR_JSON - Supported only for streaming table (Amazon S3 Tables) destinations.
        
        JSON - Supported for both general purpose Amazon S3 and streaming table destinations.
        
        STRING - Supported only for general purpose Amazon S3 destinations.
        
        BYTE_ARRAY - Supported only for general purpose Amazon S3 destinations.
        
        GSRSchemaARN (string) –
        
        The Amazon Resource Name (ARN) of the Amazon Web Services Glue Schema Registry schema used to validate records. Required when the channel destination is a streaming table (Amazon S3 Tables), for both the JSON and GSR_JSON record formats.
  - S3DestinationConfiguration (dict) –
    
    The configuration for delivery to a general purpose Amazon S3 bucket. Present only when the channel destination is a general purpose Amazon S3 bucket.
    - DataFreshnessInSeconds (integer) –
      
      The maximum age, in seconds, of undelivered data.
    - DeadLetterQueueS3Configuration (dict) –
      
      The dead-letter queue configuration for records that cannot be delivered.
      - BucketARN (string) –
        
        The Amazon Resource Name (ARN) of the dead-letter queue Amazon S3 bucket.
      - ExpectedBucketOwner (string) –
        
        The Amazon Web Services account ID of the expected owner of the dead-letter queue bucket.
      - ErrorOutputPrefix (string) –
        
        The Amazon S3 key prefix for error records.
    - StorageConfiguration (dict) –
      
      The Amazon S3 storage configuration for the channel.
      - BucketARN (string) –
        
        The Amazon Resource Name (ARN) of the destination Amazon S3 bucket.
      - ExpectedBucketOwner (string) –
        
        The Amazon Web Services account ID of the expected owner of the destination bucket. This value helps prevent delivery to an unintended bucket if ownership changes.
      - OutputKeyTemplate (string) –
        
        The template used to construct the Amazon S3 object key for delivered objects. If not specified, a default template is used.
      - StorageClass (string) –
        
        The Amazon S3 storage class for delivered objects. Valid values:
        
        STANDARD - Default storage class for frequently accessed data. (default)
        
        INTELLIGENT_TIERING - Automatically moves objects to the most cost-effective access tier based on usage patterns.
        
        GLACIER_IR - Low-cost storage for rarely accessed data that requires millisecond retrieval.
      - CompressionType (string) –
        
        The compression applied to delivered objects. Valid values:
        
        NONE - No compression.
        
        GZIP - gzip compression.
        
        ZSTD - Zstandard compression.
  - S3TablesDestinationConfiguration (dict) –
    
    The configuration for delivery to streaming tables on Apache Iceberg in Amazon S3 Tables. Present only when the channel destination is a streaming table.
    - DataFreshnessInSeconds (integer) –
      
      The maximum age, in seconds, of undelivered data.
    - DeadLetterQueueS3Configuration (dict) –
      
      The dead-letter queue configuration for records that cannot be delivered.
      - BucketARN (string) –
        
        The Amazon Resource Name (ARN) of the dead-letter queue Amazon S3 bucket.
      - ExpectedBucketOwner (string) –
        
        The Amazon Web Services account ID of the expected owner of the dead-letter queue bucket.
      - ErrorOutputPrefix (string) –
        
        The Amazon S3 key prefix for error records.
    - S3TablesConfigurationList (list) –
      
      The list of streaming table configurations.
      - (dict) –
        
        Specifies a destination streaming table on Apache Iceberg.
        
        TableBucketARN (string) –
        
        The Amazon Resource Name (ARN) of the Amazon S3 table bucket.
        
        Namespace (string) –
        
        The namespace (database) of the destination table.
        
        TableName (string) –
        
        The name of the destination table. Amazon Kinesis Data Streams creates this table in the specified table bucket.
        
        CompressionType (string) –
        
        The compression applied to Parquet data files. Valid values:
        
        NONE - No compression.
        
        ZSTD - Zstandard compression.
        
        SNAPPY - Snappy compression.
        
        PartitionSpec (dict) –
        
        The partitioning specification for the destination table.
        
        PartitionFields (list) –
        
        The list of partition fields.
        
        (dict) –
        
        Specifies a single partition field.
        
        Transform (string) –
        
        The partition transform to apply. The only valid value is TIME_HOUR.
        
        SourceName (string) –
        
        The name of the source column used for partitioning. This column must be of the timestamptz type.
  - EncryptionConfiguration (dict) –
    
    The server-side encryption configuration for the channel.
    - EncryptionType (string) –
      
      The encryption type. The only valid value is KMS.
    - KeyId (string) –
      
      The identifier of the customer managed Amazon Web Services KMS key. You cannot use the Amazon Kinesis Data Streams service key ( aws/kinesis).
  - LoggingConfiguration (dict) –
    
    The Amazon CloudWatch Logs configuration for the channel.
    - CloudWatchLogs (dict) –
      
      The Amazon CloudWatch Logs settings for the channel.
      - Enabled (boolean) –
        
        Specifies whether logging to Amazon CloudWatch Logs is enabled.
      - LogGroupName (string) –
        
        The name of the Amazon CloudWatch Logs log group. Defaults to /aws/kinesis/{channelName}/{channelId}.
      - LogStreamName (string) –
        
        The name of the Amazon CloudWatch Logs log stream. Defaults to DestinationDelivery.

Exceptions

Kinesis.Client.exceptions.ValidationException
Kinesis.Client.exceptions.ResourceNotFoundException
Kinesis.Client.exceptions.LimitExceededException
Kinesis.Client.exceptions.InvalidArgumentException
Kinesis.Client.exceptions.AccessDeniedException