ExAws

https://ex-aws.hexdocs.pm/
Admin
ExAws is a flexible, easy-to-use set of Elixir APIs for Amazon Web Services (AWS), providing core...
Tokens:8,993
Snippets:87
Trust Score:9
Update:22 hours ago
Show doc for...
Tokens:
Raw
### request/2 examples with service modules

Source: https://ex-aws.hexdocs.pm/ExAws.md

Examples of using request/2 with service modules like ExAws.S3 and ExAws.Dynamo. The second example shows passing a region override.

```elixir
ExAws.S3.list_buckets |> ExAws.request
```

```elixir
ExAws.S3.list_buckets |> ExAws.request(region: "eu-west-1")
```

```elixir
ExAws.Dynamo.get_object("users", "foo@bar.com") |> ExAws.request
```

--------------------------------

### stream!/2 example

Source: https://ex-aws.hexdocs.pm/ExAws.md

Example of using stream!/2 with ExAws.S3.list_objects/2 to stream objects from a bucket.

```elixir
ExAws.S3.list_objects("my-bucket") |> ExAws.stream!
```

--------------------------------

### Manual operation struct example

Source: https://ex-aws.hexdocs.pm/ExAws.md

Example of creating an ExAws.Operation.JSON struct manually for services not supported, then passing it to ExAws.request/1.

```elixir
op = %ExAws.Operation.JSON{
  http_method: :post,
  service: :dynamodb,
  headers: [
    {"x-amz-target", "DynamoDB_20120810.ListTables"},
    {"content-type", "application/x-amz-json-1.0"}
  ],
}

ExAws.request(op)
```

--------------------------------

### Basic ExAws S3 request and streaming examples

Source: https://ex-aws.hexdocs.pm/readme.md

Shows how to make S3 list_objects requests with the default region, specify a region, and use streaming to enumerate results.

```elixir
# make a request (with the default region)
ExAws.S3.list_objects("my-bucket") |> ExAws.request()

# or specify the region
ExAws.S3.list_objects("my-bucket") |> ExAws.request(region: "us-west-1")

# some operations support streaming
ExAws.S3.list_objects("my-bucket") |> ExAws.stream!() |> Enum.to_list()
```

--------------------------------

### Run DynamoDB Local for ExAws tests

Source: https://ex-aws.hexdocs.pm/readme.md

Starts a local DynamoDB instance on port 8000 using Docker, required for running mix test.

```console
docker run --rm -d -p 8000:8000 amazon/dynamodb-local -jar DynamoDBLocal.jar -port 8000
```

--------------------------------

### Configure ExAws with AWS CLI profile credentials

Source: https://ex-aws.hexdocs.pm/readme.md

Example configuration using the awscli credential provider with a named profile and timeout. Also supports using the AWS_PROFILE environment variable with {:awscli, :system, timeout}.

```elixir
config :ex_aws,
  access_key_id: [{:system, "AWS_ACCESS_KEY_ID"}, {:awscli, "default", 30}, :pod_identity, :instance_role],
  secret_access_key: [{:system, "AWS_SECRET_ACCESS_KEY"}, {:awscli, "default", 30}, :pod_identity, :instance_role]
```

--------------------------------

### ExAws.Operation.perform example with DynamoDB

Source: https://ex-aws.hexdocs.pm/ExAws.Operation.md

Shows how to perform a synchronous request on AWS using ExAws.Operation.perform/2 with an ExAws.Operation.JSON struct for DynamoDB ListTables. The operation returns a response or an error.

```elixir
%ExAws.Operation.JSON{
  data: %{},
  headers: [
    {"x-amz-target", "DynamoDB_20120810.ListTables"},
    {"content-type", "application/x-amz-json-1.0"}
  ],
  http_method: :post,
  params: %{},
  path: "/",
  service: :dynamodb,
} |> ExAws.Operation.perform(ExAws.Config.new(:dynamodb))
```

