Kinesis / Client / create_channel

create_channel¶

Kinesis.Client.create_channel(**kwargs)¶

Creates a channel that delivers records from a Kinesis data stream to a destination. A channel reads records from the specified stream and writes them to streaming tables on Apache Iceberg (Amazon S3 Tables) or to a general purpose Amazon S3 bucket.

You must specify either S3DestinationConfiguration or S3TablesDestinationConfiguration, but not both.

To use this operation, you must have permission to pass the specified service execution IAM role to Amazon Kinesis Data Streams (the iam:PassRole permission on that role).

Creating a channel is an asynchronous operation. Upon receiving the request, Amazon Kinesis Data Streams returns immediately with the channel in the CREATING state. After provisioning is complete, Amazon Kinesis Data Streams sets the state to ACTIVE. You can use DescribeChannel to check the current state.

This operation is only supported for data streams with the on-demand capacity mode.

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.create_channel(
    ChannelName='string',
    ServiceExecutionRoleARN='string',
    StreamConfigurationList=[
        {
            'StreamARN': 'string',
            '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'
    },
    Tags={
        'string': 'string'
    },
    LoggingConfiguration={
        'CloudWatchLogs': {
            'Enabled': True|False,
            'LogGroupName': 'string',
            'LogStreamName': 'string'
        }
    }
)

Parameters:

ChannelName (string) –
[REQUIRED]

The name of the channel. The name is unique within your Amazon Web Services account and Amazon Web Services Region.
ServiceExecutionRoleARN (string) –
[REQUIRED]

The Amazon Resource Name (ARN) of the IAM role that Amazon Kinesis Data Streams assumes to write records to the destination.
StreamConfigurationList (list) –
[REQUIRED]

The source stream configuration for the channel. Currently, one stream is supported per channel.
- (dict) –
  
  Specifies the source stream and record configuration when creating a channel.
  - StreamARN (string) – [REQUIRED]
    
    The Amazon Resource Name (ARN) of the source Kinesis data stream.
  - RecordConfiguration (dict) – [REQUIRED]
    
    The record format configuration for the source stream.
    - RecordFormatType (string) – [REQUIRED]
      
      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. You must specify either S3DestinationConfiguration or S3TablesDestinationConfiguration, but not both.
- DataFreshnessInSeconds (integer) –
  
  The maximum age, in seconds, of undelivered data. Valid range is 300 to 900 seconds (5 to 15 minutes). The default value is 300 seconds.
- DeadLetterQueueS3Configuration (dict) –
  
  The dead-letter queue configuration for records that cannot be delivered. Optional for general purpose Amazon S3 destinations. If not specified, it defaults to the destination bucket with an error prefix.
  - BucketARN (string) – [REQUIRED]
    
    The Amazon Resource Name (ARN) of the dead-letter queue Amazon S3 bucket.
  - ExpectedBucketOwner (string) – [REQUIRED]
    
    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) – [REQUIRED]
  
  The Amazon S3 storage configuration for the channel.
  - BucketARN (string) – [REQUIRED]
    
    The Amazon Resource Name (ARN) of the destination Amazon S3 bucket.
  - ExpectedBucketOwner (string) – [REQUIRED]
    
    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) – [REQUIRED]
    
    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. You must specify either S3DestinationConfiguration or S3TablesDestinationConfiguration, but not both.
- DataFreshnessInSeconds (integer) –
  
  The maximum age, in seconds, of undelivered data. Valid range is 300 to 900 seconds (5 to 15 minutes). The default value is 300 seconds.
- DeadLetterQueueS3Configuration (dict) – [REQUIRED]
  
  The dead-letter queue configuration for records that cannot be delivered. Required for streaming table destinations.
  - BucketARN (string) – [REQUIRED]
    
    The Amazon Resource Name (ARN) of the dead-letter queue Amazon S3 bucket.
  - ExpectedBucketOwner (string) – [REQUIRED]
    
    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) – [REQUIRED]
  
  The list of streaming table configurations. Currently, one table is supported per channel.
  - (dict) –
    
    Specifies a destination streaming table on Apache Iceberg.
    - TableBucketARN (string) – [REQUIRED]
      
      The Amazon Resource Name (ARN) of the Amazon S3 table bucket.
    - Namespace (string) – [REQUIRED]
      
      The namespace (database) of the destination table.
    - TableName (string) – [REQUIRED]
      
      The name of the destination table. Amazon Kinesis Data Streams creates this table in the specified table bucket.
    - CompressionType (string) – [REQUIRED]
      
      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) – [REQUIRED]
        
        The list of partition fields.
        
        (dict) –
        
        Specifies a single partition field.
        
        Transform (string) – [REQUIRED]
        
        The partition transform to apply. The only valid value is TIME_HOUR.
        
        SourceName (string) – [REQUIRED]
        
        The name of the source column used for partitioning. This column must be of the timestamptz type.
EncryptionConfiguration (dict) –
The server-side encryption configuration that uses an Amazon Web Services KMS key to encrypt data delivered to the destination.
- EncryptionType (string) – [REQUIRED]
  
  The encryption type. The only valid value is KMS.
- KeyId (string) – [REQUIRED]
  
  The identifier of the customer managed Amazon Web Services KMS key. You cannot use the Amazon Kinesis Data Streams service key ( aws/kinesis).
Tags (dict) –
A set of key-value pairs to assign to the channel. A tag consists of a required key and an optional value.
- (string) –
  - (string) –
LoggingConfiguration (dict) –
The Amazon CloudWatch Logs configuration for the channel.
- CloudWatchLogs (dict) – [REQUIRED]
  
  The Amazon CloudWatch Logs settings for the channel.
  - Enabled (boolean) – [REQUIRED]
    
    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.

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.ResourceInUseException
Kinesis.Client.exceptions.ResourceNotFoundException
Kinesis.Client.exceptions.LimitExceededException
Kinesis.Client.exceptions.InvalidArgumentException
Kinesis.Client.exceptions.KMSDisabledException
Kinesis.Client.exceptions.KMSInvalidStateException
Kinesis.Client.exceptions.KMSAccessDeniedException
Kinesis.Client.exceptions.KMSNotFoundException
Kinesis.Client.exceptions.KMSOptInRequired
Kinesis.Client.exceptions.KMSThrottlingException
Kinesis.Client.exceptions.AccessDeniedException