update-subscriber¶

Description¶

Updates a subscriber. Fields omitted from the request are left unchanged.

Synopsis¶

  update-subscriber
--subscriber-arn <value>
[--description <value>]
[--state <value>]
[--resume-position <value>]
[--invoke-configuration <value>]
[--filter-configuration <value>]
[--batch-configuration <value>]
[--transformer <value>]
[--retry-policy <value>]
[--on-failure-configuration <value>]
[--log-configuration <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¶

--subscriber-arn (string) [required]

The Amazon Resource Name (ARN) that uniquely identifies a subscriber.

Constraints:

min: 1

max: 1011

pattern: arn:aws(-[a-z0-9]+)*:events:[a-z][a-z0-9]*(-[a-z0-9]+)*:([0-9]{12}):subscriber\/[A-Za-z0-9][\.\-_A-Za-z0-9]{0,255}\/[a-z0-9]{25}

--description (string)

Free-text description. Used by every resource type that has one: event buses, subscribers, and event sources.

Constraints:

min: 0

max: 512

pattern: [^\u0000-\u001F\u007F-\u009F\u2028\u2029]*(?![\s\S]).*

--state (string)

Customer-controlled run state of a subscriber, set on create or update. Distinct from the bus lifecycle vocabulary, where ACTIVE means “provisioned and healthy”. Delivery requires State RUNNING on a subscriber that is not revoked.

Possible values:

RUNNING

STOPPED

--resume-position (string)

Position from which delivery resumes when a subscriber is unpaused. Honored only on an UpdateSubscriber call that transitions State from STOPPED to RUNNING (unpause); ignored on any other call and not accepted on Create. Defaults to LAST_PROCESSED when omitted.

Possible values:

LAST_PROCESSED

LATEST

--invoke-configuration (structure)

Update-able configuration for how the subscriber invokes its target.

RoleArn -> (string) [required]

IAM role the service assumes to invoke the target. Must belong to the calling account.

Constraints:

min: 1

max: 1600

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

LambdaParameters -> (structure)

Lambda invocation parameters for subscribers. Values are forwarded to the Lambda Invoke API. Every string member accepts a literal or a JSONata expression (e.g. “{% $events.Data.qualifier %}”).

InvocationType -> (string)

Lambda invocation type. EVENT invokes the function asynchronously; REQUEST_RESPONSE waits for its result.

Possible values:

EVENT

REQUEST_RESPONSE

Qualifier -> (string)

Lambda qualifier: $LATEST, $LATEST.PUBLISHED, a numeric version, or an alias. Accepts a JSONata expression.

Constraints:

min: 0

max: 8192

DurableExecutionName -> (string)

Durable execution name. Accepts a JSONata expression.

Constraints:

min: 0

max: 8192

TenantId -> (string)

Tenant identifier. Accepts a JSONata expression.

Constraints:

min: 0

max: 8192

InvocationTimeoutSeconds -> (string)

Timeout in seconds for each invocation of the target. String-typed so the value may be a JSONata expression.

Constraints:

min: 0

max: 8192

SqsParameters -> (structure)

SQS invocation parameters for subscribers. Values are forwarded to the SQS SendMessageBatch API. All scalar values accept a literal or a JSONata expression (e.g. “{% $events.Data.groupId %}”).

MessageGroupId -> (string)

Message group ID for FIFO queues. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

MessageDeduplicationId -> (string)

Message deduplication ID for FIFO queues. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

DelaySeconds -> (string)

Delay in seconds before the message becomes visible, standard queues only. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

MessageAttributes -> (map)

Custom message attributes (name/type/value).

Constraints:

min: 0

max: 50

key -> (string)

Message attribute name. The ceiling is wide enough to hold a JSONata expression, because a name may be a literal or an expression resolved once per delivered event.

Constraints:

min: 0

max: 8192

value -> (structure)

A custom SQS message attribute (data type plus string or binary value).

DataType -> (string)

Attribute data type. Requiredness, the accepted vocabulary, and any custom label belong to SQS, which rejects an attribute without a data type on delivery.

Constraints:

min: 0

max: 8192

StringValue -> (string)

String attribute value. A JSONata expression resolves once per delivered event.

BinaryValue -> (string)

Base64-encoded literal binary attribute value.

MessageSystemAttributes -> (map)

System message attributes (e.g., AWSTraceHeader).

Constraints:

min: 0

max: 50

key -> (string)

Message attribute name. The ceiling is wide enough to hold a JSONata expression, because a name may be a literal or an expression resolved once per delivered event.

Constraints:

min: 0

max: 8192

value -> (structure)

A custom SQS message attribute (data type plus string or binary value).

DataType -> (string)

Attribute data type. Requiredness, the accepted vocabulary, and any custom label belong to SQS, which rejects an attribute without a data type on delivery.

Constraints:

min: 0

max: 8192

StringValue -> (string)

String attribute value. A JSONata expression resolves once per delivered event.

BinaryValue -> (string)

Base64-encoded literal binary attribute value.

SnsParameters -> (structure)

SNS invocation parameters for subscribers. Values are forwarded to the SNS PublishBatch API. All scalar values accept a literal or a JSONata expression (e.g. “{% $events.Data.groupId %}”).

MessageGroupId -> (string)

Message group ID for FIFO topics. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

MessageDeduplicationId -> (string)

Message deduplication ID for FIFO topics. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

Subject -> (string)

Subject line for email protocol subscriptions. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

MessageStructure -> (string)

Per-protocol message formatting mode, forwarded to SNS Publish unchanged. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

MessageAttributes -> (map)

Custom message attributes for SNS filtering.

Constraints:

min: 0

max: 50

key -> (string)

Message attribute name. The ceiling is wide enough to hold a JSONata expression, because a name may be a literal or an expression resolved once per delivered event.

Constraints:

min: 0

max: 8192

value -> (structure)

A custom SNS message attribute (data type plus string or binary value).

DataType -> (string)

Attribute data type. Requiredness and the accepted vocabulary belong to SNS, which rejects an attribute without a data type on delivery.

Constraints:

min: 0

max: 8192

StringValue -> (string)

String attribute value. A JSONata expression resolves once per delivered event.

BinaryValue -> (string)

Base64-encoded literal binary attribute value.

KinesisParameters -> (structure)

Kinesis Data Streams invocation parameters for subscribers. Values are forwarded to the Kinesis PutRecords API. All scalar values accept a literal or a JSONata expression (e.g. “{% $events.Data.partitionKey %}”).

PartitionKey -> (string)

Required by PutRecords even when an explicit hash key is supplied. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

ExplicitHashKey -> (string)

Explicit hash key forwarded to PutRecords unchanged. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

StepFunctionsParameters -> (structure)

Step Functions invocation parameters for subscribers. Values are forwarded to the Step Functions StartExecution or StartSyncExecution API. Every string member accepts a literal or a JSONata expression (e.g. “{% $events.Data.executionName %}”).

InvocationType -> (string)

Selects StartExecution (EVENT) or StartSyncExecution (REQUEST_RESPONSE) at delivery.

Possible values:

EVENT

REQUEST_RESPONSE

Name -> (string)

Name for the execution. Must be unique per account/region/state machine. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

TraceHeader -> (string)

X-Ray trace header for distributed tracing. Accepts JSONata expression.

Constraints:

min: 0

max: 8192

InvocationTimeoutSeconds -> (string)

Timeout in seconds for each invocation of the target (1-30). String-typed (not integer) so the value may be a JSONata expression.

Constraints:

min: 0

max: 8192

HttpParameters -> (structure)

HTTP invocation parameters for subscribers (API Gateway / API Destination). Values are forwarded to the HTTP endpoint.

PathParameterValues -> (list)

Values substituted, in order, for the path-parameter placeholders in an HTTP target’s endpoint path.

Constraints:

min: 0

max: 50

(string)

Constraints:

pattern: (?!\s*$).+

HeaderParameters -> (map)

Map of HTTP header names to values, sent with the request to an HTTP target.

Constraints:

min: 0

max: 50

key -> (string)

Constraints:

min: 0

max: 512

pattern: ([!#$%&'*+\-.^_`|~0-9a-zA-Z]+|\{%[\s\S]+?%\})

value -> (string)

Constraints:

min: 0

max: 2048

pattern: ([ \t]*[\x20-\x7E]+([ \t]+[\x20-\x7E]+)*[ \t]*|\{%[\s\S]+?%\})

QueryStringParameters -> (map)

Map of query-string parameter names to values, appended to the request to an HTTP target.

Constraints:

min: 0

max: 50

key -> (string)

Constraints:

min: 0

max: 512

pattern: [^\x00-\x1F\x7F]+

value -> (string)

Constraints:

min: 0

max: 512

pattern: [^\x00-\x09\x0B\x0C\x0E-\x1F\x7F]+

InvocationTimeoutSeconds -> (string)

Timeout in seconds for each invocation of the target (1-30). String-typed (not integer) so the value may be a JSONata expression.

UniversalTargetParameters -> (structure)

Parameters for USI (Universal Service Integration) targets. Used when TargetArn is in the format arn:aws:events:::aws-sdk:{service}:{apiAction}

Input -> (string) [required]

JSON string or JSONata expression that produces the API request. Supports {% … %} JSONata expressions for dynamic values from the event.

Constraints:

min: 1

max: 262144

InvocationTimeoutSeconds -> (string)

Timeout in seconds for each invocation of the target (1-30, default 30). Accepts a literal integer or a {% … %} JSONata expression evaluated against the event at invocation time. A JSONata expression is syntax-checked at create time. Resolved values outside of the range [1, 30] will be constrained to the nearest bound at delivery time. Defaults to 30 seconds when unset.

EventBusV2Parameters -> (structure)

Parameters for forwarding events to another EventBridge event bus.

Metadata -> (map)

Customer-defined metadata forwarded with each event.

Constraints:

min: 0

max: 100

key -> (string)

value -> (string)

SystemMetadata -> (structure)

Customer-controllable system metadata attached to each forwarded event.

EventGroupId -> (string)

Event group ID for FIFO ordering on the downstream bus. Accepts a literal or a JSONata expression.

DeduplicationId -> (string)

Deduplication ID for FIFO deduplication on the downstream bus. Accepts a literal or a JSONata expression.

DeduplicationConfiguration -> (structure)

Deduplication settings applied to the forwarded events on the downstream bus.

DeduplicationType -> (string) [required]

How duplicate events are detected: by a hash of the event content (CONTENT_BASED). To deduplicate by a caller-supplied token instead, omit DeduplicationConfiguration and set DeduplicationId on each entry.

Possible values:

CONTENT_BASED

JSON Syntax:

{
  "RoleArn": "string",
  "LambdaParameters": {
    "InvocationType": "EVENT"|"REQUEST_RESPONSE",
    "Qualifier": "string",
    "DurableExecutionName": "string",
    "TenantId": "string",
    "InvocationTimeoutSeconds": "string"
  },
  "SqsParameters": {
    "MessageGroupId": "string",
    "MessageDeduplicationId": "string",
    "DelaySeconds": "string",
    "MessageAttributes": {"string": {
          "DataType": "string",
          "StringValue": "string",
          "BinaryValue": "string"
        }
      ...},
    "MessageSystemAttributes": {"string": {
          "DataType": "string",
          "StringValue": "string",
          "BinaryValue": "string"
        }
      ...}
  },
  "SnsParameters": {
    "MessageGroupId": "string",
    "MessageDeduplicationId": "string",
    "Subject": "string",
    "MessageStructure": "string",
    "MessageAttributes": {"string": {
          "DataType": "string",
          "StringValue": "string",
          "BinaryValue": "string"
        }
      ...}
  },
  "KinesisParameters": {
    "PartitionKey": "string",
    "ExplicitHashKey": "string"
  },
  "StepFunctionsParameters": {
    "InvocationType": "EVENT"|"REQUEST_RESPONSE",
    "Name": "string",
    "TraceHeader": "string",
    "InvocationTimeoutSeconds": "string"
  },
  "HttpParameters": {
    "PathParameterValues": ["string", ...],
    "HeaderParameters": {"string": "string"
      ...},
    "QueryStringParameters": {"string": "string"
      ...},
    "InvocationTimeoutSeconds": "string"
  },
  "UniversalTargetParameters": {
    "Input": "string",
    "InvocationTimeoutSeconds": "string"
  },
  "EventBusV2Parameters": {
    "Metadata": {"string": "string"
      ...},
    "SystemMetadata": {
      "EventGroupId": "string",
      "DeduplicationId": "string"
    },
    "DeduplicationConfiguration": {
      "DeduplicationType": "CONTENT_BASED"
    }
  }
}

--filter-configuration (structure)

Configuration for filtering events delivered to a subscriber. On CreateSubscriber, Filters is required and must contain at least one Filter with a non-empty Pattern. On UpdateSubscriber, an empty FilterConfiguration:{} clears the existing filter. Any non-empty shape (including {Language:X} without Filters) must contain a valid Filters list — same contract as CreateSubscriber. A non-empty Filters list overwrites; an omitted FilterConfiguration preserves existing state. All Filters are implicitly ANDed — an event must match every Filter to be delivered.

Language -> (string)

Defaults to EVENT_BRIDGE_PATTERN when not specified.

Possible values:

EVENT_BRIDGE_PATTERN

Filters -> (list)

List of filters. An event must match every filter to be delivered.

Constraints:

min: 1

max: 50

(structure)

A single filter entry within a FilterConfiguration.

Pattern -> (string) [required]

An event pattern, as a JSON string, that selects which events match.

Constraints:

min: 0

max: 4096

Scope -> (string) [required]

Scope of a filter pattern within a FilterConfiguration.

Possible values:

DATA

METADATA

SYSTEM_METADATA

Shorthand Syntax:

Language=string,Filters=[{Pattern=string,Scope=string},{Pattern=string,Scope=string}]

JSON Syntax:

{
  "Language": "EVENT_BRIDGE_PATTERN",
  "Filters": [
    {
      "Pattern": "string",
      "Scope": "DATA"|"METADATA"|"SYSTEM_METADATA"
    }
    ...
  ]
}

--batch-configuration (structure)

Batching configuration for a subscriber.

MaxBatchSize -> (integer)

The maximum number of events to include in a single batch delivered to the target. The service delivers up to this many events per batch; fewer may be delivered when the batch window elapses or the target’s per-batch limit is smaller. This is a maximum, not a guaranteed count. Valid range is 1-500 (default: 10, or the target API’s per-batch maximum). The resolved value applied by the service is returned on read.

Constraints:

min: 1

max: 500

MaxBatchWindowInSeconds -> (integer)

The maximum time in seconds to wait for a batch to fill before delivering it to the target. This is a maximum; a batch may be delivered sooner if it reaches MaxBatchSize or another delivery condition is met. Valid range is 0-300 (default: 0, meaning no wait). The resolved value applied by the service is always returned on read.

Constraints:

min: 0

max: 300

Shorthand Syntax:

MaxBatchSize=integer,MaxBatchWindowInSeconds=integer

JSON Syntax:

{
  "MaxBatchSize": integer,
  "MaxBatchWindowInSeconds": integer
}

--transformer (structure)

Not applicable to universal (aws-sdk) targets, whose input transformation is UniversalTargetParameters.Input; a Transformer on such a target is rejected.

Type -> (string)

Transform type.

Possible values:

RAW

WITH_METADATA

JSONATA

JsonataConfiguration -> (structure)

JSONata expression configuration. Required when Type is JSONATA.

Expression -> (string) [required]

JSONata expression to transform the event. Must be wrapped in {% %} delimiters.

Constraints:

min: 1

max: 8192

pattern: \{%[\s\S]+?%\}(?![\s\S]).*

Shorthand Syntax:

Type=string,JsonataConfiguration={Expression=string}

JSON Syntax:

{
  "Type": "RAW"|"WITH_METADATA"|"JSONATA",
  "JsonataConfiguration": {
    "Expression": "string"
  }
}

--retry-policy (structure)

Retry policy for a subscriber.

MaxRetryAttempts -> (integer)

Maximum number of retry attempts (0-185, default: 5).

Constraints:

min: 0

max: 185

MaxEventAgeInSeconds -> (integer)

Maximum age of an event in seconds before it is discarded (60-86400, default: 300).

Constraints:

min: 60

max: 86400

RetryStrategy -> (string)

Strategy for determining which exceptions are retried. Default: ALL.

Possible values:

ALL

Shorthand Syntax:

MaxRetryAttempts=integer,MaxEventAgeInSeconds=integer,RetryStrategy=string

JSON Syntax:

{
  "MaxRetryAttempts": integer,
  "MaxEventAgeInSeconds": integer,
  "RetryStrategy": "ALL"
}

--on-failure-configuration (structure)

On-failure configuration: where a failed delivery is sent. Shared by the subscriber and the EventSource.

Arn -> (string)

The ARN of the destination that receives events that could not be delivered. An Amazon SQS queue is the supported destination.

Constraints:

min: 1

max: 1600

pattern: arn:aws(-[a-z0-9]+)*:sqs:[a-z][a-z0-9]*(-[a-z0-9]+)*:[0-9]{12}:([A-Za-z0-9_-]{1,80}|[A-Za-z0-9_-]{1,75}\.fifo)(?![\s\S]).*

Shorthand Syntax:

Arn=string

JSON Syntax:

{
  "Arn": "string"
}

--log-configuration (structure)

Log configuration for a subscriber.

Level -> (string)

Minimum log level. Records below this level are not emitted. Defaults to OFF.

Possible values:

OFF

ERROR

INFO

IncludePayload -> (string)

Whether the customer event payload is embedded in log records. Defaults to ON_ERROR_ONLY.

Possible values:

FULL

ON_ERROR_ONLY

Shorthand Syntax:

Level=string,IncludePayload=string

JSON Syntax:

{
  "Level": "OFF"|"ERROR"|"INFO",
  "IncludePayload": "FULL"|"ON_ERROR_ONLY"
}

--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¶

SubscriberArn -> (string)

The Amazon Resource Name (ARN) that uniquely identifies a subscriber.

Constraints:

min: 1

max: 1011

pattern: arn:aws(-[a-z0-9]+)*:events:[a-z][a-z0-9]*(-[a-z0-9]+)*:([0-9]{12}):subscriber\/[A-Za-z0-9][\.\-_A-Za-z0-9]{0,255}\/[a-z0-9]{25}

Name -> (string)

Name of a subscriber. The first character must be alphanumeric; the remaining characters may also include ‘.’, ‘-’, and ‘_’.

Constraints:

min: 1

max: 256

pattern: [A-Za-z0-9][\.\-_A-Za-z0-9]*

EventBusArn -> (string)

The Amazon Resource Name (ARN) that uniquely identifies an event bus.

Constraints:

min: 1

max: 1011

pattern: arn:aws(-[a-z0-9]+)*:events:[a-z][a-z0-9]*(-[a-z0-9]+)*:([0-9]{12}):event-busv2\/[A-Za-z0-9][\.\-_A-Za-z0-9]{0,255}\/[a-z0-9]{25}

Type -> (string)

Delivery ordering mode of a subscriber: FIFO delivers events in order within an event group; UNORDERED delivers without an ordering guarantee.

Possible values:

FIFO

UNORDERED

StartingPosition -> (string)

Starting position for a subscriber.

Possible values:

LATEST

POINT_IN_TIME

PointInTimeConfiguration -> (structure)

Point-in-time configuration for a subscriber. Only applicable when StartingPosition is POINT_IN_TIME.

PointType -> (string) [required]

Whether to start from the horizon or a specific timestamp.

Possible values:

HORIZON

TIMESTAMP

StartingPoint -> (timestamp)

Timestamp to start from. Required when PointType is TIMESTAMP.

EndPoint -> (timestamp)

Timestamp to stop at. Optional.

State -> (string)

Customer-controlled run state of a subscriber, set on create or update. Distinct from the bus lifecycle vocabulary, where ACTIVE means “provisioned and healthy”. Delivery requires State RUNNING on a subscriber that is not revoked.

Possible values:

RUNNING

STOPPED

LastModifiedTime -> (timestamp)

The time the subscriber was last modified.

Table of Contents

Feedback

User Guide

update-subscriber¶

Description¶

Synopsis¶

Options¶

Global Options¶

Output¶