--------------------------------

### Configure ExAws for instance roles with session token

Source: https://ex-aws.hexdocs.pm/readme.md

Required configuration when using instance roles. Both the environment variable and :instance_role must be included in security_token because instance roles generate session tokens. Without this, instance role authentication may fail silently or produce authentication errors.

```elixir
config :ex_aws,
  access_key_id: [{:system, "AWS_ACCESS_KEY_ID"}, :instance_role],
  secret_access_key: [{:system, "AWS_SECRET_ACCESS_KEY"}, :instance_role],
  security_token: [{:system, "AWS_SESSION_TOKEN"}, :instance_role]
```

--------------------------------

### request!(op, config_overrides \\ [])

Source: https://ex-aws.hexdocs.pm/ExAws.html

Perform an AWS request, raise if it fails. Same as request/1,2 except it will either return the successful response from AWS or raise an exception.

```APIDOC
## request!(op, config_overrides \\ [])

### Description
Perform an AWS request, raise if it fails. Same as `request/1,2` except it will either return the successful response from AWS or raise an exception.

### Function Signature
```elixir
@spec request!(
  ExAws.Operation.t(),
  keyword()
) :: term()
```

### Parameters
- **op** (ExAws.Operation.t()) - Required - The operation to perform.
- **config_overrides** (keyword()) - Optional - Configuration overrides for the request.

### Response
Returns the successful response from AWS or raises an exception.
```

--------------------------------

### Configure JSON codec

Source: https://ex-aws.hexdocs.pm/readme.md

The default JSON codec is Jason. You can choose a different one, such as Poison.

```elixir
config :ex_aws,
  json_codec: Poison
```

--------------------------------

### Add ExAws and S3 dependencies to mix.exs

Source: https://ex-aws.hexdocs.pm/readme.md

Required dependencies for using the S3 service with ExAws v2.0. Includes the core ex_aws package, ex_aws_s3, the default HTTP client hackney, and sweet_xml for XML parsing.

```elixir
defp deps do
  [
    {:ex_aws, "~> 2.1"},
    {:ex_aws_s3, "~> 2.0"},
    {:hackney, "~> 1.9"},
    {:sweet_xml, "~> 0.6"},
  ]
end
```

--------------------------------

### Configure ExAws with session token

Source: https://ex-aws.hexdocs.pm/readme.md

Alternative authentication using AWS_SESSION_TOKEN mapped to security_token. Use when you have a session token to authenticate.

```elixir
config :ex_aws,
  access_key_id: {:system, "AWS_ACCESS_KEY_ID"},
  security_token: {:system, "AWS_SESSION_TOKEN"},
  secret_access_key: {:system, "AWS_SECRET_ACCESS_KEY"}
```

--------------------------------

### Configure ExAws retries with default values

Source: https://ex-aws.hexdocs.pm/readme.md

Sets the retry parameters for ExAws: max_attempts, base_backoff_in_ms, and max_backoff_in_ms. The default values are shown; max_attempts_client can be set separately for client errors (4xx).

```elixir
# default values shown below

config :ex_aws, :retries,
  max_attempts: 10,
  base_backoff_in_ms: 10,
  max_backoff_in_ms: 10_000
```

--------------------------------

### stream!(op, config_overrides \\ [])

Source: https://ex-aws.hexdocs.pm/ExAws.html

Return a stream for the AWS resource. Useful for streaming large resources like S3 objects.

```APIDOC
## stream!(op, config_overrides \\ [])

### Description
Return a stream for the AWS resource. This function allows you to stream the resource instead of loading it all at once.

### Function Signature
```elixir
@spec stream!(
  ExAws.Operation.t(),
  keyword()
) :: Enumerable.t()
```

### Parameters
- **op** (ExAws.Operation.t()) - Required - The operation to perform.
- **config_overrides** (keyword()) - Optional - Configuration overrides for the request.

### Examples
```elixir
ExAws.S3.list_objects("my-bucket") |> ExAws.stream!
```

### Response
Returns an `Enumerable.t()` stream for the AWS resource.
```

