describe-channel¶

Description¶

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 .

Synopsis¶

  describe-channel
--channel-arn <value>
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
[--cli-error-format <value>]

Options¶

--channel-arn (string) [required]

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

Constraints:

min: 1

max: 2048

pattern: arn:aws.*:kinesis:.*:\d{12}:channel/\S+

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

Global Options¶

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

json
text
table
yaml
yaml-stream
off

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

on
off
auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--cli-binary-format (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob fileb:// will always be treated as binary and use the file contents directly regardless of the cli-binary-format setting. When using file:// the file contents will need to properly formatted for the configured cli-binary-format.

base64
raw-in-base64-out

--no-cli-pager (boolean)

Disable cli pager for output.

--cli-auto-prompt (boolean)

Automatically prompt for CLI input parameters.

--no-cli-auto-prompt (boolean)

Disable automatically prompt for CLI input parameters.

--cli-error-format (string)

The formatting style for error output. By default, errors are displayed in enhanced format.

legacy
json
yaml
text
table
enhanced

Output¶

ChannelDescription -> (structure)

The configuration and current status of the channel.

ChannelName -> (string) [required]

The name of the channel.

Constraints:

min: 1

max: 128

pattern: [a-zA-Z0-9_.-]+

ChannelARN -> (string) [required]

The Amazon Resource Name (ARN) of the channel.

Constraints:

min: 1

max: 2048

pattern: arn:aws.*:kinesis:.*:\d{12}:channel/\S+

ChannelId -> (string) [required]

The unique identifier of the channel.

Constraints:

min: 1

max: 64

ChannelStatus -> (string) [required]

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.

Possible values:

CREATING

ACTIVE

UPDATING

DELETING

FAILED

ChannelStatusReason -> (string)

A message describing the reason for a FAILED status.

Constraints:

min: 1

max: 2048

ChannelCreationTimestamp -> (timestamp) [required]

The time at which the channel was created.

ServiceExecutionRoleARN -> (string) [required]

The Amazon Resource Name (ARN) of the IAM role that Amazon Kinesis Data Streams assumes to write records to the destination.

Constraints:

min: 1

max: 512

pattern: arn:aws[-a-z0-9]*:iam::\d{12}:role/[a-zA-Z_0-9+=,.@\-_/]+

StreamConfigurationList -> (list) [required]

The source stream configuration for the channel.

Constraints:

min: 1

max: 10000

(structure)

Describes the source stream of a channel.

StreamARN -> (string) [required]

The Amazon Resource Name (ARN) of the source Kinesis data stream.

Constraints:

min: 1

max: 2048

pattern: arn:aws.*:kinesis:.*:\d{12}:stream/\S+

StreamCreationTimestamp -> (timestamp) [required]

The time at which the source stream was created.

RecordConfiguration -> (structure) [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.

Possible values:

GSR_JSON

JSON

STRING

BYTE_ARRAY

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.

Constraints:

min: 1

max: 512

pattern: arn:aws[-a-z0-9]*:glue:[-a-z0-9]+:\d{12}:schema/[-a-zA-Z0-9_$#.]+/[-a-zA-Z0-9_$#.]+

S3DestinationConfiguration -> (structure)

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) [required]

The maximum age, in seconds, of undelivered data.

DeadLetterQueueS3Configuration -> (structure) [required]

The dead-letter queue configuration for records that cannot be delivered.

BucketARN -> (string) [required]

The Amazon Resource Name (ARN) of the dead-letter queue Amazon S3 bucket.

Constraints:

min: 1

max: 2048

pattern: arn:aws[-a-z0-9]*:s3:::[a-z0-9._-]{3,63}

ExpectedBucketOwner -> (string) [required]

The Amazon Web Services account ID of the expected owner of the dead-letter queue bucket.

Constraints:

min: 12

max: 12

pattern: \d{12}

ErrorOutputPrefix -> (string)

The Amazon S3 key prefix for error records.

Constraints:

min: 1

max: 512

pattern: [0-9A-Za-z!\-_'.*()\/]+

StorageConfiguration -> (structure) [required]

The Amazon S3 storage configuration for the channel.

BucketARN -> (string) [required]

The Amazon Resource Name (ARN) of the destination Amazon S3 bucket.

Constraints:

min: 1

max: 2048

pattern: arn:aws[-a-z0-9]*:s3:::[a-z0-9._-]{3,63}

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.

Constraints:

min: 12

max: 12

pattern: \d{12}

OutputKeyTemplate -> (string)

The template used to construct the Amazon S3 object key for delivered objects. If not specified, a default template is used.

Constraints:

min: 1

max: 1024

pattern: [0-9A-Za-z!\-_'.*()\/=:{}]+

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.

Possible values:

STANDARD

INTELLIGENT_TIERING

GLACIER_IR

CompressionType -> (string) [required]

The compression applied to delivered objects. Valid values:

NONE - No compression.

GZIP - gzip compression.

ZSTD - Zstandard compression.

Possible values:

NONE

GZIP

ZSTD

S3TablesDestinationConfiguration -> (structure)

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) [required]

The maximum age, in seconds, of undelivered data.

DeadLetterQueueS3Configuration -> (structure) [required]

The dead-letter queue configuration for records that cannot be delivered.

BucketARN -> (string) [required]

The Amazon Resource Name (ARN) of the dead-letter queue Amazon S3 bucket.

Constraints:

min: 1

max: 2048

pattern: arn:aws[-a-z0-9]*:s3:::[a-z0-9._-]{3,63}

ExpectedBucketOwner -> (string) [required]

The Amazon Web Services account ID of the expected owner of the dead-letter queue bucket.

Constraints:

min: 12

max: 12

pattern: \d{12}

ErrorOutputPrefix -> (string)

The Amazon S3 key prefix for error records.

Constraints:

min: 1

max: 512

pattern: [0-9A-Za-z!\-_'.*()\/]+

S3TablesConfigurationList -> (list) [required]

The list of streaming table configurations.

Constraints:

min: 1

max: 10000

(structure)

Specifies a destination streaming table on Apache Iceberg.

TableBucketARN -> (string) [required]

The Amazon Resource Name (ARN) of the Amazon S3 table bucket.

Constraints:

min: 1

max: 2048

pattern: arn:aws[-a-z0-9]*:s3tables:[-a-z0-9]+:\d{12}:bucket/[a-z0-9_-]{3,63}

Namespace -> (string) [required]

The namespace (database) of the destination table.

Constraints:

min: 1

max: 255

pattern: [0-9a-z_]+

TableName -> (string) [required]

The name of the destination table. Amazon Kinesis Data Streams creates this table in the specified table bucket.

Constraints:

min: 1

max: 255

pattern: [0-9a-z_]+

CompressionType -> (string) [required]

The compression applied to Parquet data files. Valid values:

NONE - No compression.

ZSTD - Zstandard compression.

SNAPPY - Snappy compression.

Possible values:

NONE

ZSTD

SNAPPY

PartitionSpec -> (structure)

The partitioning specification for the destination table.

PartitionFields -> (list) [required]

The list of partition fields.

Constraints:

min: 1

max: 10

(structure)

Specifies a single partition field.

Transform -> (string) [required]

The partition transform to apply. The only valid value is TIME_HOUR .

Possible values:

TIME_HOUR

SourceName -> (string) [required]

The name of the source column used for partitioning. This column must be of the timestamptz type.

Constraints:

min: 1

max: 255

pattern: [a-zA-Z0-9\.\_]+

EncryptionConfiguration -> (structure)

The server-side encryption configuration for the channel.

EncryptionType -> (string) [required]

The encryption type. The only valid value is KMS .

Possible values:

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 ).

Constraints:

min: 1

max: 2048

LoggingConfiguration -> (structure) [required]

The Amazon CloudWatch Logs configuration for the channel.

CloudWatchLogs -> (structure) [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} .

Constraints:

min: 1

max: 512

pattern: [\.\-_/#A-Za-z0-9]+

LogStreamName -> (string)

The name of the Amazon CloudWatch Logs log stream. Defaults to DestinationDelivery .

Constraints:

min: 1

max: 512

pattern: [^:*]*

Table of Contents

Feedback

User Guide