@aws-sdk/client-kinesis 3.1137.0 → 3.1139.0

package/dist-types/commands/UpdateStreamRecordDistributionStrategyCommand.d.ts

@@ -0,0 +1,127 @@
+import type { MetadataBearer as __MetadataBearer } from "@smithy/types";
+import type { UpdateStreamRecordDistributionStrategyInput } from "../models/models_0";
+/**
+ * @public
+ */
+export type { __MetadataBearer };
+/**
+ * @public
+ *
+ * The input for {@link UpdateStreamRecordDistributionStrategyCommand}.
+ */
+export interface UpdateStreamRecordDistributionStrategyCommandInput extends UpdateStreamRecordDistributionStrategyInput {
+}
+/**
+ * @public
+ *
+ * The output of {@link UpdateStreamRecordDistributionStrategyCommand}.
+ */
+export interface UpdateStreamRecordDistributionStrategyCommandOutput extends __MetadataBearer {
+}
+declare const UpdateStreamRecordDistributionStrategyCommand_base: {
+    new (input: UpdateStreamRecordDistributionStrategyCommandInput): import("@smithy/core/client").CommandImpl<UpdateStreamRecordDistributionStrategyCommandInput, UpdateStreamRecordDistributionStrategyCommandOutput, import("..").KinesisClientResolvedConfig, import("..").ServiceInputTypes, import("..").ServiceOutputTypes>;
+    new (input: UpdateStreamRecordDistributionStrategyCommandInput): import("@smithy/core/client").CommandImpl<UpdateStreamRecordDistributionStrategyCommandInput, UpdateStreamRecordDistributionStrategyCommandOutput, import("..").KinesisClientResolvedConfig, import("..").ServiceInputTypes, import("..").ServiceOutputTypes>;
+    getEndpointParameterInstructions(): import("@smithy/types").EndpointParameterInstructions;
+};
+/**
+ * <p>Updates the record distribution strategy for the specified Amazon Kinesis Data Streams
+ *             on-demand data stream. The record distribution strategy determines how Amazon Kinesis
+ *             Data Streams distributes records across the shards in a stream.</p>
+ *          <note>
+ *             <p>You must specify the stream using the <code>StreamARN</code> parameter.</p>
+ *          </note>
+ *          <p>The record distribution strategy is a stream-level setting. You can switch between the
+ *             following strategies at any time, and the change takes effect immediately without
+ *             downtime, data loss, or disruption to producer or consumer applications:</p>
+ *          <ul>
+ *             <li>
+ *                <p>
+ *                   <code>AUTO</code> – Amazon Kinesis Data Streams distributes records evenly
+ *                     across shards using service-managed algorithms, and ignores any partition key
+ *                     and <code>ExplicitHashKey</code> that a producer provides. Use this strategy for
+ *                     stateless workloads that do not require partition-key ordering.</p>
+ *             </li>
+ *             <li>
+ *                <p>
+ *                   <code>USER_PARTITION_KEY</code> – Producers must provide a partition key, and
+ *                     Amazon Kinesis Data Streams uses the partition key to determine shard placement.
+ *                     Records that share a partition key are sent to the same shard. This is the
+ *                     default strategy.</p>
+ *             </li>
+ *          </ul>
+ *          <p>This operation is only supported for data streams that use the on-demand capacity
+ *             mode. Provisioned capacity mode streams do not support the record distribution strategy
+ *             setting. Attempting to set <code>AUTO</code> on a provisioned stream results in an
+ *             <code>InvalidArgumentException</code>.</p>
+ *          <p>New records that arrive after the change are distributed according to the new
+ *             strategy. Records already in the stream keep their original shard assignments and are
+ *             not redistributed.</p>
+ * @example
+ * Use a bare-bones client and the command you need to make an API call.
+ * ```javascript
+ * import { KinesisClient, UpdateStreamRecordDistributionStrategyCommand } from "@aws-sdk/client-kinesis"; // ES Modules import
+ * // const { KinesisClient, UpdateStreamRecordDistributionStrategyCommand } = require("@aws-sdk/client-kinesis"); // CommonJS import
+ * // import type { KinesisClientConfig } from "@aws-sdk/client-kinesis";
+ * const config = {}; // type is KinesisClientConfig
+ * const client = new KinesisClient(config);
+ * const input = { // UpdateStreamRecordDistributionStrategyInput
+ *   StreamARN: "STRING_VALUE", // required
+ *   StreamId: "STRING_VALUE",
+ *   RecordDistributionStrategy: "AUTO" || "USER_PARTITION_KEY", // required
+ * };
+ * const command = new UpdateStreamRecordDistributionStrategyCommand(input);
+ * const response = await client.send(command);
+ * // {};
+ *
+ * ```
+ *
+ * @param UpdateStreamRecordDistributionStrategyCommandInput - {@link UpdateStreamRecordDistributionStrategyCommandInput}
+ * @returns {@link UpdateStreamRecordDistributionStrategyCommandOutput}
+ * @see {@link UpdateStreamRecordDistributionStrategyCommandInput} for command's `input` shape.
+ * @see {@link UpdateStreamRecordDistributionStrategyCommandOutput} for command's `response` shape.
+ * @see {@link KinesisClientResolvedConfig | config} for KinesisClient's `config` shape.
+ *
+ * @throws {@link AccessDeniedException} (client fault)
+ *  <p>Specifies that you do not have the permissions required to perform this
+ *             operation.</p>
+ *
+ * @throws {@link InvalidArgumentException} (client fault)
+ *  <p>A specified parameter exceeds its restrictions, is not supported, or can't be used.
+ *             For more information, see the returned message.</p>
+ *
+ * @throws {@link LimitExceededException} (client fault)
+ *  <p>The requested resource exceeds the maximum number allowed, or the number of concurrent
+ *             stream requests exceeds the maximum number allowed. </p>
+ *
+ * @throws {@link ResourceInUseException} (client fault)
+ *  <p>The resource is not available for this operation. For successful operation, the
+ *             resource must be in the <code>ACTIVE</code> state.</p>
+ *
+ * @throws {@link ResourceNotFoundException} (client fault)
+ *  <p>The requested resource could not be found. The stream might not be specified
+ *             correctly.</p>
+ *
+ * @throws {@link ValidationException} (client fault)
+ *  <p>Specifies that you tried to invoke this API for a data stream with the on-demand
+ *             capacity mode. This API is only supported for data streams with the provisioned capacity
+ *             mode. </p>
+ *
+ * @throws {@link KinesisServiceException}
+ * <p>Base exception class for all service exceptions from Kinesis service.</p>
+ *
+ *
+ * @public
+ */
+export declare class UpdateStreamRecordDistributionStrategyCommand extends UpdateStreamRecordDistributionStrategyCommand_base {
+    /** @internal type navigation helper, not in runtime. */
+    protected static __types: {
+        api: {
+            input: UpdateStreamRecordDistributionStrategyInput;
+            output: {};
+        };
+        sdk: {
+            input: UpdateStreamRecordDistributionStrategyCommandInput;
+            output: UpdateStreamRecordDistributionStrategyCommandOutput;
+        };
+    };
+}