--------------------------------

### perform/2

Source: https://ex-aws.hexdocs.pm/ExAws.Operation.md

Performs a synchronous request on AWS. Takes an operation struct (e.g., ExAws.Operation.JSON) and an ExAws.Config, and returns a response or an error.

```APIDOC
## perform/2

### Description
Performs a request on AWS. The operation is synchronous, returning a response or an error.

### Method
perform/2

### Parameters
- **operation** (ExAws.Operation.t()) - Required - The operation to perform, implementing the ExAws.Operation protocol.
- **config** (ExAws.Config) - Required - The AWS configuration.

### Example
```elixir
%ExAws.Operation.JSON{
  data: %{},
  headers: [
    {"x-amz-target", "DynamoDB_20120810.ListTables"},
    {"content-type", "application/x-amz-json-1.0"}
  ],
  http_method: :post,
  params: %{},
  path: "/",
  service: :dynamodb,
} |> ExAws.Operation.perform(ExAws.Config.new(:dynamodb))
```

### Returns
- **response** (term()) - The AWS response.
- **error** (term()) - An error tuple if the request fails.
```

--------------------------------

### request!/2

Source: https://ex-aws.hexdocs.pm/ExAws.md

Perform an AWS request, raise if it fails. Same as request/2 but returns the successful response or raises an exception.

```APIDOC
## `request!/2`

### Description
Perform an AWS request, raise if it fails. Same as `request/1,2` except it will either return the successful response from AWS or raise an exception.

### Signature
```elixir
@spec request!(
  ExAws.Operation.t(),
  keyword()
) :: term()
```

### Parameters
- **operation** (ExAws.Operation.t()) - Required - The operation to perform.
- **options** (keyword()) - Optional - Configuration overrides.

### Returns
- `term()` - The successful response from AWS, or raises an exception on failure.
```

--------------------------------

### request/2

Source: https://ex-aws.hexdocs.pm/ExAws.md

Perform an AWS request. Build an operation from a service module or manually, then pass it to this function. Accepts optional configuration overrides and telemetry options.

```APIDOC
## `request/2`

### Description
Perform an AWS request. First build an operation from one of the services, and then pass it to this function to perform it. This function takes an optional second parameter of configuration overrides.

### Signature
```elixir
@spec request(
  ExAws.Operation.t(),
  keyword()
) :: {:ok, term()} | {:error, term()}
```

### Parameters
- **operation** (ExAws.Operation.t()) - Required - The operation to perform, built from a service module or manually.
- **options** (keyword()) - Optional - Configuration overrides, including `:telemetry_event` and `:telemetry_options`.

### Examples
```elixir
ExAws.S3.list_buckets |> ExAws.request

ExAws.S3.list_buckets |> ExAws.request(region: "eu-west-1")

ExAws.Dynamo.get_object("users", "foo@bar.com") |> ExAws.request
```

### Telemetry Events
- `[:ex_aws, :request, :start]` - dispatched on start every request sent to the AWS.
- `[:ex_aws, :request, :stop]` - dispatched on every response from AWS.
- `[:ex_aws, :request, :exception]` - dispatched after exceptions on request sent to AWS.

Metadata includes: `:result`, `:attempt`, `:service`, `:options`.

### Returns
- `{:ok, term()}` - Success response from AWS.
- `{:error, term()}` - Error response from AWS.
```

--------------------------------

### Add configparser_ex dependency for AWS CLI config support

Source: https://ex-aws.hexdocs.pm/readme.md

Required dependency to enable reading AWS CLI config files (~/.aws/config and ~/.aws/credentials).

```elixir
{:configparser_ex, "~> 4.0"}
```

--------------------------------

### Redshift DescribeClusters with ExAws.Operation.Query

