Kinesis / Client / update_channel

update_channel¶

Kinesis.Client.update_channel(**kwargs)¶

Updates the data freshness interval or the Amazon CloudWatch Logs configuration of an existing channel. You cannot change the destination, source stream, record format, schema, encryption configuration, or service execution role of an existing channel. To change any other setting, delete the channel and create a new one.

Updating a channel is an asynchronous operation. Upon receiving the request, Amazon Kinesis Data Streams sets the channel to the UPDATING state and returns immediately. After the change is applied, Amazon Kinesis Data Streams sets the channel back to the ACTIVE state.

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.update_channel(
    ChannelARN='string',
    S3DestinationConfiguration={
        'DataFreshnessInSeconds': 123
    },
    S3TablesDestinationConfiguration={
        'DataFreshnessInSeconds': 123
    },
    LoggingConfiguration={
        'CloudWatchLogs': {
            'Enabled': True|False,
            'LogGroupName': 'string',
            'LogStreamName': 'string'
        }
    }
)

Parameters:

ChannelARN (string) –
[REQUIRED]

The Amazon Resource Name (ARN) of the channel to update.
S3DestinationConfiguration (dict) –
The updated configuration for a general purpose Amazon S3 destination. Only DataFreshnessInSeconds can be updated.
- DataFreshnessInSeconds (integer) – [REQUIRED]
  
  The maximum age, in seconds, of undelivered data. Valid range is 300 to 900 seconds (5 to 15 minutes).
S3TablesDestinationConfiguration (dict) –
The updated configuration for a streaming table destination. Only DataFreshnessInSeconds can be updated.
- DataFreshnessInSeconds (integer) – [REQUIRED]
  
  The maximum age, in seconds, of undelivered data. Valid range is 300 to 900 seconds (5 to 15 minutes).
LoggingConfiguration (dict) –
The updated Amazon CloudWatch Logs configuration for the channel.
- CloudWatchLogs (dict) – [REQUIRED]
  
  The updated 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.
  - LogStreamName (string) –
    
    The name of the Amazon CloudWatch Logs log stream.

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 updated 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.AccessDeniedException