package/dist-types/commands/index.d.ts

@@ -41,4 +41,5 @@ export * from "./UpdateChannelCommand";
 export * from "./UpdateMaxRecordSizeCommand";
 export * from "./UpdateShardCountCommand";
 export * from "./UpdateStreamModeCommand";
+export * from "./UpdateStreamRecordDistributionStrategyCommand";
 export * from "./UpdateStreamWarmThroughputCommand";

package/dist-types/models/enums.d.ts

@@ -113,6 +113,18 @@ export declare const ConsumerStatus: {
  * @public
  */
 export type ConsumerStatus = (typeof ConsumerStatus)[keyof typeof ConsumerStatus];
+/**
+ * @public
+ * @enum
+ */
+export declare const RecordDistributionStrategy: {
+    readonly AUTO: "AUTO";
+    readonly USER_PARTITION_KEY: "USER_PARTITION_KEY";
+};
+/**
+ * @public
+ */
+export type RecordDistributionStrategy = (typeof RecordDistributionStrategy)[keyof typeof RecordDistributionStrategy];
 /**
  * @public
  * @enum

package/dist-types/models/models_0.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelDestinationType, ChannelEncryptionType, ChannelStatus, ConsumerStatus, EncryptionType, MetricsName, MinimumThroughputBillingCommitmentInputStatus, MinimumThroughputBillingCommitmentOutputStatus, PartitionTransform, RecordFormatType, S3CompressionType, S3StorageClass, S3TablesCompressionType, ScalingType, ShardFilterType, ShardIteratorType, StreamMode, StreamStatus } from "./enums";
+import type { ChannelDestinationType, ChannelEncryptionType, ChannelStatus, ConsumerStatus, EncryptionType, MetricsName, MinimumThroughputBillingCommitmentInputStatus, MinimumThroughputBillingCommitmentOutputStatus, PartitionTransform, RecordDistributionStrategy, RecordFormatType, S3CompressionType, S3StorageClass, S3TablesCompressionType, ScalingType, ShardFilterType, ShardIteratorType, StreamMode, StreamStatus } from "./enums";
 import type { InternalFailureException, KMSAccessDeniedException, KMSDisabledException, KMSInvalidStateException, KMSNotFoundException, KMSOptInRequired, KMSThrottlingException, ResourceInUseException, ResourceNotFoundException } from "./errors";
 /**
  * <p>Represents the input for <code>AddTagsToStream</code>.</p>
@@ -120,7 +120,7 @@ export interface S3StorageConfiguration {
      *          <ul>
      *             <li>
      *                <p>
-     *                   <code>STANDARD</code> - Default storage class for frequently accessed data. (default)</p>
+     *                   <code>STANDARD</code> - The default storage class, for frequently accessed data.</p>
      *             </li>
      *             <li>
      *                <p>
@@ -297,7 +297,7 @@ export interface RecordConfiguration {
      */
     RecordFormatType: RecordFormatType | undefined;
     /**
-     * <p>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 <code>JSON</code> and <code>GSR_JSON</code> record formats.</p>
+     * <p>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.</p>
      * @public
      */
     GSRSchemaARN?: string | undefined;
@@ -401,7 +401,7 @@ export interface ChannelDescription {
      */
     S3TablesDestinationConfiguration?: S3TablesDestinationDescription | undefined;
     /**
-     * <p>The server-side encryption configuration for the channel.</p>
+     * <p>The Amazon Web Services KMS key configuration that Amazon Kinesis Data Streams uses to encrypt data delivered to the channel's destination.</p>
      * @public
      */
     EncryptionConfiguration?: ChannelEncryptionConfiguration | undefined;
@@ -438,7 +438,7 @@ export interface CloudWatchLogsUpdateInput {
  */
 export interface ChannelLoggingUpdateInput {
     /**
-     * <p>The updated Amazon CloudWatch Logs settings for the channel.</p>
+     * <p>The updated Amazon CloudWatch Logs settings, including whether logging is enabled and the target log group and log stream.</p>
      * @public
      */
     CloudWatchLogs: CloudWatchLogsUpdateInput | undefined;
@@ -670,7 +670,7 @@ export interface ConsumerDescription {
  */
 export interface S3DestinationConfiguration {
     /**
-     * <p>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.</p>
+     * <p>The maximum age, in seconds, of undelivered data before the channel delivers it to the destination. The default value is 300 seconds.</p>
      * @public
      */
     DataFreshnessInSeconds?: number | undefined;
@@ -691,7 +691,7 @@ export interface S3DestinationConfiguration {
  */
 export interface S3TablesDestinationConfiguration {
     /**
-     * <p>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.</p>
+     * <p>The maximum age, in seconds, of undelivered data before the channel delivers it to the destination. The default value is 300 seconds.</p>
      * @public
      */
     DataFreshnessInSeconds?: number | undefined;
@@ -726,12 +726,12 @@ export interface CreateChannelInput {
      */
     StreamConfigurationList: ChannelStreamConfiguration[] | undefined;
     /**
-     * <p>The configuration for delivery to a general purpose Amazon S3 bucket. You must specify either <code>S3DestinationConfiguration</code> or <code>S3TablesDestinationConfiguration</code>, but not both.</p>
+     * <p>The configuration for delivery to a general purpose Amazon S3 bucket. Specify this parameter when <code>S3TablesDestinationConfiguration</code> is not specified.</p>
      * @public
      */
     S3DestinationConfiguration?: S3DestinationConfiguration | undefined;
     /**
-     * <p>The configuration for delivery to streaming tables on Apache Iceberg in Amazon S3 Tables. You must specify either <code>S3DestinationConfiguration</code> or <code>S3TablesDestinationConfiguration</code>, but not both.</p>
+     * <p>The configuration for delivery to streaming tables on Apache Iceberg in Amazon S3 Tables. Specify this parameter when <code>S3DestinationConfiguration</code> is not specified.</p>
      * @public
      */
     S3TablesDestinationConfiguration?: S3TablesDestinationConfiguration | undefined;
@@ -756,7 +756,7 @@ export interface CreateChannelInput {
  */
 export interface CreateChannelOutput {
     /**
-     * <p>The configuration and current status of the channel.</p>
+     * <p>The configuration and current status of the channel, including its ARN, destination configuration, and lifecycle state. Immediately after creation, the state is <code>CREATING</code>.</p>
      * @public
      */
     ChannelDescription: ChannelDescription | undefined;
@@ -817,6 +817,31 @@ export interface CreateStreamInput {
      * @public
      */
     MaxRecordSizeInKiB?: number | undefined;
+    /**
+     * <p>The record distribution strategy for the stream, which determines how Amazon Kinesis
+     *             Data Streams distributes records across shards. Specify one of the following
+     *             values:</p>
+     *          <ul>
+     *             <li>
+     *                <p>
+     *                   <code>AUTO</code> – Amazon Kinesis Data Streams distributes records evenly
+     *                     across shards and ignores any partition key and <code>ExplicitHashKey</code>
+     *                     that producers supply. Use this value for stateless workloads that do not
+     *                     require partition-key ordering.</p>
+     *             </li>
+     *             <li>
+     *                <p>
+     *                   <code>USER_PARTITION_KEY</code> – Producers must supply a partition key, which
+     *                     Amazon Kinesis Data Streams uses to determine shard placement. This is the
+     *                     default.</p>
+     *             </li>
+     *          </ul>
+     *          <p>The record distribution strategy is only supported for streams that use the on-demand
+     *             capacity mode. If you do not specify this parameter, the stream uses
+     *             <code>USER_PARTITION_KEY</code>.</p>
+     * @public
+     */
+    RecordDistributionStrategy?: RecordDistributionStrategy | undefined;
 }
 /**
  * <p>Represents the input for <a>DecreaseStreamRetentionPeriod</a>.</p>
@@ -985,7 +1010,7 @@ export interface DescribeChannelInput {
  */
 export interface DescribeChannelOutput {
     /**
-     * <p>The configuration and current status of the channel.</p>
+     * <p>The configuration and current status of the channel, including its ARN, source stream, destination configuration, and lifecycle state.</p>
      * @public
      */
     ChannelDescription: ChannelDescription | undefined;
@@ -1542,6 +1567,15 @@ export interface StreamDescriptionSummary {
      * @public
      */
     ChannelCount?: number | undefined;
+    /**
+     * <p>The record distribution strategy that the stream currently uses. A value of
+     *             <code>AUTO</code> indicates that Amazon Kinesis Data Streams distributes records across
+     *             shards using service-managed algorithms. A value of <code>USER_PARTITION_KEY</code>
+     *             indicates that shard placement is determined by the partition key that producers supply.
+     *             This field is only present for streams that use the on-demand capacity mode.</p>
+     * @public
+     */
+    RecordDistributionStrategy?: RecordDistributionStrategy | undefined;
 }
 /**
  * @public
@@ -1790,9 +1824,13 @@ export interface _Record {
     Data: Uint8Array | undefined;
     /**
      * <p>Identifies which shard in the stream the data record is assigned to.</p>
+     *          <p>For a stream that uses the <code>AUTO</code> record distribution strategy, this value
+     *             is not returned if the producer did not provide a partition key when writing the record.
+     *             If the producer provided a partition key, the original value is returned even though it
+     *             was not used to determine shard placement.</p>
      * @public
      */
-    PartitionKey: string | undefined;
+    PartitionKey?: string | undefined;
     /**
      * <p>The encryption type used on the record. This parameter can be one of the following
      *             values:</p>
@@ -2019,7 +2057,7 @@ export interface ListChannelsInput {
      */
     MaxResults?: number | undefined;
     /**
-     * <p>The pagination token returned by a previous call. Specify this token to retrieve the next page of results. This value is <code>null</code> when there are no more results to return.</p>
+     * <p>The pagination token returned by a previous call. Specify this token to retrieve the next page of results.</p>
      * @public
      */
     NextToken?: string | undefined;
@@ -2562,9 +2600,16 @@ export interface PutRecordInput {
      *             function is used to map partition keys to 128-bit integer values and to map associated
      *             data records to shards. As a result of this hashing mechanism, all data records with the
      *             same partition key map to the same shard within the stream.</p>
+     *          <p>If the stream uses the <code>USER_PARTITION_KEY</code> record distribution strategy
+     *             (the default), a partition key is required. If the stream uses the <code>AUTO</code>
+     *             record distribution strategy, the partition key is optional and any value you provide is
+     *             ignored, along with any <code>ExplicitHashKey</code> you provide. In that case, Amazon
+     *             Kinesis Data Streams distributes the record across shards using service-managed
+     *             algorithms. For more information, see
+     *             <code>UpdateStreamRecordDistributionStrategy</code>.</p>
      * @public
      */
-    PartitionKey: string | undefined;
+    PartitionKey?: string | undefined;
     /**
      * <p>The hash value used to explicitly determine the shard the data record is assigned to
      *             by overriding the partition key hash.</p>
@@ -2659,9 +2704,16 @@ export interface PutRecordsRequestEntry {
      *             function is used to map partition keys to 128-bit integer values and to map associated
      *             data records to shards. As a result of this hashing mechanism, all data records with the
      *             same partition key map to the same shard within the stream.</p>
+     *          <p>If the stream uses the <code>USER_PARTITION_KEY</code> record distribution strategy
+     *             (the default), a partition key is required for each record. If the stream uses the
+     *             <code>AUTO</code> record distribution strategy, the partition key is optional and any
+     *             value you provide is ignored, along with any <code>ExplicitHashKey</code> you provide.
+     *             In that case, Amazon Kinesis Data Streams distributes records across shards using
+     *             service-managed algorithms. For more information, see
+     *             <code>UpdateStreamRecordDistributionStrategy</code>.</p>
      * @public
      */
-    PartitionKey: string | undefined;
+    PartitionKey?: string | undefined;
 }
 /**
  * <p>A <code>PutRecords</code> request.</p>
@@ -3451,7 +3503,7 @@ export interface UpdateAccountSettingsOutput {
  */
 export interface S3DestinationUpdateInput {
     /**
-     * <p>The maximum age, in seconds, of undelivered data. Valid range is 300 to 900 seconds (5 to 15 minutes).</p>
+     * <p>The maximum age, in seconds, of undelivered data before the channel delivers it to the destination.</p>
      * @public
      */
     DataFreshnessInSeconds: number | undefined;
@@ -3462,7 +3514,7 @@ export interface S3DestinationUpdateInput {
  */
 export interface S3TablesDestinationUpdateInput {
     /**
-     * <p>The maximum age, in seconds, of undelivered data. Valid range is 300 to 900 seconds (5 to 15 minutes).</p>
+     * <p>The maximum age, in seconds, of undelivered data before the channel delivers it to the destination.</p>
      * @public
      */
     DataFreshnessInSeconds: number | undefined;
@@ -3477,12 +3529,12 @@ export interface UpdateChannelInput {
      */
     ChannelARN: string | undefined;
     /**
-     * <p>The updated configuration for a general purpose Amazon S3 destination. Only <code>DataFreshnessInSeconds</code> can be updated.</p>
+     * <p>The updated configuration for a general purpose Amazon S3 destination. Specify this parameter when the channel delivers to a general purpose Amazon S3 bucket. Only <code>DataFreshnessInSeconds</code> can be updated.</p>
      * @public
      */
     S3DestinationConfiguration?: S3DestinationUpdateInput | undefined;
     /**
-     * <p>The updated configuration for a streaming table destination. Only <code>DataFreshnessInSeconds</code> can be updated.</p>
+     * <p>The updated configuration for a streaming table destination. Specify this parameter when the channel delivers to streaming tables on Apache Iceberg in Amazon S3 Tables. Only <code>DataFreshnessInSeconds</code> can be updated.</p>
      * @public
      */
     S3TablesDestinationConfiguration?: S3TablesDestinationUpdateInput | undefined;
@@ -3497,7 +3549,7 @@ export interface UpdateChannelInput {
  */
 export interface UpdateChannelOutput {
     /**
-     * <p>The configuration and current status of the updated channel.</p>
+     * <p>The configuration and current status of the channel after the update, including its ARN, destination configuration, and lifecycle state. Immediately after the request, the state is <code>UPDATING</code>.</p>
      * @public
      */
     ChannelDescription: ChannelDescription | undefined;
@@ -3622,6 +3674,41 @@ export interface UpdateStreamModeInput {
      */
     WarmThroughputMiBps?: number | undefined;
 }
+/**
+ * @public
+ */
+export interface UpdateStreamRecordDistributionStrategyInput {
+    /**
+     * <p>The Amazon Resource Name (ARN) of the stream to update.</p>
+     * @public
+     */
+    StreamARN: string | undefined;
+    /**
+     * <p>Not Implemented. Reserved for future use.</p>
+     * @public
+     */
+    StreamId?: string | undefined;
+    /**
+     * <p>The record distribution strategy to apply to the stream. Specify one of the following
+     *             values:</p>
+     *          <ul>
+     *             <li>
+     *                <p>
+     *                   <code>AUTO</code> – Amazon Kinesis Data Streams distributes records evenly
+     *                     across shards and ignores any partition key and <code>ExplicitHashKey</code>
+     *                     that producers supply.</p>
+     *             </li>
+     *             <li>
+     *                <p>
+     *                   <code>USER_PARTITION_KEY</code> – Producers must supply a partition key, which
+     *                     Amazon Kinesis Data Streams uses to determine shard placement. This is the
+     *                     default.</p>
+     *             </li>
+     *          </ul>
+     * @public
+     */
+    RecordDistributionStrategy: RecordDistributionStrategy | undefined;
+}
 /**
  * @public
  */

package/dist-types/schemas/schemas_0.d.ts

@@ -134,6 +134,7 @@ export declare var UpdateMaxRecordSizeInput$: StaticStructureSchema;
 export declare var UpdateShardCountInput$: StaticStructureSchema;
 export declare var UpdateShardCountOutput$: StaticStructureSchema;
 export declare var UpdateStreamModeInput$: StaticStructureSchema;
+export declare var UpdateStreamRecordDistributionStrategyInput$: StaticStructureSchema;
 export declare var UpdateStreamWarmThroughputInput$: StaticStructureSchema;
 export declare var UpdateStreamWarmThroughputOutput$: StaticStructureSchema;
 export declare var WarmThroughputObject$: StaticStructureSchema;
@@ -181,4 +182,5 @@ export declare var UpdateChannel$: StaticOperationSchema;
 export declare var UpdateMaxRecordSize$: StaticOperationSchema;
 export declare var UpdateShardCount$: StaticOperationSchema;
 export declare var UpdateStreamMode$: StaticOperationSchema;
+export declare var UpdateStreamRecordDistributionStrategy$: StaticOperationSchema;
 export declare var UpdateStreamWarmThroughput$: StaticOperationSchema;