Source: https://ex-aws.hexdocs.pm/readme.md

Constructs a query-protocol operation for the Redshift DescribeClusters API. The action is converted to a string and camelized for the 'Action' parameter. Requires knowing the service name (:redshift) and path ('/').

```elixir
action = :describe_clusters
action_string = action |> Atom.to_string |> Macro.camelize

operation =
  %ExAws.Operation.Query{
    path: "/",
    params: %{"Action" => action_string},
    service: :redshift,
    action: action
  }

ExAws.request(operation)
```

--------------------------------

### Add ex_aws_sts dependency for role-based authentication

Source: https://ex-aws.hexdocs.pm/readme.md

Required dependency for role-based authentication via role_arn and source_profile. Further information is provided in the ex_aws_sts dependency.

```elixir
{:ex_aws_sts, "~> 2.0"}
```

--------------------------------

### request(op, config_overrides \\ [])

Source: https://ex-aws.hexdocs.pm/ExAws.html

Perform an AWS request. Build an operation from one of the services and pass it to this function. Optionally accepts configuration overrides for per-request changes.

```APIDOC
## request(op, config_overrides \\ [])

### Description
Perform an AWS request. First build an operation from one of the services, and then pass it to this function to perform it. Optionally accepts a second parameter of configuration overrides for per-request changes.

### Function Signature
```elixir
@spec request(
  ExAws.Operation.t(),
  keyword()
) :: {:ok, term()} | {:error, term()}
```

### Parameters
- **op** (ExAws.Operation.t()) - Required - The operation to perform, built from a service module or manually.
- **config_overrides** (keyword()) - Optional - Configuration overrides for the request, e.g., `region: "eu-west-1"`.

### Configuration Overrides
- `:telemetry_event` - The telemetry event name to dispatch the event under. Defaults to `[:ex_aws, :request]`.
- `:telemetry_options` - Extra options to attach to telemetry event name.

### Examples
```elixir
ExAws.S3.list_buckets |> ExAws.request

ExAws.S3.list_buckets |> ExAws.request(region: "eu-west-1")

ExAws.Dynamo.get_object("users", "foo@bar.com") |> ExAws.request
```

Alternatively, create operation structs manually:
```elixir
op = %ExAws.Operation.JSON{
  http_method: :post,
  service: :dynamodb,
  headers: [
    {"x-amz-target", "DynamoDB_20120810.ListTables"},
    {"content-type", "application/x-amz-json-1.0"}
  ],
}

ExAws.request(op)
```

### Telemetry Events
The following events are published:
- `[:ex_aws, :request, :start]` - dispatched on start every request sent to the AWS.
- `[:ex_aws, :request, :stop]` - dispatched on every response from AWS.
- `[:ex_aws, :request, :exception]` - dispatched after exceptions on request sent to AWS.

With `:metadata` map including the following fields:
- `:result` - the request result: `:ok` or `:error`
- `:attempt` - the attempt number
- `:service` - the AWS service
- `:options` - extra options given to the repo operation under `:telemetry_options`

### Response
Returns `{:ok, term()}` on success or `{:error, term()}` on failure.
```

--------------------------------

### Configure hackney options

Source: https://ex-aws.hexdocs.pm/readme.md

ExAws uses hackney by default for HTTP requests. Modify options such as follow_redirect and recv_timeout.

```elixir
config :ex_aws, :hackney_opts,
  follow_redirect: true,
  recv_timeout: 30_000
```

--------------------------------

### ECS RunTask with ExAws.Operation.JSON

Source: https://ex-aws.hexdocs.pm/readme.md

Constructs a JSON-protocol operation for the ECS RunTask API. Includes HTTP method, headers with the x-amz-target and content-type, path, data payload, and service name. The data includes task definition, launch type, and network configuration.

