As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Configurar o AWS SDK para Kotlin
Esta seção explica como configurar um cliente de serviço usando AWS SDK para Kotlin o. Para obter mais informações, consulte o [Guia de referência do SDK e das ferramentas](https://docs.aws.amazon.com/sdkref/latest/guide/overview.html), que inclui uma visão geral da configuração que se aplica a todos AWS SDKs.
**Contents**
+ [Crie um cliente de serviço](creating-clients.md)
+ [Configurar um cliente em código](creating-clients.md#programmatic-config)
+ [Configurar um cliente do ambiente](creating-clients.md#loading-from-the-environment)
+ [Feche o cliente](creating-clients.md#closing-the-client)
+ [Região da AWS seleção](region-selection.md)
+ [Cadeia de fornecedores da região padrão](region-selection.md#default-region-provider-chain)
+ [Provedores de credenciais](credential-providers.md)
+ [A cadeia de fornecedores de credenciais padrão](credential-providers.md#default-credential-provider-chain)
+ [Saiba mais sobre a cadeia de fornecedores de credenciais padrão](credential-providers.md#default-credentials-retrieval-order)
+ [Especifique um provedor de credenciais](credential-providers.md#explicit-credential-provider)
+ [Credenciais de cache com um provedor autônomo](credential-providers.md#credentials-caching)
+ [Configurar endpoints do cliente](config-endpoint.md)
+ [Configuração personalizada](config-endpoint.md#config-endpoint-custom-config)
+ [Definir `endpointUrl`](config-endpoint.md#config-endpoint-custom-config-endpointurl)
+ [Definir `endpointProvider`](config-endpoint.md#config-endpoint-custom-config-endpointprovider)
+ [Propriedades do `EndpointProvider`](config-endpoint.md#config-endpoint-custom-config-endpointprovider-params)
+ [`endpointUrl` ou `endpointProvider`](config-endpoint.md#config-endpoint-custom-config-which)
+ [Uma observação sobre o Amazon S3](config-endpoint.md#config-endpoint-custom-config-s3)
+ [Exemplos](config-endpoint.md#config-endpoint-examples)
+ [Exemplo de `endpointUrl`](config-endpoint.md#config-endpoint-examples-endpointurl)
+ [Exemplo de `endpointProvider`](config-endpoint.md#config-endpoint-examples-endpointprovider)
+ [`endpointUrl` e `endpointProvider`](config-endpoint.md#config-endpoint-examples-both)
+ [HTTP](http.md)
+ [Configuração do cliente HTTP](http-client-config.md)
+ [Configuração básica](http-client-config.md#basic-http-confg)
+ [Importações](http-client-config.md#basic-config-ex-imports)
+ [Código](http-client-config.md#basic-config-ex-code)
+ [Configurações avançadas](http-client-config.md#advanced-http-config)
+ [Especifique um tipo de mecanismo HTTP](http-client-config.md#http-config-engine)
+ [Importações](http-client-config.md#http-config-specify-engine-imports)
+ [Código](http-client-config.md#http-config-specify-engine-code)
+ [Usar a `OkHttp4Engine`](http-client-config.md#http-config-okhttp4engine)
+ [Use um cliente HTTP explícito](http-client-config.md#http-client-explicit-usage)
+ [Importações](http-client-config.md#http-client-explicit-usage-ex-imports)
+ [Código](http-client-config.md#http-client-explicit-usage-ex-code)
+ [Monitoramento de conexão ociosa](http-client-config.md#http-idle-connection-monitoring)
+ [Importações](http-client-config.md#http-idle-connection-ex-imports)
+ [Código](http-client-config.md#http-idle-connection-ex-code)
+ [Usar um proxy HTTP](using-http-proxy.md)
+ [Usar propriedade do sistema de JVM](using-http-proxy.md#http-proxy-jvm-properties)
+ [Use variáveis de ambiente](using-http-proxy.md#http-proxy-environment-variables)
+ [Use um proxy em instâncias do EC2](using-http-proxy.md#http-proxy-ec2)
+ [Interceptadores HTTP](interceptors.md)
+ [Registro de interceptor](interceptors.md#interceptor-registration)
+ [Interceptor para todas as operações do cliente de serviço](interceptors.md#interceptor-all-ops)
+ [Interceptor somente para operações específicas](interceptors.md#interceptor-specific-ops)
+ [Aplicar uma versão mínima do TLS](configure-http-tls.md)
+ [Configurar o mecanismo HTTP](configure-http-tls.md#configure-http-tls-engine)
+ [Definir a propriedade do `sdk.minTls` sistema JVM](configure-http-tls.md#configure-http-tls-sysprop)
+ [Defina a variável de `SDK_MIN_TLS` ambiente](configure-http-tls.md#configure-http-tls-envvar)
+ [Tentativas novamente no AWS SDK para Kotlin](retries.md)
+ [Entendendo o comportamento de repetição](retries.md#retries-understanding)
+ [Configuração padrão de novas tentativas](retries.md#retries-default)
+ [Quais exceções podem ser repetidas?](retries.md#retries-default-policy-details)
+ [Tentável novamente por código de erro](retries.md#retries-retryable-by-error-code)
+ [Tentável novamente pelo código de status HTTP](retries.md#retries-retryable-by-status-code)
+ [Tentável novamente por tipo de erro](retries.md#retries-retryable-by-error-type)
+ [Tentável novamente por metadados do SDK](retries.md#retries-retryable-by-metadata)
+ [Verifique se uma exceção pode ser repetida](retries.md#retries-check-exception-retryable)
+ [Quais exceções chegam ao seu código quando as novas tentativas falham](retries.md#retries-exception-types-during-retries)
+ [Personalizando o comportamento de repetição](retries.md#retries-customizing)
+ [Configurar o máximo de tentativas](retries.md#retires-max-attempts)
+ [Configure atrasos e recuos](retries.md#retries-delays-backoff)
+ [Configurar o repositório de tokens de nova tentativa](retries.md#retries-token-bucket)
+ [Configurar novas tentativas adaptáveis](retries.md#retries-adaptive-retries)
+ [Observabilidade](observability.md)
+ [Configurar um `TelemetryProvider`](observability.md#observability-conf-telemetry-provider)
+ [Configurar o provedor de telemetria global padrão](observability.md#observability-conf-telemetry-provider-global)
+ [Configurar um provedor de telemetria para um cliente de serviço específico](observability.md#observability-conf-telemetry-provider-client)
+ [Metrics](observability-telemetry-metrics.md)
+ [Registro em log](logging.md)
+ [Especifique o modo de registro para mensagens em nível de fio](logging.md#sdk-log-mode)
+ [Definir o modo de registro no código](logging.md#set-log-mode-programmatically)
+ [Defina o modo de registro a partir do ambiente](logging.md#set-log-mode-from-enviironment)
+ [Provedores de telemetria](observability-telemetry-providers.md)
+ [Configurar o provedor OpenTelemetry de telemetria baseado](observability-telemetry-providers-otel.md)
+ [Pré-requisitos](observability-telemetry-providers-otel.md#observability-telemetry-providers-otel-prereqs)
+ [Configurar o SDK](observability-telemetry-providers-otel.md#observability-telemetry-providers-otel-conf)
+ [Recursos](observability-telemetry-providers-otel.md#observability-telemetry-providers-otel-res)
+ [Substituir a configuração do cliente de serviço](override-client-config.md)
+ [Ciclo de vida de um cliente sobrecarregado](override-client-config.md#override-client-lifecycle)
+ [Recursos compartilhados entre clientes](override-client-config.md#override-client-shared-res)
# Crie um cliente de serviço
Para fazer uma solicitação a um AWS service (Serviço da AWS), você deve primeiro instanciar um cliente para esse serviço.
Você pode definir configurações comuns para clientes de serviço, como o cliente HTTP a ser usado, o nível de registro e a configuração de repetição. Além disso, cada cliente de serviço exige um Região da AWS e um provedor de credenciais. O SDK usa esses valores para enviar solicitações para a região correta e assinar solicitações com as credenciais corretas.
Você pode especificar esses valores de modo programático no código ou fazer com que sejam carregados automaticamente do ambiente.
## Configurar um cliente em código
Para configurar um cliente de serviço com valores específicos, você pode especificá-los em uma função lambda passada para o método de fábrica do cliente de serviço, conforme mostrado no trecho a seguir.
```
val dynamoDbClient = DynamoDbClient {
region = "us-east-1"
credentialsProvider = ProfileCredentialsProvider(profileName = "myprofile")
}
```
Todos os valores que você não especificar no bloco de configuração são definidos como padrões. Por exemplo, se você não especificar um provedor de credenciais como o código anterior, o provedor de credenciais usará como padrão a cadeia de fornecedores de credenciais [padrão](credential-providers.md#default-credential-provider-chain).
**Atenção**
Algumas propriedades, como `region` não têm um padrão. Você deve especificá-los explicitamente no bloco de configuração ao usar a configuração programática. Se o SDK não conseguir resolver a propriedade, as solicitações de API poderão falhar.
## Configurar um cliente do ambiente
Ao criar um cliente de serviço, o SDK pode inspecionar locais no ambiente de execução atual para determinar algumas propriedades de configuração. Esses locais incluem [arquivos compartilhados de configuração e credenciais](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html), [variáveis de ambiente](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) e propriedades do sistema [JVM](https://docs.aws.amazon.com/sdkref/latest/guide/jvm-system-properties.html). As propriedades disponíveis para serem resolvidas incluem [AWS Região](region-selection.md), [estratégia de repetição](retries.md), [modo de registro](logging.md#sdk-log-mode) e outras. Para obter mais informações sobre todas as configurações que o SDK pode resolver no ambiente de execução, consulte o [Guia de referência de configurações AWS SDKs e ferramentas](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html).
Para criar um cliente com configuração baseada no ambiente, use o método estático `suspend fun fromEnvironment()` na interface do cliente de serviço:
```
val dynamoDbClient = DynamoDbClient.fromEnvironment()
```
Criar um cliente dessa forma é útil quando executado no Amazon EC2 ou em qualquer outro contexto em que a configuração de um cliente de serviço esteja disponível no ambiente. AWS Lambda Isso separa seu código do ambiente em que ele está sendo executado e facilita a implantação do aplicativo em várias regiões sem alterar o código.
Além disso, você pode substituir propriedades específicas passando um bloco lambda para. `fromEnvironment` O exemplo a seguir carrega algumas propriedades de configuração do ambiente (por exemplo, Região), mas substitui especificamente o provedor de credenciais para usar credenciais de um perfil.
```
val dynamoDbClient = DynamoDbClient.fromEnvironment {
credentialsProvider = ProfileCredentialsProvider(profileName = "myprofile")
}
```
O SDK usa valores padrão para qualquer propriedade de configuração que não possa ser determinada a partir de configurações programáticas ou do ambiente. Por exemplo, se você não especificar um provedor de credenciais no código ou em uma configuração de ambiente, o provedor de credenciais usará como padrão a cadeia de fornecedores de credenciais [padrão](credential-providers.md#default-credential-provider-chain).
**Atenção**
Algumas propriedades, como Região, não têm um padrão. Você deve especificá-los em uma configuração de ambiente ou explicitamente no bloco de configuração. Se o SDK não conseguir resolver a propriedade, as solicitações de API poderão falhar.
**nota**
Embora propriedades relacionadas a credenciais, como chaves de acesso temporárias e configuração de SSO, possam ser encontradas no ambiente de execução, os valores não são fornecidos pelo cliente no momento da criação. Em vez disso, os valores são acessados pela camada do provedor de credenciais em cada solicitação.
## Feche o cliente
Quando você não precisar mais do cliente de serviço, feche-o para liberar os recursos que ele está usando:
```
val dynamoDbClient = DynamoDbClient.fromEnvironment()
// Invoke several DynamoDB operations.
dynamoDbClient.close()
```
Como os clientes de serviço estendem a [https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.io/-closeable/index.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.io/-closeable/index.html)interface, você pode usar a [https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.io/use.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.io/use.html)extensão para fechar o cliente automaticamente no final de um bloco, conforme mostrado no trecho a seguir.
```
DynamoDbClient.fromEnvironment().use { dynamoDbClient ->
// Invoke several DynamoDB operations.
}
```
No exemplo anterior, o bloco lambda recebe uma referência ao cliente que acabou de ser criado. Você pode invocar operações nessa referência de cliente e, quando o bloco for concluído, inclusive lançando uma exceção, o cliente será fechado.
# Região da AWS seleção
Com Regiões da AWS, você pode acessar Serviços da AWS essas operações em uma área geográfica específica. Isso pode ser útil para redundância e para manter os dados e os aplicativos em execução próximo ao lugar onde você e os usuários os acessarão.
## Cadeia de fornecedores da região padrão
Ao carregar a configuração de um cliente de serviço [do ambiente](creating-clients.md#loading-from-the-environment), o seguinte processo de pesquisa é usado:
1. Qualquer região explícita definida no construtor.
1. A propriedade do sistema `aws.region` JVM é verificada. Se estiver definida, essa região será usada na configuração do cliente.
1. A variável de ambiente `AWS_REGION` está marcada. Se estiver definida, essa região será usada na configuração do cliente.
1. **Observação**: essa variável de ambiente é definida pelo contêiner Lambda.
1. O SDK verifica o arquivo de configuração AWS compartilhado. Se a `region` propriedade estiver definida para o perfil ativo, o SDK a usará.
1. A variável de ambiente `AWS_CONFIG_FILE` pode ser usada para personalizar o local do arquivo de configuração compartilhado.
1. A propriedade do sistema `aws.profile` JVM ou a variável de `AWS_PROFILE` ambiente podem ser usadas para personalizar o perfil que o SDK carrega.
1. O SDK tenta usar o Amazon EC2 Instance Metadata Service para determinar a região da instância EC2 atualmente em execução.
1. Se a região ainda não estiver resolvida neste momento, a criação do cliente falhará com uma exceção.
# Provedores de credenciais
****
**A ordem na qual a cadeia de provedores de credenciais padrão resolve as credenciais foi alterada com a versão 1.4.0. Para obter detalhes, consulte a nota abaixo.**
Quando você envia solicitações para a Amazon Web Services usando o AWS SDK para Kotlin, as solicitações devem ser assinadas criptograficamente com credenciais emitidas por. AWS O Kotlin SDK assina a solicitação automaticamente para você. Para adquirir as credenciais, o SDK pode usar definições de configuração que estão localizadas em vários lugares, por exemplo, propriedades do sistema JVM, variáveis de ambiente, `credentials` arquivos compartilhados AWS `config` e metadados de instâncias do Amazon EC2.
O SDK usa a abstração do *provedor de credenciais* para simplificar o processo de recuperação de credenciais de várias fontes. O SDK contém [várias implementações de provedores de credenciais.](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/aws-config/aws.sdk.kotlin.runtime.auth.credentials/index.html)
Por exemplo, se a configuração recuperada incluir configurações de acesso de login único do IAM Identity Center do `config` arquivo compartilhado, o SDK trabalhará com o IAM Identity Center para recuperar as credenciais temporárias que ele usa para fazer solicitações. Serviços da AWS Com essa abordagem de aquisição de credenciais, o SDK usa o provedor do IAM Identity Center (também conhecido como provedor de credenciais de SSO). A [seção de configuração](setup-basic-onetime-setup.md#setup-sso-access) deste guia descreveu essa configuração.
Para usar um provedor de credenciais específico, você pode especificar um ao criar um cliente de serviço. Como alternativa, você pode usar a cadeia de provedores de credenciais padrão para pesquisar as configurações automaticamente.
## A cadeia de fornecedores de credenciais padrão
Quando não especificado explicitamente na construção do cliente, o SDK para Kotlin usa um provedor de credenciais que verifica sequencialmente cada local onde você pode fornecer credenciais. Esse provedor de credenciais padrão é implementado como uma cadeia de provedores de credenciais.
Para usar a cadeia padrão para fornecer credenciais em seu aplicativo, crie um cliente de serviço sem fornecer explicitamente uma `credentialsProvider` propriedade.
```
val ddb = DynamoDbClient {
region = "us-east-2"
}
```
Para obter mais informações sobre a criação de clientes de serviço, consulte [construir e configurar um cliente](creating-clients.md).
### Saiba mais sobre a cadeia de fornecedores de credenciais padrão
A cadeia de provedores de credenciais padrão pesquisa a configuração de credenciais usando a seguinte sequência predefinida. Quando as configurações definidas fornecem credenciais válidas, a cadeia é interrompida.
**1. [AWS chaves de acesso (propriedades do sistema JVM)](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html)**
O SDK procura as propriedades do sistema`aws.accessKeyId`,`aws.secretAccessKey`, e `aws.sessionToken` JVM.
**2. [AWS chaves de acesso (variáveis de ambiente)](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html)**
O SDK tenta carregar credenciais das variáveis de ambiente `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`.
**3. [Token de identidade da Web](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role-web.html)**
O SDK procura as variáveis de ambiente `AWS_WEB_IDENTITY_TOKEN_FILE` e `AWS_ROLE_ARN` (ou as propriedades `aws.webIdentityTokenFile` do sistema JVM e). `aws.roleArn` Com base nas informações do token e na função, o SDK adquire credenciais temporárias.
**4. [Um perfil em um arquivo de configuração](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)**
Nesta etapa, o SDK usa configurações associadas a um perfil. Por padrão, o SDK usa o compartilhado AWS `config` e os `credentials` arquivos, mas se a variável de `AWS_CONFIG_FILE` ambiente estiver definida, o SDK usará esse valor. Se a variável de `AWS_PROFILE` ambiente (ou propriedade do sistema `aws.profile` JVM) *não* estiver definida, o SDK procurará o perfil “padrão”, caso contrário, procurará o perfil que corresponde ao valor. `AWS_PROFILE’s`
O SDK procura o perfil com base na configuração descrita no parágrafo anterior e usa as configurações definidas lá. Se as configurações encontradas pelo SDK contiverem uma combinação de configurações para diferentes abordagens de provedores de credenciais, o SDK usará a seguinte ordem:
1. [AWS chaves de acesso (arquivo de configuração)](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html) - O SDK usa as configurações para `aws_access_key_id``aws_access_key_id`, e. `aws_session_token`
1. [Assumir a configuração da função](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html) - se o SDK encontrar `role_arn` `source_profile` e/ou `credential_source` configurações, ele tentará assumir uma função. Se o SDK encontrar a `source_profile` configuração, ele obterá credenciais de outro perfil para receber credenciais temporárias para a função especificada por. `role_arn` Se o SDK encontrar a `credential_source` configuração, ele obterá as credenciais de um contêiner do Amazon ECS, de uma instância do Amazon EC2 ou de variáveis de ambiente, dependendo do valor da configuração. `credential_source` Em seguida, ele usa essas credenciais para adquirir credenciais temporárias para a função.
Um perfil deve conter a `source_profile` configuração ou a `credential_source` configuração, mas não ambas.
1. [Configuração do token de identidade da Web](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role-web.html) - Se o SDK encontrar `role_arn` e `web_identity_token_file` configurar, ele adquire credenciais temporárias para acessar AWS recursos com base no `role_arn` e no token.
1. [Configuração do token SSO](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html) — se o SDK encontrar `sso_role_name` as configurações`sso_session`,`sso_account_id`, (junto com uma `sso-session` seção complementar nos arquivos de configuração), o SDK recuperará credenciais temporárias do serviço IAM Identity Center.
1. [Configuração de SSO herdada](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-legacy) — se o SDK encontrar` sso_start_url`,`sso_region`, e `sso_role_name` definir`sso_account_id`, o SDK recuperará credenciais temporárias do serviço IAM Identity Center.
1. [Configuração de login](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-legacy) - Se o SDK encontrar uma `login_session` configuração, ele usará as credenciais temporárias da sessão de login ou tentará atualizá-las se elas expirarem em menos de 5 minutos. Para saber como iniciar uma sessão de login, consulte o guia do [usuário da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html).
1. [Configuração do processo](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html): se o SDK encontrar uma `credential_process` configuração, ele usa o valor do caminho para invocar um processo e adquirir credenciais temporárias.
**5. [Credenciais do contêiner](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html)**
O SDK procura variáveis de ambiente `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` ou `AWS_CONTAINER_CREDENTIALS_FULL_URI` e `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` ou`AWS_CONTAINER_AUTHORIZATION_TOKEN`. Ele usa esses valores para carregar credenciais do endpoint HTTP especificado por meio de uma solicitação GET.
**6. [Credenciais IMDS](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html)**
O SDK tenta buscar credenciais do [Instance Metadata Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) no endpoint HTTP padrão ou configurado. O SDK só oferece suporte [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html).
Se as credenciais ainda não forem resolvidas neste momento, a criação do cliente falhará com uma exceção.
**Nota: Alteração na ordem de resolução de credenciais**
A ordenação da resolução de credenciais descrita acima é atual para o `1.4.x+` lançamento do SDK para Kotlin. Antes do `1.4.0` lançamento, os itens número 3 e 4 foram trocados e o item 4a atual seguiu o item 4g atual.
## Especifique um provedor de credenciais
Você pode especificar um provedor de credenciais em vez de usar a cadeia de fornecedores padrão. Essa abordagem oferece controle direto sobre quais credenciais o SDK usa.
Por exemplo, para usar as credenciais de uma função presumida do IAM, especifique um `StsAssumeRoleCredentialsProvider` ao criar o cliente:
```
val ddb = DynamoDbClient {
region = "us-east-1"
credentialsProvider = StsAssumeRoleCredentialsProvider()
}
```
Você também pode criar uma cadeia personalizada (`CredentialsProviderChain`) que combina vários fornecedores em seu pedido preferido.
### Credenciais de cache com um provedor autônomo
**Importante**
A cadeia padrão armazena as credenciais em cache automaticamente. Provedores autônomos não armazenam credenciais em cache. Para evitar a busca de credenciais em cada chamada de API, envolva seu provedor com um. `CachedCredentialsProvider` O provedor em cache busca novas credenciais somente quando as atuais expiram.
Para armazenar credenciais em cache com um provedor independente, use a `CachedCredentialsProvider` classe:
```
val ddb = DynamoDbClient {
region = "us-east-1"
credentialsProvider = CachedCredentialsProvider(StsAssumeRoleCredentialsProvider())
}
```
Como alternativa, use a função `cached()` de extensão para obter um código mais conciso:
```
val ddb = DynamoDbClient {
region = "us-east-1"
credentialsProvider = StsAssumeRoleCredentialsProvider().cached()
}
```
# Configurar endpoints do cliente
Quando ele AWS SDK para Kotlin chama um AWS service (Serviço da AWS), uma de suas primeiras etapas é determinar para onde encaminhar a solicitação. O processo é conhecido como resolução de endpoint.
Você pode configurar a resolução de endpoint para o SDK ao criar um cliente de serviço. A configuração padrão para resolução de endpoints geralmente é boa, mas há vários motivos que podem levar você a modificar a configuração padrão. Estes são dois exemplos de motivos:
+ Faça solicitações para uma versão de pré-lançamento de um serviço ou para uma implantação local de um serviço.
+ Acesso a recursos de serviço específicos ainda não modelados no SDK.
**Atenção**
A resolução de endpoints é um tópico avançado do SDK. Se você alterar as configurações padrão, corre o risco de quebrar seu código. As configurações padrão devem ser aplicadas à maioria dos usuários em ambientes de produção.
## Configuração personalizada
Você pode personalizar a resolução do endpoint de um cliente de serviço com duas propriedades que estão disponíveis ao criar o cliente:
1. `endpointUrl: Url`
1. `endpointProvider: EndpointProvider`
### Definir `endpointUrl`
Você pode definir um valor para `endpointUrl` para indicar um nome de host “base” para o serviço. Esse valor, no entanto, não é final, pois é passado como parâmetro para a instância `EndpointProvider` do cliente. A `EndpointProvider` implementação então pode inspecionar e potencialmente modificar esse valor para determinar o endpoint final.
Por exemplo, se você especificar um `endpointUrl` valor para um cliente do Amazon Simple Storage Service (Amazon S3) e realizar `GetObject` uma operação, a implementação padrão do provedor de endpoint injeta o nome do bucket no valor do nome do host.
Na prática, os usuários definem um `endpointUrl` valor para apontar para uma instância de desenvolvimento ou pré-visualização de um serviço.
### Definir `endpointProvider`
A `EndpointProvider` implementação de um cliente de serviço determina a resolução final do endpoint. A `EndpointProvider` interface mostrada no bloco de código a seguir expõe o `resolveEndpoint` método.
```
public fun interface EndpointProvider {
public suspend fun resolveEndpoint(params: T): Endpoint
}
```
Um cliente de serviço chama o `resolveEndpoint` método para cada solicitação. O cliente do serviço usa o `Endpoint` valor retornado pelo provedor sem alterações adicionais.
#### Propriedades do `EndpointProvider`
O `resolveEndpoint` método aceita um `EndpointParameters` objeto específico do serviço que contém propriedades usadas na resolução de endpoints.
Cada serviço inclui as seguintes propriedades básicas.
****
| Nome | Tipo | Description |
| --- | --- | --- |
| region | String | A AWS região do cliente |
| endpoint | String | Uma representação de string conjunto de valores de endpointUrl |
| useFips | Booleano | Se os endpoints FIPS estiverem habilitados na configuração do cliente |
| useDualStack | Booleano | Se os endpoints de pilha dupla estiverem habilitados na configuração do cliente |
Os serviços podem especificar propriedades adicionais necessárias para a resolução. Por exemplo, o Amazon S3 [https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3.endpoints/-s3-endpoint-parameters/index.html](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3.endpoints/-s3-endpoint-parameters/index.html)inclui o nome do bucket e também várias configurações de recursos específicos do Amazon S3. Por exemplo, a propriedade `forcePathStyle` determina se o endereço do host virtual pode ser usado.
Se você implementar seu próprio provedor, não precisará criar sua própria instância do`EndpointParameters`. O SDK fornece as propriedades de cada solicitação e as passa para sua implementação do `resolveEndpoint`.
### `endpointUrl` ou `endpointProvider`
É importante entender que as duas declarações a seguir NÃO produzem clientes com comportamento de resolução de endpoint equivalente:
```
// Use endpointUrl.
S3Client.fromEnvironment {
endpointUrl = Url.parse("https://endpoint.example")
}
// Use endpointProvider.
S3Client.fromEnvironment {
endpointProvider = object : S3EndpointProvider {
override suspend fun resolveEndpoint(params: S3EndpointParameters): Endpoint = Endpoint("https://endpoint.example")
}
}
```
A declaração que define a `endpointUrl` propriedade especifica uma URL *base* que é passada para o provedor (padrão), que pode ser modificada como parte da resolução do endpoint.
A declaração que define o `endpointProvider` especifica o URL *final* que ele `S3Client` usa.
Embora você possa definir as duas propriedades, na maioria dos casos que precisam de personalização, você fornece uma delas. Como usuário geral do SDK, você geralmente fornece um `endpointUrl` valor.
### Uma observação sobre o Amazon S3
O Amazon S3 é um serviço complexo com muitos de seus recursos modelados por meio de personalizações personalizadas de endpoints, como hospedagem virtual de bucket. A hospedagem virtual é um recurso do Amazon S3 em que o nome do bucket é inserido no nome do host.
Por isso, recomendamos que você não substitua a `EndpointProvider` implementação em um cliente de serviço do Amazon S3. Se você precisar estender seu comportamento de resolução, talvez enviando solicitações para uma pilha de desenvolvimento local com considerações adicionais de endpoint, recomendamos incluir a implementação padrão. O `endpointProvider` exemplo a seguir mostra um exemplo de implementação dessa abordagem.
## Exemplos
### Exemplo de `endpointUrl`
O trecho de código a seguir mostra como o endpoint de serviço geral pode ser substituído por um cliente Amazon S3.
```
val client = S3Client.fromEnvironment {
endpointUrl = Url.parse("https://custom-s3-endpoint.local")
// EndpointProvider is left as the default.
}
```
### Exemplo de `endpointProvider`
O trecho de código a seguir mostra como fornecer um provedor de endpoint personalizado que encapsule a implementação padrão para o Amazon S3.
```
import aws.sdk.kotlin.services.s3.endpoints.DefaultS3EndpointProvider
import aws.sdk.kotlin.services.s3.endpoints.S3EndpointParameters
import aws.sdk.kotlin.services.s3.endpoints.S3EndpointProvider
import aws.smithy.kotlin.runtime.client.endpoints.Endpoint
public class CustomS3EndpointProvider : S3EndpointProvider {
override suspend fun resolveEndpoint(params: S3EndpointParameters) =
if (/* Input params indicate we must route another endpoint for whatever reason. */) {
Endpoint(/* ... */)
} else {
// Fall back to the default resolution.
DefaultS3EndpointProvider().resolveEndpoint(params)
}
}
```
### `endpointUrl` e `endpointProvider`
O programa de exemplo a seguir demonstra a interação entre as `endpointProvider` configurações `endpointUrl` e. Esse é um caso de uso avançado.
```
import aws.sdk.kotlin.services.s3.S3Client
import aws.sdk.kotlin.services.s3.endpoints.DefaultS3EndpointProvider
import aws.sdk.kotlin.services.s3.endpoints.S3EndpointParameters
import aws.sdk.kotlin.services.s3.endpoints.S3EndpointProvider
import aws.smithy.kotlin.runtime.client.endpoints.Endpoint
fun main() = runBlocking {
S3Client.fromEnvironment {
endpointUrl = Url.parse("https://example.endpoint")
endpointProvider = CustomS3EndpointProvider()
}.use { s3 ->
// ...
}
}
class CustomS3EndpointProvider : S3EndpointProvider {
override suspend fun resolveEndpoint(params: S3EndpointParameters) {
// The resolved string value of the endpointUrl set in the client above is available here.
println(params.endpoint)
// ...
}
}
```
# HTTP
Esta seção aborda a configuração das configurações relacionadas ao HTTP no. AWS SDK para Kotlin
**Topics**
+ [Configuração do cliente HTTP](http-client-config.md)
+ [Usar um proxy HTTP](using-http-proxy.md)
+ [Interceptadores HTTP](interceptors.md)
+ [Aplicar uma versão mínima do TLS](configure-http-tls.md)
# Configuração do cliente HTTP
Por padrão, o AWS SDK para Kotlin usa um cliente HTTP baseado em [OkHttp](https://square.github.io/okhttp). Você pode substituir o cliente HTTP e sua configuração fornecendo um cliente explicitamente configurado.
**Atenção**
Independentemente de qual mecanismo HTTP você usa, outras dependências em seu projeto podem ter dependências transitivas que entram em conflito com a versão específica do mecanismo exigida pelo SDK. Em particular, estruturas como o Spring Boot são conhecidas por gerenciar dependências OkHttp e confiar em versões mais antigas do que o SDK. Consulte [Como faço para resolver conflitos de dependência?](ts-faq-dep-conflict-resolution.md) para obter mais informações.
**nota**
Por padrão, cada cliente de serviço usa sua própria cópia de um cliente HTTP. Se você usa vários serviços em seu aplicativo, talvez queira criar um único cliente HTTP e compartilhá-lo com todos os clientes de serviço.
## Configuração básica
Ao configurar um cliente de serviço, você pode configurar o tipo de mecanismo padrão. O SDK gerencia o mecanismo do cliente HTTP resultante e o fecha automaticamente quando não é mais necessário.
O exemplo a seguir mostra a configuração de um cliente HTTP durante a inicialização de um cliente do DynamoDB.
### Importações
```
import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import kotlin.time.Duration.Companion.seconds
```
### Código
```
DynamoDbClient {
region = "us-east-2"
httpClient {
maxConcurrency = 64u
connectTimeout = 10.seconds
}
}.use { ddb ->
// Perform some actions with Amazon DynamoDB.
}
```
## Configurações avançadas
A configuração HTTP padrão é adequada para a maioria dos casos de uso. Para alguns casos de uso avançados, como ambientes de alto rendimento, as seguintes opções de configuração avançada fornecem recursos e capacidades adicionais:
### Especifique um tipo de mecanismo HTTP
Para especificar um tipo de mecanismo HTTP não padrão ou para personalizar a configuração específica de um determinado tipo de mecanismo HTTP, você pode passar um parâmetro adicional `httpClient` que especifique o tipo de mecanismo.
O exemplo a seguir especifica o [https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine/index.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine/index.html)que você pode usar para configurar a [https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine-config/index.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine-config/index.html)propriedade.
#### Importações
```
import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import aws.smithy.kotlin.runtime.http.engine.okhttp.OkHttpEngine
```
#### Código
```
DynamoDbClient {
region = "us-east-2"
httpClient(OkHttpEngine) { // The first parameter specifies the HTTP engine type.
// The following parameter is generic HTTP configuration available in any engine type.
maxConcurrency = 64u
// The following parameter is OkHttp-specific configuration.
maxConcurrencyPerHost = 32u
}
}.use { ddb ->
// Perform some actions with Amazon DynamoDB.
}
```
Os valores possíveis para o tipo de motor são `OkHttpEngine` [https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp4/aws.smithy.kotlin.runtime.http.engine.okhttp4/-ok-http4-engine/index.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp4/aws.smithy.kotlin.runtime.http.engine.okhttp4/-ok-http4-engine/index.html), [https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-crt/aws.smithy.kotlin.runtime.http.engine.crt/-crt-http-engine/index.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-crt/aws.smithy.kotlin.runtime.http.engine.crt/-crt-http-engine/index.html)e.
Para usar parâmetros de configuração específicos de um mecanismo HTTP, você deve adicionar o mecanismo como uma dependência em tempo de compilação. Para o`OkHttpEngine`, você adiciona a seguinte dependência usando o Gradle.
(Você pode navegar até o *X.Y.Z* link para ver a versão mais recente disponível.)
```
implementation(platform("aws.smithy.kotlin:bom:[https://github.com/smithy-lang/smithy-kotlin/releases/latest](https://github.com/smithy-lang/smithy-kotlin/releases/latest)"))
implementation("aws.smithy.kotlin:http-client-engine-okhttp")
```
Para o`CrtHttpEngine`, adicione a seguinte dependência.
```
implementation(platform("aws.smithy.kotlin:bom:[https://github.com/smithy-lang/smithy-kotlin/releases/latest](https://github.com/smithy-lang/smithy-kotlin/releases/latest)"))
implementation("aws.smithy.kotlin:http-client-engine-crt")
```
#### Usar a `OkHttp4Engine`
Use o `OkHttp4Engine` se você não puder usar o padrão`OkHttpEngine`. O [ GitHub repositório smithy-kotlin](https://github.com/smithy-lang/smithy-kotlin/tree/main/runtime/protocol/http-client-engines/http-client-engine-okhttp4) tem informações sobre como você configura e usa o. `OkHttp4Engine`
#### Use um cliente HTTP explícito
Quando você usa um cliente HTTP explícito, você é responsável por sua vida útil, incluindo o fechamento quando não precisa mais dele. Um cliente HTTP deve durar pelo menos tanto quanto qualquer cliente de serviço que o use.
O exemplo de código a seguir mostra o código que mantém o cliente HTTP ativo enquanto o `DynamoDbClient` está ativo. A [https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.io/use.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.io/use.html)função garante que o cliente HTTP feche corretamente.
##### Importações
```
import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import aws.smithy.kotlin.runtime.http.engine.okhttp.OkHttpEngine
import kotlin.time.Duration.Companion.seconds
```
##### Código
```
OkHttpEngine {
maxConcurrency = 64u
connectTimeout = 10.seconds
}.use { okHttpClient ->
DynamoDbClient {
region = "us-east-2"
httpClient = okHttpClient
}.use { ddb ->
{
// Perform some actions with Amazon DynamoDB.
}
}
}
```
### Monitoramento de conexão ociosa
**Importante**
O recurso de OkHttp pesquisa de marcha lenta da conexão ([https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine-config/connection-idle-polling-interval.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine-config/connection-idle-polling-interval.html)) foi substituído por novas tentativas automáticas de falha de conexão (). [https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine-config/retry-on-connection-failure.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine-config/retry-on-connection-failure.html) ****A pesquisa de conexão ociosa será **descontinuada** na versão **v1.7 do SDK e será removida na versão v1.8** do SDK.**** Consulte [a postagem de GitHub discussão relacionada](https://github.com/aws/aws-sdk-kotlin/discussions/1797) para obter mais detalhes.
[https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine/](https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine/)fornece a opção [https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine-config/connection-idle-polling-interval.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/http-client-engine-okhttp/aws.smithy.kotlin.runtime.http.engine.okhttp/-ok-http-engine-config/connection-idle-polling-interval.html)de configuração para monitorar conexões ociosas para fechamento remoto. Esse recurso detecta quando os serviços têm conexões fechadas que ainda estão no pool de conexões, evitando erros nas solicitações subsequentes.
Quando `connectionIdlePollingInterval` definido como um valor não nulo, o mecanismo pesquisa as conexões que são liberadas de volta para o pool de conexões. O processo de pesquisa realiza leituras de bloqueio com o tempo limite do soquete definido para o intervalo especificado. A pesquisa é cancelada automaticamente quando o motor adquire a conexão do pool ou quando a conexão é despejada e fechada.
Quando esse valor é `null` (o padrão), a pesquisa é desativada. Conexões ociosas no pool que são fechadas remotamente podem encontrar erros ao serem adquiridas para chamadas subsequentes.
**nota**
Como o ciclo de pesquisa usa leituras de bloqueio, as chamadas do mecanismo para adquirir ou fechar uma conexão podem ser atrasadas tanto quanto o `connectionIdlePollingInterval` intervalo. Escolher um valor baixo para o intervalo significa que o SDK adquirirá conexões mais rapidamente, às custas de um maior uso de recursos ociosos.
#### Importações
```
import aws.sdk.kotlin.services.s3.S3Client
import aws.smithy.kotlin.runtime.http.engine.okhttp.OkHttpEngine
import kotlin.time.Duration.Companion.milliseconds
```
#### Código
```
S3Client.fromEnvironment {
httpEngine(OkHttpEngine) {
connectionIdlePollingInterval = 50.milliseconds
}
}.use { s3 ->
// Use the Amazon S3 client
}
```
# Usar um proxy HTTP
Para acessar AWS por meio de servidores proxy usando o AWS SDK para Kotlin, você pode configurar as propriedades do sistema JVM ou as variáveis de ambiente. Se ambos forem fornecidos, as propriedades do sistema JVM terão precedência.
## Usar propriedade do sistema de JVM
O SDK procura as propriedades do sistema JVM`https.proxyHost`, e. `https.proxyPort` `http.nonProxyHosts` Para obter mais informações sobre essas propriedades comuns do sistema JVM, consulte [Rede e proxies](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html) na documentação do Java.
```
java -Dhttps.proxyHost=10.15.20.25 -Dhttps.proxyPort=1234 -Dhttp.nonProxyHosts=localhost|api.example.com MyApplication
```
## Use variáveis de ambiente
O SDK procura as variáveis de `no_proxy` ambiente`https_proxy`,`http_proxy`, e (e as versões em maiúsculas de cada uma).
```
export http_proxy=http://10.15.20.25:1234
export https_proxy=http://10.15.20.25:5678
export no_proxy=localhost,api.example.com
```
## Use um proxy em instâncias do EC2
Se você configurar um proxy em uma instância do EC2 executada com uma função do IAM anexada, certifique-se de isentar o endereço usado para acessar os metadados da [instância](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html). Para fazer isso, defina a propriedade do sistema `http.nonProxyHosts` JVM ou a variável de `no_proxy` ambiente como o endereço IP do Serviço de Metadados da Instância, que é. `169.254.169.254` Esse endereço não varia.
```
export no_proxy=169.254.169.254
```
# Interceptadores HTTP
Você pode usar interceptores para se conectar à execução de solicitações e respostas de API. Os interceptores são mecanismos abertos nos quais o SDK chama o código que você grava para injetar comportamento no ciclo de vida. request/response Dessa maneira, é possível modificar uma solicitação em andamento, depurar o processamento da solicitação, visualizar exceções e muito mais.
O exemplo a seguir mostra um interceptor simples que adiciona um cabeçalho adicional a todas as solicitações de saída antes que o loop de repetição seja inserido.
```
class AddHeader(
private val key: String,
private val value: String
) : HttpInterceptor {
override suspend fun modifyBeforeRetryLoop(context: ProtocolRequestInterceptorContext): HttpRequest {
val httpReqBuilder = context.protocolRequest.toBuilder()
httpReqBuilder.headers[key] = value
return httpReqBuilder.build()
}
}
```
Para obter mais informações e os ganchos de interceptação disponíveis, consulte a interface do [Interceptor](https://docs.aws.amazon.com/smithy-kotlin/api/latest/smithy-client/aws.smithy.kotlin.runtime.client/-interceptor/index.html).
## Registro de interceptor
Você registra interceptores ao construir um cliente de serviço ou ao substituir a configuração de um conjunto específico de operações.
### Interceptor para todas as operações do cliente de serviço
O código a seguir adiciona uma `AddHeader` instância à propriedade interceptors do construtor. Essa adição adiciona o `x-foo-version` cabeçalho a todas as operações antes que o loop de repetição seja inserido.
```
val s3 = S3Client.fromEnvironment {
interceptors += AddHeader("x-foo-version", "1.0")
}
// All service operations invoked using 's3' will have the header appended.
s3.listBuckets { ... }
s3.listObjectsV2 { ... }
```
### Interceptor somente para operações específicas
Usando a `withConfig` extensão, você pode [substituir a configuração do cliente de serviço](override-client-config.md) para uma ou mais operações para qualquer cliente de serviço. Com esse recurso, você pode registrar interceptores adicionais para um subconjunto de operações.
O exemplo a seguir substitui a configuração da `s3` instância para operações dentro da `use` extensão. As operações chamadas `s3Scoped` contêm os cabeçalhos `x-foo-version` e os `x-bar-version` cabeçalhos.
```
// 's3' instance created in the previous code snippet.
s3.withConfig {
interceptors += AddHeader("x-bar-version", "3.7")
}.use { s3Scoped ->
// All service operations invoked using 's3Scoped' trigger interceptors
// that were registered when the client was created and any added in the
// withConfig { ... } extension.
}
```
# Aplicar uma versão mínima do TLS
Com o AWS SDK para Kotlin, você pode configurar a versão mínima do TLS ao se conectar aos endpoints de serviço. O SDK oferece diferentes opções de configuração. Na ordem da maior para a menor precedência, as opções são:
+ Configurar explicitamente o mecanismo HTTP
+ Definir a propriedade do `sdk.minTls` sistema JVM
+ Defina a variável de `SDK_MIN_TLS` ambiente
## Configurar o mecanismo HTTP
Ao especificar um mecanismo HTTP não padrão para um cliente de serviço, você pode definir o `tlsContext.minVersion` campo.
O exemplo a seguir configura o mecanismo HTTP e qualquer cliente de serviço que o usa para usar o TLS v1.2 no mínimo.
```
DynamoDbClient {
region = "us-east-2"
httpClient {
tlsContext {
minVersion = TlsVersion.TLS_1_2
}
}
}.use { ddb ->
// Perform some actions with Amazon DynamoDB.
}
```
## Definir a propriedade do `sdk.minTls` sistema JVM
Você pode definir a propriedade do sistema `sdk.minTls` JVM. Quando você inicia um aplicativo com a propriedade do sistema definida, todos os mecanismos HTTP criados pelo AWS SDK para Kotlin usam a versão mínima especificada do TLS por padrão. No entanto, você pode substituir isso explicitamente na configuração do mecanismo HTTP. Os valores permitidos são:
+ TLS\$11\$10
+ TLS\$11\$11
+ TLS\$11\$12
+ TLS\$11\$13
## Defina a variável de `SDK_MIN_TLS` ambiente
Você pode definir a variável de `SDK_MIN_TLS` ambiente. Quando você inicia um aplicativo com a variável de ambiente definida, todos os mecanismos HTTP criados pelo AWS SDK para Kotlin usam a versão mínima especificada do TLS, a menos que sejam substituídos por outra opção.
Os valores permitidos são:
+ TLS\$11\$10
+ TLS\$11\$11
+ TLS\$11\$12
+ TLS\$11\$13
# Tentativas novamente no AWS SDK para Kotlin
Ligações para retornar Serviços da AWS ocasionalmente exceções inesperadas. Determinados tipos de erros, como erros transitórios ou de controle de utilização, podem ser bem-sucedidos se a chamada for repetida.
Esta página descreve como ele AWS SDK para Kotlin lida com novas tentativas automaticamente e como personalizar o comportamento de repetição para seus aplicativos.
## Entendendo o comportamento de repetição
As seções a seguir explicam como o SDK determina quando repetir as solicitações e quais exceções são consideradas passíveis de nova tentativa.
### Configuração padrão de novas tentativas
Por padrão, cada cliente de serviço é configurado automaticamente com uma [estratégia de repetição padrão](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.retries/-standard-retry-strategy/index.html). A configuração padrão tenta uma chamada que falha até três vezes (a tentativa inicial mais duas tentativas). O atraso intermediário entre cada chamada é configurado com recuo exponencial e instabilidade aleatória para evitar tempestades de novas tentativas. Essa configuração funciona para a maioria dos casos de uso, mas pode ser inadequada em algumas circunstâncias, como sistemas de alto rendimento.
O SDK tenta novas tentativas somente em caso de erros que possam ser repetidos. Exemplos de erros que podem ser repetidos são tempos limite de soquete, controle de utilização do lado do serviço, falhas de simultaneidade ou bloqueio positivo e erros transitórios de serviço. Parâmetros ausentes ou inválidos, authentication/security erros e exceções de configuração incorreta não são considerados passíveis de nova tentativa.
Você pode personalizar a estratégia de repetição padrão definindo o máximo de tentativas, atrasos e recuos e a configuração do token bucket.
### Quais exceções podem ser repetidas?
O AWS SDK para Kotlin usa uma política de repetição pré-configurada que determina quais exceções podem ser repetidas. A configuração do cliente de serviço tem uma `retryPolicy` propriedade que especifica a política aplicada às novas tentativas. Se nenhum valor personalizado for especificado, o valor padrão será [AwsRetryPolicy](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/aws-http/aws.sdk.kotlin.runtime.http.retries/-aws-retry-policy/).
As seguintes exceções foram determinadas como passíveis de nova tentativa por: `AwsRetryPolicy`
#### Tentável novamente por código de erro
Qualquer um `ServiceException` com um `sdkErrorMetadata.errorCode` dos seguintes:
+ `BandwidthLimitExceeded`
+ `EC2ThrottledException`
+ `IDPCommunicationError`
+ `LimitExceededException`
+ `PriorRequestNotComplete`
+ `ProvisionedThroughputExceededException`
+ `RequestLimitExceeded`
+ `RequestThrottled`
+ `RequestThrottledException`
+ `RequestTimeout`
+ `RequestTimeoutException`
+ `SlowDown`
+ `ThrottledException`
+ `Throttling`
+ `ThrottlingException`
+ `TooManyRequestsException`
+ `TransactionInProgressException`
#### Tentável novamente pelo código de status HTTP
Qualquer um `ServiceException` com um `sdkErrorMetadata.statusCode` dos seguintes:
+ 500 (Erro de serviço interno)
+ 502 (Gateway inválido)
+ 503 (Serviço indisponível)
+ 504 (Tempo limite do gateway)
#### Tentável novamente por tipo de erro
Qualquer um `ServiceException` com um `sdkErrorMetadata.errorType` dos seguintes:
+ `ErrorType.Server`(como erros internos de serviço)
+ `ErrorType.Client`(como uma solicitação inválida, um recurso não encontrado, acesso negado etc.)
#### Tentável novamente por metadados do SDK
Em qualquer `SdkBaseException` lugar:
+ `sdkErrorMetadata.isRetryable`é `true` (como um tempo limite do lado do cliente, networking/socket erro etc.)
+ `sdkErrorMetadata.isThrottling`é `true` (como fazer muitas solicitações em um curto espaço de tempo)
Para obter uma lista completa das exceções que podem ser lançadas por cada cliente de serviço, consulte a documentação de referência da [API específica do serviço](https://docs.aws.amazon.com/#products).
### Verifique se uma exceção pode ser repetida
Para determinar se o SDK considera uma exceção passível de repetição, verifique a `isRetryable` propriedade das exceções detectadas:
```
try {
dynamoDbClient.putItem {
tableName = "MyTable"
item = mapOf("id" to AttributeValue.S("123"))
}
} catch (e: SdkBaseException) {
println("Exception occurred: ${e.message}")
if (e.sdkErrorMetadata.isRetryable) {
println("This exception is retryable - SDK will automatically retry")
println("If you're seeing this, retries may have been exhausted")
} else {
println("This exception is not retryable - fix the underlying issue")
// Common non-retryable scenarios.
when {
e.message?.contains("ValidationException") == true ->
println("Check your request parameters")
e.message?.contains("AccessDenied") == true ->
println("Check your IAM permissions")
e.message?.contains("ResourceNotFound") == true ->
println("Verify the resource exists")
}
}
}
```
### Quais exceções chegam ao seu código quando as novas tentativas falham
Quando o mecanismo de repetição do SDK não consegue resolver um problema, exceções são lançadas no código do aplicativo. Compreender esses tipos de exceção ajuda você a implementar o tratamento adequado de erros. Essas *não* são as exceções que acionam as tentativas. Elas são tratadas internamente pelo SDK.
Seu código detectará os seguintes tipos de exceções quando as novas tentativas forem esgotadas ou desativadas:
Exceções de serviço após nova tentativa de exaustão
Quando todas as tentativas de repetição falham, seu código captura a exceção de serviço final (subclasse de`AwsServiceException`) que causou a falha na última tentativa de repetição. Isso pode ser um erro de limitação, erro do servidor ou outra exceção específica do serviço que o SDK não conseguiu resolver por meio de novas tentativas.
Exceções de rede após a exaustão de novas tentativas
Quando os problemas de rede persistem em todas as tentativas, seu código detecta `ClientException` instâncias com problemas como tempos limite de conexão, falhas na resolução de DNS e outros problemas de conectividade que o SDK não conseguiu resolver.
Use o padrão a seguir para lidar com essas exceções em seu aplicativo:
```
try {
s3Client.getObject {
bucket = "amzn-s3-demo-bucket"
key = "my-key"
}
} catch (e: AwsServiceException) {
// Service-side errors that persisted through all retries.
println("Service error after retries: ${e.errorDetails?.errorCode} - ${e.message}")
// Handle specific service errors that couldn't be resolved.
if (e.errorDetails?.errorCode == "ServiceQuotaExceededException" ||
e.errorDetails?.errorCode == "ThrottlingException") {
println("Rate limiting persisted - consider longer delays or quota increase")
}
} catch (e: ClientException) {
// Client-side errors (persistent network issues, DNS resolution failures, etc.)
println("Client error after retries: ${e.message}")
}
```
## Personalizando o comportamento de repetição
As seções a seguir mostram como personalizar o comportamento de repetição do SDK para seu caso de uso específico.
### Configurar o máximo de tentativas
Você pode personalizar o máximo padrão de tentativas (3) no [bloco `retryStrategy` DSL](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.retries/-standard-retry-strategy/-config/-builder/index.html) durante a construção do cliente.
```
val dynamoDb = DynamoDbClient.fromEnvironment {
retryStrategy {
maxAttempts = 5
}
}
```
Com o cliente de serviço do DynamoDB mostrado no snippet anterior, o SDK tenta chamadas de API que falham até cinco vezes (a tentativa inicial mais quatro tentativas).
Você pode desativar completamente as novas tentativas automáticas definindo o máximo de tentativas como uma, conforme mostrado no trecho a seguir.
```
val dynamoDb = DynamoDbClient.fromEnvironment {
retryStrategy {
maxAttempts = 1 // The SDK makes no retries.
}
}
```
### Configure atrasos e recuos
Se uma nova tentativa for necessária, a estratégia de nova tentativa padrão aguarda antes de fazer a tentativa subsequente. O atraso na primeira tentativa é pequeno, mas cresce exponencialmente nas tentativas posteriores. A quantidade máxima de atraso é limitada para não aumentar muito.
Finalmente, a instabilidade aleatória é aplicada aos atrasos entre todas as tentativas. A instabilidade ajuda a mitigar o efeito de grandes frotas que podem causar tempestades de novas tentativas. (Veja esta [postagem no blog de AWS arquitetura](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) para uma discussão mais profunda sobre recuo exponencial e instabilidade.)
Os parâmetros de atraso são configuráveis no bloco [`delayProvider`DSL.](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.retries.delay/-exponential-backoff-with-jitter/-config/index.html)
```
val dynamoDb = DynamoDbClient.fromEnvironment {
retryStrategy {
delayProvider {
initialDelay = 100.milliseconds
maxBackoff = 5.seconds
}
}
}
```
Com a configuração mostrada no trecho anterior, o cliente atrasa a primeira tentativa em até 100 milissegundos. O tempo máximo entre qualquer tentativa de repetição é de 5 segundos.
Os parâmetros a seguir estão disponíveis para atrasos de ajuste e recuo.
| Parâmetro | Valor padrão | Description |
| --- | --- | --- |
| initialDelay | 10 milissegundos | A quantidade máxima de atraso para a primeira tentativa. Quando a instabilidade é aplicada, a quantidade real de atraso pode ser menor. |
| jitter | 1.0 (instabilidade total) | A amplitude máxima pela qual reduzir aleatoriamente o atraso calculado. O valor padrão de 1,0 significa que o atraso calculado pode ser reduzido para qualquer valor de até 100% (por exemplo, até 0). Um valor de 0,5 significa que o atraso calculado pode ser reduzido em até metade. Assim, um atraso máximo de 10 ms pode ser reduzido para algo entre 5 ms e 10 ms. Um valor de 0,0 significa que nenhuma instabilidade é aplicada. ️ A configuração do Jitter é um recurso avançado. A personalização desse comportamento normalmente não é recomendada. |
| maxBackoff | 20 segundos | A quantidade máxima de atraso a ser aplicada a qualquer tentativa. Definir esse valor limita o crescimento exponencial que ocorre entre as tentativas subsequentes e evita que o máximo calculado seja muito grande. Esse parâmetro limita o atraso calculado antes que a instabilidade seja aplicada. Se aplicada, a instabilidade pode reduzir ainda mais o atraso. |
| scaleFactor | 1.5 | A base exponencial pela qual os atrasos máximos subsequentes serão aumentados. Por exemplo, considerando um `initialDelay` de 10 ms e um `scaleFactor` de 1,5, os seguintes atrasos máximos seriam calculados:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-kotlin/latest/developer-guide/retries.html)Quando a instabilidade é aplicada, a quantidade real de cada atraso pode ser menor. |
### Configurar o repositório de tokens de nova tentativa
Você pode modificar ainda mais o comportamento da estratégia de repetição padrão ajustando a configuração padrão do token bucket. O repositório de tokens de repetição ajuda a reduzir as novas tentativas com menor probabilidade de sucesso ou que podem levar mais tempo para serem resolvidas, como falhas de tempo limite e limitação.
**Importante**
A configuração do token bucket é um recurso avançado. A personalização desse comportamento normalmente não é recomendada.
Cada tentativa de nova tentativa (opcionalmente incluindo a tentativa inicial) diminui parte da capacidade do token bucket. O valor diminuído depende do tipo de tentativa. Por exemplo, tentar novamente erros transitórios pode ser barato, mas tentar novamente erros de tempo limite ou de limitação pode ser mais caro.
Uma tentativa bem-sucedida retorna a capacidade para o bucket. O balde não pode ser incrementado além de sua capacidade máxima nem diminuído abaixo de zero.
Dependendo do valor da `useCircuitBreakerMode` configuração, as tentativas de diminuir a capacidade abaixo de zero resultam em um dos seguintes resultados:
+ Se a configuração for TRUE, uma exceção será lançada — por exemplo, se muitas tentativas tiverem ocorrido e for improvável que mais tentativas sejam bem-sucedidas.
+ Se a configuração for FALSA, haverá um atraso — por exemplo, atrasos até que o bucket tenha capacidade suficiente novamente.
**nota**
Quando o disjuntor é ativado (o token bucket atinge a capacidade zero), o SDK emite um `ClientException` com a mensagem “Capacidade de repetição excedida”. Essa é uma exceção do lado do cliente, não uma`AwsServiceException`, porque se origina da lógica de repetição do SDK e não do serviço. AWS A exceção é lançada imediatamente sem tentar a operação, ajudando a evitar novas tentativas durante interrupções no serviço.
Os parâmetros do token bucket são configuráveis no bloco [`tokenBucket`DSL:](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.retries.delay/-standard-retry-token-bucket/-config/index.html)
```
val dynamoDb = DynamoDbClient.fromEnvironment {
retryStrategy {
tokenBucket {
maxCapacity = 100
refillUnitsPerSecond = 2
}
}
}
```
Os parâmetros a seguir estão disponíveis para ajustar o repositório de tokens de repetição:
| Parâmetro | Valor padrão | Description |
| --- | --- | --- |
| initialTryCost | 0 | O valor a ser diminuído do intervalo nas tentativas iniciais. O valor padrão de 0 significa que nenhuma capacidade será diminuída e, portanto, as tentativas iniciais não serão interrompidas ou atrasadas. |
| initialTrySuccessIncrement | 1 | O valor para incrementar a capacidade quando a tentativa inicial foi bem-sucedida. |
| maxCapacity | 500 | A capacidade máxima do token bucket. O número de tokens disponíveis não pode exceder esse número. |
| refillUnitsPerSecond | 0 | A quantidade de capacidade adicionada novamente ao balde a cada segundo. Um valor de 0 significa que nenhuma capacidade é adicionada novamente automaticamente. (Por exemplo, somente tentativas bem-sucedidas resultam no aumento da capacidade). Um valor de 0 useCircuitBreakerMode precisa ser VERDADEIRO. |
| retryCost | 5 | A quantidade a ser diminuída do compartimento em caso de uma tentativa após uma falha transitória. A mesma quantidade é reincrementada de volta para o bucket se a tentativa for bem-sucedida. |
| timeoutRetryCost | 10 | O valor a ser diminuído do bucket por uma tentativa após uma falha de tempo limite ou limitação. A mesma quantidade é reincrementada de volta para o bucket se a tentativa for bem-sucedida. |
| useCircuitBreakerMode | TRUE | Determina o comportamento quando uma tentativa de diminuir a capacidade faria com que a capacidade do bucket caísse abaixo de zero. Quando TRUE, o token bucket lançará uma exceção indicando que não existe mais capacidade de repetição. Quando FALSO, o token bucket atrasará a tentativa até que a capacidade suficiente seja reabastecida. |
Para obter informações detalhadas sobre os tipos de exceção lançados durante cenários de repetição, incluindo exceções de disjuntores, consulte. [Quais exceções chegam ao seu código quando as novas tentativas falham](#retries-exception-types-during-retries)
### Configurar novas tentativas adaptáveis
Como alternativa à estratégia de repetição padrão, a estratégia de repetição adaptativa é uma abordagem avançada que busca a taxa de solicitação ideal para minimizar os erros de limitação.
**Importante**
As novas tentativas adaptáveis são um modo de nova tentativa avançado. Normalmente, não é recomendável usar essa estratégia de repetição.
As novas tentativas adaptáveis incluem todos os recursos das novas tentativas padrão. Isso adiciona um limitador de taxa do lado do cliente que mede a taxa de solicitações de controle de utilização em comparação com solicitações sem o controle. Também limita o tráfego para tentar permanecer em uma largura de banda segura, o que, idealmente, não causa nenhum erro de controle de utilização.
A taxa se adapta em tempo real às mudanças nas condições de serviço e nos padrões de tráfego e pode aumentar ou diminuir a taxa de tráfego de acordo. Fundamentalmente, o limitador de taxa pode atrasar as tentativas iniciais em cenários de tráfego intenso.
Você seleciona a estratégia de repetição adaptativa fornecendo um parâmetro adicional ao `retryStrategy` método. Os parâmetros do limitador de taxa são configuráveis no bloco [`rateLimiter`DSL](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.retries.delay/-adaptive-rate-limiter/-config/index.html).
```
val dynamoDb = DynamoDbClient.fromEnvironment {
retryStrategy(AdaptiveRetryStrategy) {
maxAttempts = 10
rateLimiter {
minFillRate = 1.0
smoothing = 0.75
}
}
}
```
**nota**
A estratégia de novas tentativas adaptável pressupõe que o cliente trabalhe com um único recurso (por exemplo, uma tabela do DynamoDB ou um bucket do Amazon S3).
Se você usa um único cliente para vários recursos, o controle de utilização ou as interrupções associadas a um recurso resultam em maior latência e falhas quando o cliente acessa todos os outros recursos. Ao usar a estratégia de novas tentativas adaptável, recomendamos que você use um único cliente para cada recurso.
# Observabilidade
Observabilidade é a medida em que o estado atual de um sistema pode ser identificado com base nos dados que ele emite. Os dados emitidos são chamados, com frequência, de telemetria.
Eles AWS SDK para Kotlin podem fornecer todos os três sinais comuns de telemetria: métricas, rastreamentos e registros. Você pode conectar um [https://docs.aws.amazon.com/smithy-kotlin/api/latest/telemetry-api/aws.smithy.kotlin.runtime.telemetry/-telemetry-provider/index.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/telemetry-api/aws.smithy.kotlin.runtime.telemetry/-telemetry-provider/index.html)para enviar dados de telemetria para um back-end de observabilidade (como a [AWS X-Ray](https://docs.aws.amazon.com/xray/?icmpid=docs_homepage_devtools)[Amazon CloudWatch](https://docs.aws.amazon.com/cloudwatch/?icmpid=docs_homepage_mgmtgov)) e, em seguida, agir de acordo com eles.
Por padrão, somente o registro está ativado e outros sinais de telemetria são desativados no SDK. Este tópico explica como habilitar e configurar a saída de telemetria.
**Importante**
`TelemetryProvider`atualmente é uma API experimental que deve ser ativada para uso.
## Configurar um `TelemetryProvider`
Você pode configurar um `TelemetryProvider` em seu aplicativo globalmente para todos os clientes de serviço ou para clientes individuais. Os exemplos a seguir usam uma `getConfiguredProvider()` função hipotética para demonstrar as operações da `TelemetryProvider` API. A [Provedores de telemetria](observability-telemetry-providers.md) seção descreve as informações para implementações fornecidas pelo SDK. Se um provedor não for compatível, você poderá implementar seu próprio suporte ou [abrir uma solicitação de recurso no GitHub](https://github.com/awslabs/aws-sdk-kotlin/issues/new/choose).
### Configurar o provedor de telemetria global padrão
Por padrão, todo cliente de serviço tenta usar o provedor de telemetria disponível globalmente. Dessa forma, é possível definir o provedor uma vez e todos os clientes o usarão. Isso deve ser feito apenas uma vez, antes de você instanciar qualquer cliente de serviço.
Para usar o provedor global de telemetria, primeiro atualize as dependências do projeto para adicionar o módulo de padrões de telemetria, conforme mostrado no seguinte trecho do Gradle.
(Você pode navegar até o *X.Y.Z* link para ver a versão mais recente disponível.)
```
dependencies {
implementation(platform("aws.smithy.kotlin:bom:[https://github.com/smithy-lang/smithy-kotlin/releases/latest](https://github.com/smithy-lang/smithy-kotlin/releases/latest)"))
implementation("aws.smithy.kotlin:telemetry-defaults")
...
}
```
Em seguida, defina o provedor de telemetria global antes de criar um cliente de serviço, conforme mostrado no código a seguir.
```
import aws.sdk.kotlin.services.s3.S3Client
import aws.smithy.kotlin.runtime.telemetry.GlobalTelemetryProvider
import kotlinx.coroutines.runBlocking
fun main() = runBlocking {
val myTelemetryProvider = getConfiguredProvider()
GlobalTelemetryProvider.set(myTelemetryProvider)
S3Client.fromEnvironment().use { s3 ->
…
}
}
fun getConfiguredProvider(): TelemetryProvider {
TODO("TODO - configure a provider")
}
```
### Configurar um provedor de telemetria para um cliente de serviço específico
É possível configurar um cliente de serviço individual com um provedor de telemetria específico (diferente do global). Isso é mostrado no exemplo a seguir.
```
import aws.sdk.kotlin.services.s3.S3Client
import kotlinx.coroutines.runBlocking
fun main() = runBlocking {
S3Client.fromEnvironment{
telemetryProvider = getConfiguredProvider()
}.use { s3 ->
...
}
}
fun getConfiguredProvider(): TelemetryProvider {
TODO("TODO - configure a provider")
}
```
# Metrics
A tabela a seguir lista as métricas de telemetria emitidas pelo SDK. [Configure um provedor de telemetria](observability.md#observability-conf-telemetry-provider) para tornar as métricas observáveis.
**Quais métricas são emitidas?**
| Nome da métrica | Unidades | Tipo | Atributos | Description |
| --- | --- | --- | --- | --- |
| smithy.client.call.duration | s | Histograma | rpc.service, rpc.method | Duração geral da chamada (incluindo novas tentativas) |
| smithy.client.call.attempts | \$1attempt\$1 | MonotonicCounter | rpc.service, rpc.method | O número de tentativas de uma operação individual. |
| smithy.client.call.errors | \$1error\$1 | MonotonicCounter | rpc.service, rpc.method, exception.type | O número de erros de uma operação. |
| smithy.client.call.tempt\$1duration | s | Histograma | rpc.service, rpc.method | O tempo necessário para se conectar ao serviço, enviar a solicitação e recuperar o código de status HTTP e os cabeçalhos (incluindo o tempo de espera para envio). |
| smithy.client.call.resolve\$1endpoint\$1duration | s | Histograma | rpc.service, rpc.method | O tempo necessário para resolver um endpoint (resolvedor de endpoint, não DNS) para a solicitação. |
| smithy.client.call.serialization\$1duration | s | Histograma | rpc.service, rpc.method | O tempo necessário para serializar o corpo da mensagem. |
| smithy.client.call.duração\$1desserialização | s | Histograma | rpc.service, rpc.method | O tempo necessário para desserializar o corpo da mensagem. |
| smithy.client.call.auth.signing\$1duration | s | Histograma | rpc.service, rpc.method, auth.scheme\$1id | O tempo necessário para assinar uma solicitação |
| smithy.client.call.auth.resolve\$1identity\$1duration | s | Histograma | rpc.service, rpc.method, auth.scheme\$1id | O tempo necessário para adquirir uma identidade (como AWS credenciais ou um token de portador) de um provedor de identidade |
| smithy.client.http.connections.acquire\$1duration | s | Histograma | | O tempo necessário para que uma solicitação adquira uma conexão |
| smithy.client.http.connections.limit | \$1conexão\$1 | [Assíncrono] UpDownCounter | | O máximo de conexões abertas allowed/configured para o cliente HTTP |
| smithy.client.http.connections.usage | \$1conexão\$1 | [Assíncrono] UpDownCounter | estado: ocioso \$1 adquirido | Estado atual do pool de conexões |
| smithy.client.http.connections.uptime | s | Histograma | | A quantidade de tempo em que uma conexão foi aberta |
| smithy.client.http.requests.usage | \$1solicitação\$1 | [Assíncrono] UpDownCounter | estado: em fila \$1 em voo | O estado atual da simultaneidade de solicitações do cliente HTTP |
| smithy.client.http.requests.queued\$1duration | s | Histograma | | A quantidade de tempo que uma solicitação passou na fila e esperando para ser executada pelo cliente HTTP |
| smithy.client.http.bytes\$1sent | Por | MonotonicCounter | server.address | O número total de bytes enviados pelo cliente HTTP |
| smithy.client.http.bytes\$1received | Por | MonotonicCounter | server.address | O número total de bytes recebidos pelo cliente HTTP |
Veja a seguir as descrições das colunas.
+ **Nome da métrica**: o nome da métrica emitida.
+ **Unidades**: a unidade de medida da métrica. As unidades são fornecidas na notação [UCUM](https://unitsofmeasure.org/ucum) com distinção entre maiúsculas e minúsculas (“c/s”).
+ **Tipo**: o tipo de instrumento usado para capturar a métrica.
+ **Descrição**: descrição do que a métrica está medindo.
+ **Atributos**: o conjunto de atributos (dimensões) emitidos com a métrica.
# Registro em log
O AWS SDK para Kotlin configura um registrador compatível com [SLF4J](https://www.slf4j.org/manual.html) como o padrão do provedor `LoggerProvider` de telemetria. Com SLF4 J, que é uma camada de abstração, você pode usar qualquer um dos vários sistemas de registro em tempo de execução. [Os sistemas de registro suportados incluem [Java Logging APIs](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/), [Log4j 2](https://logging.apache.org/log4j/2.x/) e Logback.](https://logback.qos.ch/)
**Atenção**
Recomendamos que você use o registro de conexões somente para fins de depuração. (O registro de cabos é discutido abaixo.) Desative-o em seus ambientes de produção porque ele pode registrar dados confidenciais, como endereços de e-mail, tokens de segurança, chaves de API, senhas e AWS Secrets Manager segredos. O registro de conexões registra a solicitação ou resposta completa sem criptografia, mesmo para uma chamada HTTPS.
Para solicitações ou respostas grandes (como o upload de um arquivo para o Amazon S3), o registro detalhado de conexões também pode afetar significativamente o desempenho do seu aplicativo.
## Exemplo de configuração de registro do Log4j 2
Embora qualquer biblioteca `SLF4J` de registros compatível possa ser usada, este exemplo permite a saída de log do SDK em programas JVM usando o Log4j 2:
**Dependências do Gradle**
(Você pode navegar até o *X.Y.Z* link para ver a versão mais recente disponível.)
```
implementation("org.apache.logging.log4j:log4j-slf4j2-impl:[https://search.maven.org/#search|gav|1|g:org.apache.logging.log4j%20AND%20a:log4j-slf4j2-impl](https://search.maven.org/#search|gav|1|g:org.apache.logging.log4j%20AND%20a:log4j-slf4j2-impl)")
```
**Arquivo de configuração do Log4j 2**
Crie um arquivo nomeado `log4j2.xml` em seu `resources` diretório (por exemplo,`/src/main/resources`). Adicione a seguinte configuração XML ao arquivo:
```
```
Essa configuração inclui o `%X` especificador no `pattern` atributo que ativa o registro do MDC (contexto de diagnóstico mapeado).
O SDK adiciona os seguintes elementos do MDC para cada operação.
**rpc**
O nome da RPC invocada, por exemplo. `S3.GetObject`
**sdkInvocationId**
Uma ID exclusiva atribuída pelo cliente do serviço para a operação. O ID correlaciona todos os eventos de registro relacionados à invocação de uma única operação.
## Especifique o modo de registro para mensagens em nível de fio
Por padrão, o AWS SDK para Kotlin não registra mensagens em nível de fio porque elas podem conter dados confidenciais de solicitações e respostas da API. No entanto, às vezes você precisa desse nível de detalhe para fins de depuração.
Com o Kotlin SDK, você pode definir um modo de log no código ou usar as configurações do ambiente para habilitar mensagens de depuração para o seguinte:
+ Solicitações HTTP
+ Respostas HTTP
O modo de log é apoiado por um campo de bits em que cada bit é um sinalizador (modo) e os valores são aditivos. Você pode combinar um modo de solicitação e um modo de resposta.
### Definir o modo de registro no código
Para optar pelo registro adicional, defina a `logMode` propriedade ao criar um cliente de serviço.
O exemplo a seguir mostra como habilitar o registro de solicitações (com o corpo) e a resposta (sem o corpo).
```
import aws.smithy.kotlin.runtime.client.LogMode
// ...
val client = DynamoDbClient {
// ...
logMode = LogMode.LogRequestWithBody + LogMode.LogResponse
}
```
Um valor de modo de log definido durante a construção do cliente de serviço substitui qualquer valor de modo de log definido do ambiente.
### Defina o modo de registro a partir do ambiente
Para definir um modo de log globalmente para todos os clientes de serviço não configurados explicitamente no código, use um dos seguintes:
+ Propriedade do sistema JVM: `sdk.logMode`
+ Variável de ambiente: `SDK_LOG_MODE`
Os seguintes valores que não diferenciam maiúsculas de minúsculas estão disponíveis:
+ `LogRequest`
+ `LogRequestWithBody`
+ `LogResponse`
+ `LogResponseWithBody`
Para criar um modo de log combinado usando as configurações do ambiente, você separa os valores com um símbolo pipe (`|`).
Por exemplo, os exemplos a seguir definem o mesmo modo de log do exemplo anterior.
```
# Environment variable.
export SDK_LOG_MODE=LogRequestWithBody|LogResponse
```
```
# JVM system property.
java -Dsdk.logMode=LogRequestWithBody|LogResponse ...
```
**nota**
Você também deve configurar um registrador SLF4 J compatível e definir o nível de registro como DEBUG para habilitar o registro em nível de fio.
# Provedores de telemetria
Atualmente, o SDK oferece suporte a [OpenTelemetry](https://opentelemetry.io/)(OTel) como provedor. O SDK pode oferecer provedores de telemetria adicionais no futuro.
**Topics**
+ [Configurar o provedor OpenTelemetry de telemetria baseado](observability-telemetry-providers-otel.md)
# Configurar o provedor OpenTelemetry de telemetria baseado
O SDK para Kotlin fornece uma implementação da `TelemetryProvider` interface apoiada por. OpenTelemetry
## Pré-requisitos
Atualize as dependências do seu projeto para adicionar o OpenTelemetry provedor, conforme mostrado no seguinte trecho do Gradle. Você pode navegar até o *X.Y.Z* link para ver a versão mais recente disponível.
```
dependencies {
implementation(platform("aws.smithy.kotlin:bom:[https://github.com/smithy-lang/smithy-kotlin/releases/latest](https://github.com/smithy-lang/smithy-kotlin/releases/latest)"))
implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:[https://search.maven.org/#search|gav|1|g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-instrumentation-bom](https://search.maven.org/#search|gav|1|g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-instrumentation-bom)"))
implementation("aws.smithy.kotlin:telemetry-provider-otel")
// OPTIONAL: If you use log4j, the following entry enables the ability to export logs through OTel.
runtimeOnly("io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.17")
}
```
## Configurar o SDK
O código a seguir configura um cliente de serviço usando o provedor de OpenTelemetry telemetria.
```
import aws.sdk.kotlin.services.s3.S3Client
import aws.smithy.kotlin.runtime.telemetry.otel.OpenTelemetryProvider
import io.opentelemetry.api.GlobalOpenTelemetry
import kotlinx.coroutines.runBlocking
fun main() = runBlocking {
val otelProvider = OpenTelemetryProvider(GlobalOpenTelemetry.get())
S3Client.fromEnvironment().use { s3 ->
telemetryProvider = otelProvider
…
}
}
```
**nota**
Uma discussão sobre como configurar o OpenTelemetry SDK está fora do escopo deste guia. A [documentação OpenTelemetry Java](https://opentelemetry.io/docs/instrumentation/java/) contém informações de configuração sobre as várias abordagens: [manual](https://opentelemetry.io/docs/instrumentation/java/manual/), automaticamente por meio do [agente Java](https://opentelemetry.io/docs/instrumentation/java/automatic/) ou do [coletor](https://opentelemetry.io/docs/collector/) (opcional).
## Recursos
Os recursos a seguir estão disponíveis para ajudar você a começar OpenTelemetry.
+ [AWS Distro para OpenTelemetry - Página](https://aws-otel.github.io/docs/introduction) inicial da AWS OTe L Distro
+ [aws-otel-java-instrumentation](https://github.com/aws-observability/aws-otel-java-instrumentation)- AWS Distro para biblioteca de instrumentação OpenTelemetry Java
+ [aws-otel-lambda](https://github.com/aws-observability/aws-otel-lambda)- camadas OpenTelemetry Lambda AWS gerenciadas
+ [aws-otel-collector](https://github.com/aws-observability/aws-otel-collector)- AWS Distro para OpenTelemetry colecionador
+ [AWS Melhores práticas de observabilidade](https://aws-observability.github.io/observability-best-practices/) - Melhores práticas gerais para observabilidade específica para AWS
# Substituir a configuração do cliente de serviço
Depois que um [cliente de serviço é criado](creating-clients.md), o cliente de serviço usa uma configuração fixa para todas as operações. No entanto, às vezes você pode precisar substituir a configuração para uma ou mais operações específicas.
Cada cliente de serviço tem uma `withConfig` extensão para que você possa modificar uma cópia da configuração existente. A `withConfig` extensão retorna um novo cliente de serviço com uma configuração modificada. O cliente original existe de forma independente e usa sua configuração original.
O exemplo a seguir mostra a criação de uma `S3Client` instância que chama duas operações.
```
val s3 = S3Client.fromEnvironment {
logMode = LogMode.LogRequest
region = "us-west-2"
// ...other configuration settings...
}
s3.listBuckets { ... }
s3.listObjectsV2 { ... }
```
O trecho a seguir mostra como substituir a configuração de uma única operação. `listObjectV2`
```
s3.withConfig {
region = "eu-central-1"
}.use { overriddenS3 ->
overriddenS3.listObjectsV2 { ... }
}
```
As chamadas de operação do `s3` cliente usam a configuração original que foi especificada quando o cliente foi criado. Sua configuração inclui o [registro de solicitações](logging.md#sdk-log-mode) e `us-west-2 region` para a região.
A `listObjectsV2` invocação no `overriddenS3` cliente usa as mesmas configurações do `s3` cliente original, exceto para a Região, que agora é. `eu-central-1`
## Ciclo de vida de um cliente sobrecarregado
No exemplo anterior, o `s3` cliente e o `overriddenS3` cliente são independentes um do outro. As operações podem ser invocadas em qualquer cliente enquanto permanecerem abertas. Cada um usa uma configuração separada, mas pode compartilhar recursos subjacentes (como um mecanismo HTTP), a menos que eles também sejam substituídos.
Você fecha um cliente com uma configuração substituída e o cliente original separadamente. Você pode fechar um cliente com a configuração substituída antes ou depois de fechar o cliente original. A menos que você precise usar um cliente com configuração substituída por muito tempo, recomendamos que você envolva seu ciclo de vida com o método. `use` O `use` método garante que o cliente seja fechado caso ocorram exceções.
## Recursos compartilhados entre clientes
Quando você cria um cliente de serviço usando`withConfig`, ele pode compartilhar recursos com o cliente original. Por outro lado, quando você cria um cliente usando [FromEnvironment ou o](creating-clients.md#loading-from-the-environment) [configura explicitamente, o cliente usa recursos](creating-clients.md#programmatic-config) independentes. Recursos como mecanismos HTTP e provedores de credenciais são compartilhados, a menos que sejam substituídos no bloco. `withConfig`
Como o ciclo de vida de cada cliente é independente, os recursos compartilhados permanecem abertos e utilizáveis até que o último cliente seja fechado. Portanto, é importante fechar clientes de serviços substituídos quando não precisar mais deles. Isso evita que recursos compartilhados permaneçam abertos e consumam recursos do sistema, como memória, conexão e ciclos de CPU.
O exemplo a seguir mostra recursos compartilhados e independentes.
Os `overriddenS3` clientes `s3` e compartilham a mesma instância do provedor de credenciais, incluindo sua configuração de cache. Chamadas feitas por meio de credenciais de `overriddenS3` reutilização se o valor em cache ainda estiver atualizado a partir das chamadas feitas pelo cliente. `s3`
O mecanismo HTTP não é compartilhado entre os dois clientes. Cada cliente tem um mecanismo HTTP independente porque ele foi substituído na `withConfig` chamada.
```
val s3 = S3Client.fromEnvironment {
region = "us-west-2"
credentialsProvider = CachedCredentialsProvider(CredentialsProviderChain(...))
httpClientEngine = OkHttpEngine { ... }
}
s3.listBuckets { ... }
s3.withConfig {
httpClientEngine = CrtHttpEngine { ... }
}.use { overriddenS3 ->
overriddenS3.listObjectsV2 { ... }
}
```