```elixir
data = %{
  taskDefinition: "hello_world",
  launchType: "FARGATE",
  networkConfiguration: %{
    awsvpcConfiguration: %{
      subnets: ["subnet-1a2b3c4d", "subnet-4d3c2b1a"],
      securityGroups: ["sg-1a2b3c4d"],
      assignPublicIp: "ENABLED"
    }
  }
}

operation =
  %ExAws.Operation.JSON{
    http_method: :post,
    headers: [
      {"x-amz-target", "AmazonEC2ContainerServiceV20141113.RunTask"},
      {"content-type", "application/x-amz-json-1.1"}
    ],
    path: "/",
    data: data,
    service: :ecs
  }

ExAws.request(operation)
```

--------------------------------

### request!/2 spec

Source: https://ex-aws.hexdocs.pm/ExAws.md

Spec for the request!/2 function. It takes an ExAws.Operation.t() and optional keyword options, returning the successful response or raising an exception.

```elixir
@spec request!(
  ExAws.Operation.t(),
  keyword()
) :: term()
```

--------------------------------

### request/2 spec

Source: https://ex-aws.hexdocs.pm/ExAws.md

Spec for the request/2 function. It takes an ExAws.Operation.t() and optional keyword options, returning {:ok, term()} or {:error, term()}.

```elixir
@spec request(
  ExAws.Operation.t(),
  keyword()
) :: {:ok, term()} | {:error, term()}
```

--------------------------------

### Set AWS region from environment variable

Source: https://ex-aws.hexdocs.pm/readme.md

Sets the region from the AWS_REGION environment variable.

```elixir
config :ex_aws,
  region: {:system, "AWS_REGION"}
```

--------------------------------

### Default AWS credential resolution configuration

Source: https://ex-aws.hexdocs.pm/readme.md

ExAws's default credential resolution order: environment variables, EKS Pod Identity, then IAM roles (ECS task role or EC2 instance role).

```elixir
config :ex_aws,
  access_key_id: [{:system, "AWS_ACCESS_KEY_ID"}, :pod_identity, :instance_role],
  secret_access_key: [{:system, "AWS_SECRET_ACCESS_KEY"}, :pod_identity, :instance_role]
```

--------------------------------

### stream!/2

Source: https://ex-aws.hexdocs.pm/ExAws.Operation.md

Performs a streaming request on AWS. This is used for operations that return a stream of data, such as S3 downloads.

```APIDOC
## stream!/2

### Description
Performs a *streaming* request on AWS. This is used for operations that return a stream of data, such as S3 downloads.

### Method
stream!/2

### Parameters
- **operation** (ExAws.Operation.t()) - Required - The operation to perform, implementing the ExAws.Operation protocol.
- **config** (ExAws.Config) - Required - The AWS configuration.

### Returns
- **stream** (Enumerable.t()) - A stream of data.
```

--------------------------------

### stream!/2 spec

Source: https://ex-aws.hexdocs.pm/ExAws.md

Spec for the stream!/2 function. It takes an ExAws.Operation.t() and optional keyword options, returning an Enumerable.t() stream.

```elixir
@spec stream!(
  ExAws.Operation.t(),
  keyword()
) :: Enumerable.t()
```

--------------------------------

### Disable path normalization

Source: https://ex-aws.hexdocs.pm/readme.md

Paths with multiple consecutive slashes are normalized to a single slash by default. Set normalize_path to false when paths need to be literal, such as for S3.

```elixir
config :ex_aws,
  normalize_path: false
```

--------------------------------

### ExAws.Operation type definition

Source: https://ex-aws.hexdocs.pm/ExAws.Operation.md

Defines the type t() as term(), representing all types that implement the ExAws.Operation protocol.

```elixir
@type t() :: term()
```

--------------------------------

### Set default AWS region

Source: https://ex-aws.hexdocs.pm/readme.md

Sets the default region used for requests to a fixed value.

```elixir
config :ex_aws,
  region: "us-west-2",
```
Tokens:
Raw