Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Konfigurasikan SDK
Di AWS SDK untuk Go V2, Anda dapat mengonfigurasi pengaturan umum untuk klien layanan, seperti logger, level log, dan konfigurasi coba lagi. Sebagian besar pengaturan bersifat opsional. Namun, untuk setiap klien layanan, Anda harus menentukan AWS Wilayah dan kredensyal Anda. SDK menggunakan nilai ini untuk mengirim permintaan ke Wilayah yang benar dan menandatangani permintaan dengan kredensyal yang benar. Anda dapat menentukan nilai-nilai ini secara terprogram dalam kode atau melalui lingkungan eksekusi.
## Memuat File Konfigurasi AWS Bersama
Ada sejumlah cara untuk menginisialisasi klien API layanan, tetapi berikut ini adalah pola paling umum yang direkomendasikan kepada pengguna.
Untuk mengonfigurasi SDK agar menggunakan file konfigurasi AWS bersama, gunakan kode berikut:
```
import (
"context"
"log"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Fatalf("failed to load configuration, %v", err)
}
```
`config.LoadDefaultConfig(context.TODO())`akan membangun [AWS.config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) menggunakan sumber konfigurasi bersama. AWS Ini termasuk mengonfigurasi penyedia kredensi, mengonfigurasi AWS Wilayah, dan memuat konfigurasi khusus layanan. Klien layanan dapat dibangun menggunakan beban`aws.Config`, memberikan pola yang konsisten untuk membangun klien.
Untuk informasi selengkapnya tentang file konfigurasi AWS bersama, lihat [Konfigurasi](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) di Panduan Referensi Alat AWS SDKs dan Konfigurasi.
## Menentukan Wilayah AWS
Ketika Anda menentukan Wilayah, Anda menentukan tempat untuk mengirim permintaan, seperti `us-west-2` atau`us-east-2`. Untuk daftar Wilayah untuk setiap layanan, lihat [Titik akhir layanan dan kuota](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) di. Referensi Umum Amazon Web
SDK tidak memiliki Region default. Untuk menentukan Wilayah:
+ Atur variabel `AWS_REGION` lingkungan ke Region default.
+ [Setel wilayah secara eksplisit menggunakan konfigurasi. WithRegion](https://github.com/aws/aws-sdk-go-v2/blob/config/v0.2.2/config/provider.go#L127)sebagai argumen `config.LoadDefaultConfig` saat memuat konfigurasi.
TINJAUAN: Jika Anda menyetel Wilayah menggunakan semua teknik ini, SDK akan menggunakan Wilayah yang Anda tentukan secara eksplisit.
### Konfigurasikan Wilayah dengan Variabel Lingkungan
#### Linux, macOS, atau Unix
```
export AWS_REGION=us-west-2
```
#### Windows
```
set AWS_REGION=us-west-2
```
### Tentukan Wilayah Secara Terprogram
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
```
## Menentukan Kredensial
AWS SDK untuk Go Memerlukan kredensyal (kunci akses dan kunci akses rahasia) untuk menandatangani permintaan. AWS Anda dapat menentukan kredensyal Anda di beberapa lokasi, tergantung pada kasus penggunaan khusus Anda. Untuk informasi tentang mendapatkan kredensional, lihat. [Memulai dengan AWS SDK untuk Go](getting-started.md)
Saat Anda menginisialisasi `aws.Config` instance menggunakan`config.LoadDefaultConfig`, SDK menggunakan rantai kredensyal defaultnya untuk menemukan kredensyal. AWS Rantai kredensi default ini mencari kredensi dalam urutan sebagai berikut:
1. Variabel lingkungan.
1. Kredensial Statis (`AWS_ACCESS_KEY_ID`,,`AWS_SECRET_ACCESS_KEY`) `AWS_SESSION_TOKEN`
1. Token Identitas Web (`AWS_WEB_IDENTITY_TOKEN_FILE`)
1. File konfigurasi bersama.
1. SDK default ke `credentials` file di bawah `.aws` folder yang ditempatkan di folder rumah di komputer Anda.
1. SDK default ke `config` file di bawah `.aws` folder yang ditempatkan di folder rumah di komputer Anda.
1. Jika aplikasi Anda menggunakan definisi tugas Amazon ECS atau operasi RunTask API, peran IAM untuk tugas.
1. Jika aplikasi Anda berjalan pada instans Amazon EC2, peran IAM untuk Amazon EC2.
SDK mendeteksi dan menggunakan penyedia bawaan secara otomatis, tanpa memerlukan konfigurasi manual. Misalnya, jika Anda menggunakan peran IAM untuk instans Amazon EC2, aplikasi Anda secara otomatis menggunakan kredensyal instans. Anda tidak perlu mengonfigurasi kredensi secara manual di aplikasi Anda.
Sebagai praktik terbaik, AWS merekomendasikan agar Anda menentukan kredensyal dalam urutan berikut:
1. Gunakan peran IAM untuk tugas jika aplikasi Anda menggunakan definisi tugas Amazon ECS atau operasi RunTask API.
1. Gunakan peran IAM untuk Amazon EC2 (jika aplikasi Anda berjalan pada instans Amazon EC2).
Peran IAM menyediakan aplikasi pada kredensyal keamanan sementara instance untuk melakukan panggilan. AWS Peran IAM menyediakan cara mudah untuk mendistribusikan dan mengelola kredensyal di beberapa instans Amazon EC2.
1. Gunakan kredensi bersama atau file konfigurasi.
Kredensyal dan file konfigurasi dibagikan di file lain dan file. AWS SDKs AWS CLI Sebagai praktik keamanan terbaik, sebaiknya gunakan file kredensyal untuk menyetel nilai sensitif seperti kunci akses IDs dan kunci rahasia. Berikut adalah [persyaratan pemformatan](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) untuk masing-masing file ini.
1. Gunakan variabel lingkungan.
Menyetel variabel lingkungan berguna jika Anda melakukan pekerjaan pengembangan pada mesin selain instans Amazon EC2.
### Peran IAM untuk Tugas
Jika aplikasi Anda menggunakan definisi atau `RunTask` operasi tugas Amazon ECS, gunakan Peran [IAM untuk Tugas untuk menentukan peran](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) IAM yang dapat digunakan oleh kontainer dalam tugas.
### Peran IAM untuk Instans Amazon EC2
Jika Anda menjalankan aplikasi di instans Amazon EC2, gunakan [peran IAM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) instans untuk mendapatkan kredenal keamanan sementara untuk melakukan panggilan. AWS
Jika Anda telah mengonfigurasi instans Anda untuk menggunakan peran IAM, SDK akan menggunakan kredensyal ini untuk aplikasi Anda secara otomatis. Anda tidak perlu menentukan kredensi ini secara manual.
### Kredensi dan Konfigurasi Bersama
Kredensyal bersama dan file konfigurasi dapat digunakan untuk berbagi konfigurasi umum di antara AWS SDKs dan alat lainnya. Jika Anda menggunakan kredensi yang berbeda untuk alat atau aplikasi yang berbeda, Anda dapat menggunakan *profil* untuk mengonfigurasi beberapa kunci akses dalam file konfigurasi yang sama.
Anda dapat menyediakan beberapa lokasi file kredensyal atau konfigurasi menggunakan`config.LoadOptions`, secara default SDK memuat file yang disimpan di lokasi default yang disebutkan dalam file. [Menentukan Kredensial](#specifying-credentials)
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg , err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedCredentialsFiles(
[]string{"test/credentials", "data/credentials"},
),
config.WithSharedConfigFiles(
[]string{"test/config", "data/config"},
)
)
```
Saat bekerja dengan kredensyal bersama dan file konfigurasi, jika profil duplikat ditentukan, profil tersebut digabungkan untuk menyelesaikan profil. Dalam kasus konflik penggabungan,
1. Jika profil duplikat ditentukan dalam credentials/config file yang sama, properti profil yang ditentukan dalam profil terakhir diutamakan.
1. Jika profil duplikat ditentukan di beberapa file kredensional atau di beberapa file konfigurasi, properti profil diselesaikan sesuai urutan input file ke file. `config.LoadOptions` Properti profil dalam file terakhir diutamakan.
1. Jika profil ada di file kredensyal dan file konfigurasi, properti file kredensyal diutamakan.
Jika perlu, Anda dapat `LogConfigurationWarnings` mengaktifkan `config.LoadOptions` dan mencatat langkah-langkah resolusi profil.
#### Membuat File Kredensial
Jika Anda tidak memiliki file kredensyal bersama (`.aws/credentials`), Anda dapat menggunakan editor teks apa pun untuk membuatnya di direktori home Anda. Tambahkan konten berikut ke file kredensyal Anda, ganti ** dan ** dengan kredensyal Anda.
```
[default]
aws_access_key_id =
aws_secret_access_key =
```
`[default]`Judul mendefinisikan kredensyal untuk profil default, yang akan digunakan SDK kecuali Anda mengonfigurasinya untuk menggunakan profil lain.
Anda juga dapat menggunakan kredensyal keamanan sementara dengan menambahkan token sesi ke profil Anda, seperti yang ditunjukkan pada contoh berikut:
```
[temp]
aws_access_key_id =
aws_secret_access_key =
aws_session_token =
```
Nama bagian untuk profil non-default dalam file kredensyal tidak boleh dimulai dengan kata. `profile` Anda dapat membaca lebih lanjut di [AWS SDKs dan Panduan Referensi Alat](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds).
#### Membuat File Config
Jika Anda tidak memiliki file kredensyal bersama (`.aws/config`), Anda dapat menggunakan editor teks apa pun untuk membuatnya di direktori home Anda. Tambahkan konten berikut ke file konfigurasi Anda, ganti ** dengan wilayah yang diinginkan.
```
[default]
region =
```
`[default]`Judul mendefinisikan konfigurasi untuk profil default, yang akan digunakan SDK kecuali Anda mengonfigurasinya untuk menggunakan profil lain.
Anda dapat menggunakan profil bernama seperti yang ditunjukkan pada contoh berikut:
```
[profile named-profile]
region =
```
Nama bagian untuk profil non-default dalam file konfigurasi harus selalu dimulai dengan kata`profile`, diikuti dengan nama profil yang dimaksud. Anda dapat membaca lebih lanjut di [Panduan Referensi AWS SDKs dan Alat](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-config).
#### Menentukan Profil
Anda dapat menyertakan beberapa kunci akses dalam file konfigurasi yang sama dengan mengaitkan setiap set kunci akses dengan profil. Misalnya, dalam file kredensial Anda, Anda dapat mendeklarasikan beberapa profil, sebagai berikut.
```
[default]
aws_access_key_id =
aws_secret_access_key =
[test-account]
aws_access_key_id =
aws_secret_access_key =
[prod-account]
; work profile
aws_access_key_id =
aws_secret_access_key =
```
Secara default, SDK memeriksa variabel `AWS_PROFILE` lingkungan untuk menentukan profil mana yang akan digunakan. Jika tidak ada `AWS_PROFILE` variabel yang disetel, SDK menggunakan `default` profil.
Terkadang, Anda mungkin ingin menggunakan profil yang berbeda dengan aplikasi Anda. Misalnya, Anda ingin menggunakan `test-account` kredensyal dengan aplikasi Anda`myapp`. Anda dapat menggunakan profil ini dengan menggunakan perintah berikut:
```
$ AWS_PROFILE=test-account myapp
```
Anda juga dapat menggunakan instruksikan SDK untuk memilih profil dengan menelepon `os.Setenv("AWS_PROFILE", "test-account")` sebelum memanggil`config.LoadDefaultConfig`, atau dengan meneruskan profil eksplisit sebagai argumen seperti yang ditunjukkan pada contoh berikut:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedConfigProfile("test-account"))
```
**catatan**
Jika Anda menentukan kredensyal dalam variabel lingkungan, SDK akan selalu menggunakan kredensyal tersebut, apa pun profil yang Anda tentukan.
### Variabel lingkungan
Secara default, SDK mendeteksi AWS kredensyal yang disetel di lingkungan Anda dan menggunakannya untuk menandatangani permintaan. AWS Dengan begitu Anda tidak perlu mengelola kredensi di aplikasi Anda.
SDK mencari kredensional dalam variabel lingkungan berikut:
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_SESSION_TOKEN` (opsional)
Contoh berikut menunjukkan bagaimana Anda mengkonfigurasi variabel lingkungan.
#### Linux, OS X, atau Unix
```
$ export AWS_ACCESS_KEY_ID=YOUR_AKID
$ export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
$ export AWS_SESSION_TOKEN=TOKEN
```
#### Windows
```
> set AWS_ACCESS_KEY_ID=YOUR_AKID
> set AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
> set AWS_SESSION_TOKEN=TOKEN
```
### Tentukan Kredensial Secara Terprogram
`config.LoadDefaultConfig`memungkinkan Anda memberikan [aws eksplisit. CredentialProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)saat memuat sumber konfigurasi bersama. [Untuk meneruskan penyedia kredensyal eksplisit saat memuat konfigurasi bersama gunakan konfigurasi. WithCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithCredentialsProvider). Misalnya, jika `customProvider` mereferensikan instance `aws.CredentialProvider` implementasi, itu dapat diteruskan selama pemuatan konfigurasi seperti:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(customProvider))
```
Jika Anda secara eksplisit memberikan kredensyal, seperti dalam contoh ini, SDK hanya menggunakan kredensyal tersebut.
**catatan**
Semua penyedia kredensi yang diteruskan atau dikembalikan oleh `LoadDefaultConfig` dibungkus secara [CredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsCache)otomatis. Ini memungkinkan rotasi caching dan kredenal yang aman secara konkurensi. Jika Anda secara eksplisit mengonfigurasi penyedia secara `aws.Config` langsung, Anda juga harus secara eksplisit membungkus penyedia dengan tipe ini menggunakan. [NewCredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NewCredentialsCache)
#### Kredensial Statis
[Anda dapat membuat kode keras kredensional dalam aplikasi Anda dengan menggunakan kredensialnya. NewStaticCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials#NewStaticCredentialsProvider)penyedia kredensi untuk secara eksplisit mengatur kunci akses yang akan digunakan. Contoh:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("AKID", "SECRET_KEY", "TOKEN")),
)
```
**Awas**
Jangan menanamkan kredensi di dalam aplikasi. Gunakan metode ini hanya untuk tujuan pengujian.
#### Kredensial Masuk Tunggal
SDK menyediakan penyedia kredensyal untuk mengambil kredensyal sementara AWS menggunakan. AWS IAM Identity Center Dengan menggunakan AWS CLI, Anda mengautentikasi dengan portal AWS akses dan mengotorisasi akses ke kredensyal sementara AWS . Anda kemudian mengonfigurasi aplikasi Anda untuk memuat profil single sign-on (SSO), dan SDK menggunakan kredenal SSO Anda untuk mengambil kredenal sementara AWS yang akan diperpanjang secara otomatis jika kedaluwarsa. Jika kredensyal SSO Anda kedaluwarsa, Anda harus memperbaruinya secara eksplisit dengan masuk ke akun Pusat Identitas IAM Anda lagi menggunakan. AWS CLI
Misalnya, Anda dapat membuat profil,`dev-profile`, mengautentikasi dan mengotorisasi profil tersebut menggunakan AWS CLI, dan mengkonfigurasi aplikasi Anda seperti yang ditunjukkan di bawah ini.
1. Pertama buat `profile` dan `sso-session`
```
[profile dev-profile]
sso_session = dev-session
sso_account_id = 012345678901
sso_role_name = Developer
region = us-east-1
[sso-session dev-session]
sso_region = us-west-2
sso_start_url = https://company-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access
```
1. Login menggunakan AWS CLI untuk mengautentikasi dan mengotorisasi profil SSO.
```
$ aws --profile dev-profile sso login
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.us-west-2.amazonaws.com/
Then enter the code:
ABCD-EFGH
Successully logged into Start URL: https://company-sso-portal.awsapps.com/start
```
1. Selanjutnya konfigurasikan aplikasi Anda untuk menggunakan profil SSO.
```
import "github.com/aws/aws-sdk-go-v2/config"
// ...
cfg, err := config.LoadDefaultConfig(
context.Background(),
config.WithSharedConfigProfile("dev-profile"),
)
if err != nil {
return err
}
```
Untuk informasi selengkapnya tentang mengonfigurasi profil SSO dan mengautentikasi menggunakan AWS CLI lihat [Mengonfigurasi yang AWS CLI akan digunakan AWS IAM Identity Center dalam Panduan Pengguna](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html). AWS CLI [Untuk informasi selengkapnya tentang pembuatan penyedia kredensi SSO secara terprogram, lihat dokumentasi referensi API ssocreds.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ssocreds)
#### Kredensi login
Anda dapat menggunakan kredenal masuk Konsol AWS Manajemen yang sudah ada untuk akses terprogram ke layanan. AWS Setelah alur otentikasi berbasis browser, buat AWS kredenal sementara yang berfungsi di seluruh alat pengembangan lokal seperti CLI, dan. AWS Alat AWS untuk PowerShell AWS SDKs Fitur ini menyederhanakan proses konfigurasi dan pengelolaan kredensional AWS CLI, terutama jika Anda lebih memilih otentikasi interaktif daripada mengelola kunci akses jangka panjang.
1. Memulai alur login menggunakan AWS CLI, dan ikuti petunjuk browser. Dalam contoh ini, kami menyimpan sesi login ke profil baru**dev-profile**, tetapi ini opsional.
```
$ aws --profile dev-profile login
```
1. (Opsional) Periksa file konfigurasi AWS bersama Anda untuk memverifikasi bahwa sesi telah dibuat.
```
[profile dev-profile]
login_session = arn:aws:sts::account id>:role
```
1. Selanjutnya konfigurasikan aplikasi Anda untuk menggunakan profil login.
```
import "github.com/aws/aws-sdk-go-v2/config"
// ...
cfg, err := config.LoadDefaultConfig(
context.Background(),
// only necessary if login session is saved to a non-default profile
config.WithSharedConfigProfile("dev-profile"),
)
if err != nil {
return err
}
```
Untuk informasi selengkapnya tentang mengonfigurasi profil login dan mengautentikasi menggunakan AWS CLI, lihat [Login untuk pengembangan AWS lokal](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) menggunakan kredenal konsol.
#### Penyedia Kredensial Lainnya
[SDK menyediakan metode lain untuk mengambil kredensyal dalam modul kredensyal.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials) Misalnya, Anda dapat mengambil kredensyal keamanan sementara dari AWS Security Token Service atau kredensyal dari penyimpanan terenkripsi.
**Penyedia Kredensi yang Tersedia**:
+ [ec2rolecreds - Ambil Kredensyal](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds) dari Peran Instans Amazon EC2 melalui Amazon EC2 IMDS.
+ [endpointcreds - Ambil Kredensial](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/endpointcreds) dari titik akhir HTTP arbitrer.
+ [processcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/processcreds) — Ambil Credentials dari proses eksternal yang akan dipanggil oleh shell lingkungan host.
+ [stscreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/stscreds) - Ambil Kredensial dari AWS STS
# Konfigurasikan Otentikasi
AWS SDK untuk Go Ini menyediakan kemampuan untuk mengkonfigurasi layanan perilaku otentikasi. Dalam kebanyakan kasus, konfigurasi default sudah cukup, tetapi mengonfigurasi otentikasi kustom memungkinkan perilaku tambahan seperti bekerja dengan fitur layanan pra-rilis.
## Definisi
Bagian ini memberikan deskripsi tingkat tinggi dari komponen otentikasi di. AWS SDK untuk Go
### AuthScheme
An [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme)adalah antarmuka yang mendefinisikan alur kerja di mana SDK mengambil identitas pemanggil dan melampirkannya ke permintaan operasi.
Skema autentikasi menggunakan komponen-komponen berikut, dijelaskan secara rinci lebih lanjut di bawah ini:
+ ID unik yang mengidentifikasi skema
+ Penyelesai identitas, yang mengembalikan identitas pemanggil yang digunakan dalam proses penandatanganan (misalnya kredensyal Anda) AWS
+ Penandatangan, yang melakukan injeksi identitas pemanggil yang sebenarnya ke dalam permintaan transport operasi (misalnya header `Authorization` HTTP)
Setiap opsi klien layanan menyertakan `AuthSchemes` bidang, yang secara default diisi dengan daftar skema autentikasi yang didukung oleh layanan tersebut.
### AuthSchemeResolver
Setiap opsi klien layanan mencakup `AuthSchemeResolver` bidang. Antarmuka ini, didefinisikan per layanan, adalah API yang dipanggil oleh SDK untuk menentukan opsi otentikasi yang mungkin untuk setiap operasi.
**penting**
Penyelesai skema autentikasi TIDAK menentukan skema autentikasi apa yang digunakan. Ini mengembalikan daftar skema yang *dapat* digunakan (“opsi”), skema akhir dipilih melalui algoritma tetap yang dijelaskan [di sini](#auth-scheme-resolution-workflow).
### Opsi
Dikembalikan dari panggilan ke`ResolverAuthSchemes`, [Option mewakili opsi](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) otentikasi yang mungkin.
Opsi terdiri dari tiga set informasi:
+ ID yang mewakili skema yang mungkin
+ Satu set properti buram yang akan diberikan kepada penyelesai identitas skema
+ Satu set properti buram yang akan diberikan kepada penandatangan skema
#### Catatan tentang properti
Untuk 99% kasus penggunaan, penelepon tidak perlu peduli dengan properti buram untuk resolusi dan penandatanganan identitas. SDK akan mengeluarkan properti yang diperlukan untuk setiap skema dan meneruskannya ke antarmuka yang diketik dengan kuat yang diekspos di SDK. [Misalnya, penyelesai autentikasi default untuk layanan menyandikan opsi SigV4 agar memiliki properti penandatangan untuk nama dan wilayah penandatanganan, yang nilainya diteruskan ke v4 yang dikonfigurasi klien. HTTPSigner](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option)implementasi ketika SigV4 dipilih.
### Identitas
[Identitas](https://pkg.go.dev/github.com/aws/smithy-go/auth#Identity) adalah representasi abstrak dari siapa pemanggil SDK.
Jenis identitas yang paling umum digunakan dalam SDK adalah seperangkat. `aws.Credentials` Untuk sebagian besar kasus penggunaan, penelepon tidak perlu menyibukkan diri `Identity` sebagai abstraksi dan dapat bekerja dengan tipe konkret secara langsung.
**catatan**
Untuk mempertahankan kompatibilitas mundur dan mencegah kebingungan API, tipe identitas AWS khusus SDK `aws.Credentials` tidak secara langsung memenuhi antarmuka. `Identity` Pemetaan ini ditangani secara internal.
### IdentityResolver
[IdentityResolver](https://pkg.go.dev/github.com/aws/smithy-go/auth#IdentityResolver)adalah antarmuka yang melaluinya sebuah `Identity` diambil.
[Versi konkret `IdentityResolver` ada di SDK dalam bentuk yang diketik dengan kuat (misalnya aws. CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)), SDK menangani pemetaan ini secara internal.
Penelepon hanya perlu mengimplementasikan `IdentityResolver` antarmuka secara langsung saat mendefinisikan skema autentikasi eksternal.
### Signer
[Penandatangan](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#Signer) adalah antarmuka di mana permintaan dilengkapi dengan pemanggil yang diambil. `Identity`
[Versi konkret yang `Signer` ada di SDK dalam bentuk yang diketik dengan kuat (misalnya v4. HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#HTTPSigner)), SDK menangani pemetaan ini secara internal.
Penelepon hanya perlu mengimplementasikan `Signer` antarmuka secara langsung saat mendefinisikan skema autentikasi eksternal.
### AuthResolverParameters
Setiap layanan mengambil satu set input tertentu yang diteruskan ke fungsi resolusinya, yang didefinisikan dalam setiap paket layanan sebagai`AuthResolverParameters`.
Parameter resolver dasar adalah sebagai berikut:
| name | jenis | deskripsi |
| --- | --- | --- |
| Operation | string | Nama operasi yang dipanggil. |
| Region | string | AWS Wilayah klien. Hanya hadir untuk layanan yang menggunakan SiGv4 [A]. |
Jika Anda menerapkan resolver Anda sendiri, Anda seharusnya tidak perlu membuat instance Anda sendiri dari parameternya. SDK akan mencari nilai per permintaan ini dan meneruskannya ke implementasi Anda.
## Alur kerja resolusi skema autentikasi
Saat Anda memanggil operasi AWS layanan melalui SDK, urutan tindakan berikut akan terjadi setelah permintaan diserialisasi:
1. SDK memanggil `AuthSchemeResolver.ResolveAuthSchemes()` API klien, mencari parameter input seperlunya, untuk mendapatkan daftar [Opsi](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) yang mungkin untuk operasi.
1. SDK mengulangi daftar itu dan memilih skema pertama yang memenuhi kondisi berikut.
+ Skema dengan ID yang cocok hadir dalam `AuthSchemes` daftar klien sendiri
+ Penyelesai identitas skema ada (tidak-`nil`) pada Opsi klien (diperiksa melalui `GetIdentityResolver` metode skema, pemetaan ke jenis penyelesai identitas konkret yang dijelaskan di atas ditangani secara internal) (1)
1. Dengan asumsi skema yang layak dipilih, SDK memanggil `GetIdentityResolver()` API-nya untuk mengambil identitas pemanggil. Misalnya, skema autentikasi SiGv4 bawaan akan dipetakan ke penyedia klien secara internal. `Credentials`
1. SDK memanggil penyelesai identitas `GetIdentity()` (misalnya `aws.CredentialProvider.Retrieve()` untuk SigV4).
1. SDK memanggil penyelesai titik akhir `ResolveEndpoint()` untuk menemukan titik akhir permintaan. Titik akhir dapat mencakup metadata tambahan yang memengaruhi proses penandatanganan (misalnya nama penandatanganan unik untuk Objek Lambda S3).
1. SDK memanggil `Signer()` API skema autentikasi untuk mengambil penandatangannya, dan menggunakan `SignRequest()` API-nya untuk menandatangani permintaan dengan identitas pemanggil yang diambil sebelumnya.
(1) Jika SDK menemukan opsi anonim (ID`smithy.api#noAuth`) dalam daftar, itu dipilih secara otomatis, karena tidak ada penyelesai identitas yang sesuai.
## S yang didukung secara asli `AuthScheme`
Skema autentikasi berikut didukung secara native oleh. AWS SDK untuk Go
| Nama | ID Skema | Penyelesai identitas | Signer | Catatan |
| --- | --- | --- | --- | --- |
| [SiGv4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) | aws.auth\$1sigv4 | [aws. CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Credentials) | [v4. HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#Signer) | Default saat ini untuk sebagian besar operasi AWS layanan. |
| Sigv4a | aws.auth\$1sigv4a | aws. CredentialsProvider | T/A | Penggunaan Sigv4a terbatas saat ini, implementasi penandatangan bersifat internal. Lihat [pengumuman](https://github.com/aws/aws-sdk-go-v2/discussions/2812) ini untuk modul keikutsertaan baru aws-http-authyang memperlihatkan tujuan umum APIs untuk menandatangani permintaan HTTP. |
| SIGV4Express | com.amazonaws.s3\$1sigv4express | [s3. ExpressCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#ExpressCredentialsProvider) | v4. HTTPSigner | Digunakan untuk [Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/). |
| Pembawa HTTP | smithy.api\$1httpBearerAuth | [pembawa smithybearer. TokenProvider](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#TokenProvider) | [Smithybearer.Signer](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#Signer) | Digunakan oleh [codecatalyst](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/codecatalyst). |
| Anonim | smithy.api\$1noAuth | tidak berlaku | T/A | Tidak ada otentikasi - tidak diperlukan identitas, dan permintaan tidak ditandatangani atau diautentikasi. |
### Konfigurasi identitas
Dalam AWS SDK untuk Go, komponen identitas skema autentikasi dikonfigurasi dalam klien SDK. `Options` SDK akan secara otomatis mengambil dan menggunakan nilai untuk komponen ini untuk skema yang dipilihnya saat operasi dipanggil.
**catatan**
Untuk alasan kompatibilitas mundur, SDK secara implisit mengizinkan penggunaan skema autentikasi anonim jika tidak ada penyelesai identitas yang dikonfigurasi. Ini dapat dicapai secara manual dengan menyetel semua penyelesai identitas pada klien `Options` ke `nil` (penyelesai identitas sigv4 juga dapat diatur ke). `aws.AnonymousCredentials{}`
### Konfigurasi penandatangan
Di AWS SDK untuk Go, komponen penandatangan skema autentikasi dikonfigurasi di klien SDK. `Options` SDK akan secara otomatis mengambil dan menggunakan nilai untuk komponen ini untuk skema yang dipilihnya saat operasi dipanggil. Tidak diperlukan konfigurasi tambahan.
#### Skema autentikasi khusus
Untuk menentukan skema autentikasi khusus dan mengonfigurasinya untuk digunakan, pemanggil harus melakukan hal berikut:
1. Mendefinisikan [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme)implementasi
1. Daftarkan skema pada daftar klien SDK `AuthSchemes`
1. Instrumen klien SDK `AuthSchemeResolver` untuk mengembalikan autentikasi `Option` dengan ID skema jika berlaku
**Awas**
Layanan berikut memiliki perilaku otentikasi yang unik atau disesuaikan. Kami menyarankan Anda mendelegasikan ke implementasi default dan membungkusnya jika Anda memerlukan perilaku otentikasi khusus:
| Layanan | Catatan |
| --- | --- |
| S3 | Penggunaan bersyarat Sigv4a dan Sigv4Express tergantung pada input operasi. |
| EventBridge | Penggunaan bersyarat Sigv4a tergantung pada input operasi. |
| Cognito | Operasi tertentu hanya bersifat anonim. |
| SSO | Operasi tertentu hanya bersifat anonim. |
| STS | Operasi tertentu hanya bersifat anonim. |
# Konfigurasikan Titik Akhir Klien
**Awas**
Resolusi titik akhir adalah topik SDK lanjutan. Dengan mengubah pengaturan ini, Anda berisiko melanggar kode Anda. Pengaturan default harus berlaku untuk sebagian besar pengguna di lingkungan produksi.
AWS SDK untuk Go Ini menyediakan kemampuan untuk mengonfigurasi titik akhir kustom yang akan digunakan untuk layanan. Dalam kebanyakan kasus, konfigurasi default sudah cukup. Mengonfigurasi titik akhir kustom memungkinkan perilaku tambahan, seperti bekerja dengan versi layanan pra-rilis.
## Kustomisasi
Ada dua “versi” konfigurasi resolusi titik akhir dalam SDK.
+ v2, dirilis pada Q3 tahun 2023, dikonfigurasi melalui:
+ `EndpointResolverV2`
+ `BaseEndpoint`
+ v1, dirilis bersama SDK, dikonfigurasi melalui:
+ `EndpointResolver`
Kami menyarankan pengguna resolusi titik akhir v1 bermigrasi ke v2 untuk mendapatkan akses ke fitur layanan terkait titik akhir yang lebih baru.
## V2: `EndpointResolverV2` \$1 `BaseEndpoint`
Dalam resolusi v2, `EndpointResolverV2` adalah mekanisme definitif di mana resolusi titik akhir terjadi. `ResolveEndpoint`Metode resolver dipanggil sebagai bagian dari alur kerja untuk setiap permintaan yang Anda buat di SDK. Nama host yang `Endpoint` dikembalikan oleh resolver digunakan **apa adanya** saat membuat permintaan (serializer operasi masih dapat ditambahkan ke jalur HTTP).
Resolution v2 menyertakan konfigurasi tingkat klien tambahan`BaseEndpoint`, yang digunakan untuk menentukan nama host “dasar” untuk instance layanan Anda. Nilai yang ditetapkan di sini tidak definitif-- itu akhirnya diteruskan sebagai parameter ke klien `EndpointResolverV2` ketika resolusi akhir terjadi (baca terus untuk informasi lebih lanjut tentang `EndpointResolverV2` parameter). Implementasi resolver kemudian memiliki kesempatan untuk memeriksa dan berpotensi memodifikasi nilai tersebut untuk menentukan titik akhir.
Misalnya, jika Anda melakukan `GetObject` permintaan S3 terhadap bucket tertentu dengan klien yang telah Anda tentukan`BaseEndpoint`, resolver default akan menyuntikkan bucket ke nama host jika kompatibel dengan virtual-host (dengan asumsi Anda belum menonaktifkan virtual-hosting di konfigurasi klien).
Dalam prakteknya, kemungkinan besar `BaseEndpoint` akan digunakan untuk mengarahkan klien Anda pada contoh pengembangan atau pratinjau layanan.
### Parameter `EndpointResolverV2`
Setiap layanan mengambil satu set input tertentu yang diteruskan ke fungsi resolusinya, yang didefinisikan dalam setiap paket layanan sebagai`EndpointParameters`.
Setiap layanan mencakup parameter dasar berikut, yang digunakan untuk memfasilitasi resolusi titik akhir umum dalam AWS:
| name | jenis | deskripsi |
| --- | --- | --- |
| Region | string | AWS Wilayah klien |
| Endpoint | string | Nilai yang ditetapkan untuk BaseEndpoint konfigurasi klien |
| UseFips | bool | Apakah titik akhir FIPS diaktifkan dalam konfigurasi klien |
| UseDualStack | bool | Apakah titik akhir tumpukan ganda diaktifkan dalam konfigurasi klien |
Layanan dapat menentukan parameter tambahan yang diperlukan untuk resolusi. Misalnya, S3 `EndpointParameters` menyertakan nama bucket, serta beberapa pengaturan fitur khusus S3 seperti apakah pengalamatan host virtual diaktifkan.
Jika Anda menerapkan sendiri`EndpointResolverV2`, Anda seharusnya tidak perlu membangun contoh Anda sendiri. `EndpointParameters` SDK akan mencari nilai per permintaan dan meneruskannya ke implementasi Anda.
### Catatan tentang Amazon S3
Amazon S3 adalah layanan yang kompleks dengan banyak fitur-fiturnya yang dimodelkan melalui penyesuaian titik akhir yang kompleks, seperti hosting virtual bucket, S3 MRAP, dan banyak lagi.
Karena itu, kami menyarankan Anda untuk tidak mengganti `EndpointResolverV2` implementasi di klien S3 Anda. Jika Anda perlu memperluas perilaku resolusinya, mungkin dengan mengirimkan permintaan ke tumpukan pengembangan lokal dengan pertimbangan titik akhir tambahan, kami sarankan untuk membungkus implementasi default sedemikian rupa sehingga mendelegasikan kembali ke default sebagai fallback (ditunjukkan dalam contoh di bawah).
### Contoh
#### dengan `BaseEndpoint`
Cuplikan kode berikut menunjukkan cara mengarahkan klien S3 Anda ke instance lokal layanan, yang dalam contoh ini di-host pada perangkat loopback di port 8080.
```
client := s3.NewFromConfig(cfg, func (o *svc.Options) {
o.BaseEndpoint = aws.String("https://localhost:8080/")
})
```
#### dengan `EndpointResolverV2`
Cuplikan kode berikut menunjukkan cara menyuntikkan perilaku khusus ke resolusi titik akhir S3 menggunakan. `EndpointResolverV2`
```
import (
"context"
"net/url"
"github.com/aws/aws-sdk-go-v2/service/s3"
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type resolverV2 struct {
// you could inject additional application context here as well
}
func (*resolverV2) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
if /* input params or caller context indicate we must route somewhere */ {
u, err := url.Parse("https://custom.service.endpoint/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{
URI: *u,
}, nil
}
// delegate back to the default v2 resolver otherwise
return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params)
}
func main() {
// load config...
client := s3.NewFromConfig(cfg, func (o *s3.Options) {
o.EndpointResolverV2 = &resolverV2{
// ...
}
})
}
```
#### Dengan keduanya
Program sampel berikut menunjukkan interaksi antara `BaseEndpoint` dan`EndpointResolverV2`. **Ini adalah kasus penggunaan lanjutan:**
```
import (
"context"
"fmt"
"log"
"net/url"
"github.com/aws/aws-sdk-go-v2"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type resolverV2 struct {}
func (*resolverV2) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
// s3.Options.BaseEndpoint is accessible here:
fmt.Printf("The endpoint provided in config is %s\n", *params.Endpoint)
// fallback to default
return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params)
}
func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if (err != nil) {
log.Fatal(err)
}
client := s3.NewFromConfig(cfg, func (o *s3.Options) {
o.BaseEndpoint = aws.String("https://endpoint.dev/")
o.EndpointResolverV2 = &resolverV2{}
})
// ignore the output, this is just for demonstration
client.ListBuckets(context.Background(), nil)
}
```
Saat dijalankan, program di atas menghasilkan yang berikut:
```
The endpoint provided in config is https://endpoint.dev/
```
## V1: `EndpointResolver`
**Awas**
Resolusi titik akhir v1 dipertahankan untuk kompatibilitas mundur dan diisolasi dari perilaku modern dalam resolusi titik akhir v2. Ini hanya akan digunakan jika `EndpointResolver` bidang diatur oleh penelepon.
Penggunaan v1 kemungkinan besar akan mencegah Anda mengakses fitur layanan terkait titik akhir yang diperkenalkan dengan atau setelah rilis resolusi v2. Lihat “Migrasi” untuk petunjuk tentang cara meningkatkan.
A [EndpointResolver](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolver)dapat dikonfigurasi untuk memberikan logika resolusi titik akhir kustom untuk klien layanan. Anda dapat menggunakan resolver endpoint khusus untuk mengganti logika resolusi titik akhir layanan untuk semua titik akhir, atau titik akhir regional tertentu saja. Penyelesai titik akhir khusus dapat memicu logika resolusi titik akhir layanan untuk mundur jika resolver khusus tidak ingin menyelesaikan titik akhir yang diminta. [EndpointResolverWithOptionsFunc](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolverWithOptionsFunc)dapat digunakan untuk dengan mudah membungkus fungsi untuk memenuhi `EndpointResolverWithOptions` antarmuka.
A `EndpointResolver` dapat dengan mudah dikonfigurasi dengan meneruskan resolver yang dibungkus dengan [WithEndpointResolverWithOptions](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithEndpointResolverWithOptions)to [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig), memungkinkan kemampuan untuk mengganti titik akhir saat memuat kredensi, serta mengonfigurasi hasil dengan resolver titik akhir kustom Anda. `aws.Config`
Penyelesai titik akhir diberikan layanan dan wilayah sebagai string, memungkinkan resolver untuk mendorong perilakunya secara dinamis. Setiap paket klien layanan memiliki `ServiceID` konstanta yang diekspor yang dapat digunakan untuk menentukan klien layanan mana yang memanggil resolver endpoint Anda.
Resolver endpoint dapat menggunakan nilai kesalahan [EndpointNotFoundError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointNotFoundError)sentinel untuk memicu resolusi fallback ke logika resolusi default klien layanan. Ini memungkinkan Anda untuk secara selektif mengganti satu atau lebih titik akhir dengan mulus tanpa harus menangani logika fallback.
Jika implementasi endpoint resolver Anda mengembalikan kesalahan selain`EndpointNotFoundError`, resolusi endpoint akan berhenti dan operasi layanan mengembalikan error ke aplikasi Anda.
### Contoh
#### Dengan fallback
Cuplikan kode berikut menunjukkan bagaimana titik akhir layanan tunggal dapat diganti untuk DynamoDB dengan perilaku fallback untuk titik akhir lainnya:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
}, nil
}
// returning EndpointNotFoundError will allow the service to fallback to it's default resolution
return aws.Endpoint{}, &aws.EndpointNotFoundError{}
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
#### Tanpa fallback
Cuplikan kode berikut menunjukkan bagaimana titik akhir layanan tunggal dapat diganti untuk DynamoDB tanpa perilaku fallback untuk titik akhir lainnya:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
}, nil
}
return aws.Endpoint{}, fmt.Errorf("unknown endpoint requested")
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
### Titik akhir yang tidak dapat diubah
**Awas**
Menyetel titik akhir sebagai tidak dapat diubah dapat mencegah beberapa fitur klien layanan berfungsi dengan benar, dan dapat mengakibatkan perilaku yang tidak terdefinisi. Perhatian harus diambil saat mendefinisikan titik akhir sebagai tidak dapat diubah.
Beberapa klien layanan, seperti Amazon S3, dapat memodifikasi titik akhir yang dikembalikan oleh resolver untuk operasi layanan tertentu. Misalnya, Amazon S3 akan secara otomatis menangani [Virtual Bucket Addressing](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html) dengan mengubah titik akhir yang diselesaikan. Anda dapat mencegah SDK mengubah titik akhir kustom Anda dengan menyetelnya. [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)`true` Contoh:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
HostnameImmutable: true,
}, nil
}
return aws.Endpoint{}, fmt.Errorf("unknown endpoint requested")
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
## Migrasi
Saat bermigrasi dari v1 ke v2 resolusi titik akhir, prinsip umum berikut berlaku:
+ Mengembalikan [Endpoint](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint) dengan [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)set to kira-kira `false` setara dengan pengaturan `BaseEndpoint` ke URL yang dikembalikan semula dari v1 dan meninggalkannya `EndpointResolverV2` sebagai default.
+ Mengembalikan Endpoint dengan HostnameImmutable set to kira-kira `true` setara dengan mengimplementasikan `EndpointResolverV2` yang mengembalikan URL yang dikembalikan semula dari v1.
+ Pengecualian utama adalah untuk operasi dengan awalan titik akhir yang dimodelkan. Catatan tentang ini diberikan lebih jauh ke bawah.
Contoh untuk kasus-kasus ini disediakan di bawah ini.
**Awas**
Titik akhir yang tidak dapat diubah V1 dan resolusi V2 tidak setara dalam perilaku. Misalnya, penandatanganan penggantian untuk fitur khusus seperti S3 Object Lambda masih akan disetel untuk titik akhir yang tidak dapat diubah yang dikembalikan melalui kode v1, tetapi hal yang sama tidak akan dilakukan untuk v2.
### Catatan tentang awalan host
Beberapa operasi dimodelkan dengan awalan host untuk ditambahkan ke titik akhir yang diselesaikan. Perilaku ini harus bekerja bersama-sama dengan output ResolveEndpoint V2 dan oleh karena itu awalan host akan tetap diterapkan pada hasil itu.
Anda dapat menonaktifkan awalan host endpoint secara manual dengan menerapkan middleware, lihat bagian contoh.
### Contoh
#### Titik akhir yang bisa berubah
Contoh kode berikut menunjukkan cara memigrasikan resolver endpoint v1 dasar yang mengembalikan titik akhir yang dapat dimodifikasi:
```
// v1
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolver = svc.EndpointResolverFromURL("https://custom.endpoint.api/")
})
// v2
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
// the value of BaseEndpoint is passed to the default EndpointResolverV2
// implementation, which will handle routing for features such as S3 accelerate,
// MRAP, etc.
o.BaseEndpoint = aws.String("https://custom.endpoint.api/")
})
```
#### Titik akhir yang tidak dapat diubah
```
// v1
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolver = svc.EndpointResolverFromURL("https://custom.endpoint.api/", func (e *aws.Endpoint) {
e.HostnameImmutable = true
})
})
// v2
import (
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type staticResolver struct {}
func (*staticResolver) ResolveEndpoint(ctx context.Context, params svc.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
// This value will be used as-is when making the request.
u, err := url.Parse("https://custom.endpoint.api/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{
URI: *u,
}, nil
}
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolverV2 = &staticResolver{}
})
```
#### Nonaktifkan awalan host
```
import (
"context"
"fmt"
"net/url"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/"
smithyendpoints "github.com/aws/smithy-go/endpoints"
"github.com/aws/smithy-go/middleware"
smithyhttp "github.com/aws/smithy-go/transport/http"
)
// disableEndpointPrefix applies the flag that will prevent any
// operation-specific host prefix from being applied
type disableEndpointPrefix struct{}
func (disableEndpointPrefix) ID() string { return "disableEndpointPrefix" }
func (disableEndpointPrefix) HandleInitialize(
ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler,
) (middleware.InitializeOutput, middleware.Metadata, error) {
ctx = smithyhttp.SetHostnameImmutable(ctx, true)
return next.HandleInitialize(ctx, in)
}
func addDisableEndpointPrefix(o *.Options) {
o.APIOptions = append(o.APIOptions, (func(stack *middleware.Stack) error {
return stack.Initialize.Add(disableEndpointPrefix{}, middleware.After)
}))
}
type staticResolver struct{}
func (staticResolver) ResolveEndpoint(ctx context.Context, params .EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
u, err := url.Parse("https://custom.endpoint.api/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{URI: *u}, nil
}
func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if err != nil {
panic(err)
}
svc := .NewFromConfig(cfg, func(o *.Options) {
o.EndpointResolverV2 = staticResolver{}
})
_, err = svc.(context.Background(), &.{ /* ... */ },
addDisableEndpointPrefix)
if err != nil {
panic(err)
}
}
```
# Sesuaikan Klien HTTP
AWS SDK untuk Go Menggunakan klien HTTP default dengan nilai konfigurasi default. Meskipun Anda dapat mengubah beberapa nilai konfigurasi ini, klien HTTP default dan transport tidak cukup dikonfigurasi untuk pelanggan yang menggunakan AWS SDK untuk Go dalam lingkungan dengan throughput tinggi dan persyaratan latensi rendah. Untuk informasi lebih lanjut, silakan lihat rekomendasi konfigurasi [Pertanyaan yang Sering Diajukan](faq-gosdk.md) as bervariasi berdasarkan beban kerja tertentu. Bagian ini menjelaskan cara mengkonfigurasi klien HTTP kustom, dan menggunakan klien tersebut untuk membuat AWS SDK untuk Go panggilan.
Untuk membantu Anda dalam membuat klien HTTP kustom, bagian ini menjelaskan cara [NewBuildableClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/transport/http#NewBuildableClient)untuk mengkonfigurasi pengaturan kustom, dan menggunakan klien itu dengan klien AWS SDK untuk Go layanan.
Mari kita definisikan apa yang ingin kita sesuaikan.
## Mengganti Selama Pemuatan Konfigurasi
Klien HTTP kustom dapat diberikan saat memanggil [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig)dengan membungkus klien menggunakan [With HTTPClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithHTTP) dan meneruskan nilai yang dihasilkan ke`LoadDefaultConfig`. Misalnya, untuk lulus `customClient` sebagai klien kami:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithHTTPClient(customClient))
```
## Waktu habis
`BuildableHTTPClient`Dapat dikonfigurasi dengan batas waktu tunggu permintaan. Batas waktu ini mencakup waktu untuk terhubung, memproses pengalihan apa pun, dan membaca badan respons lengkap. Misalnya, untuk memodifikasi batas waktu klien:
```
import "github.com/aws/aws-sdk-go-v2/aws/transport/http"
// ...
httpClient := http.NewBuildableClient().WithTimeout(time.Second*5)
```
## Dialer
`BuildableHTTPClient`Ini menyediakan mekanisme pembangun untuk membangun klien dengan opsi [Dialer](https://golang.org/pkg/net/#Dialer) yang dimodifikasi. Contoh berikut menunjukkan cara mengkonfigurasi `Dialer` pengaturan klien.
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net"
// ...
httpClient := awshttp.NewBuildableClient().WithDialerOptions(func(d *net.Dialer) {
d.KeepAlive = -1
d.Timeout = time.Millisecond*500
})
```
### Pengaturan
#### Dialer. KeepAlive
Pengaturan ini mewakili periode keep-alive untuk koneksi jaringan aktif.
Setel ke nilai negatif untuk menonaktifkan keep-alives.
Setel ke **0** untuk mengaktifkan keep-alives jika didukung oleh protokol dan sistem operasi.
Protokol jaringan atau sistem operasi yang tidak mendukung keep-alives mengabaikan bidang ini. Secara default, TCP memungkinkan tetap hidup.
Lihat [https://golang. org/pkg/net/\$1Dialer. KeepAlive](https://golang.org/pkg/net/#Dialer.KeepAlive)
Tetapkan `KeepAlive` sebagai **time.Duration.**
#### Dialer.Timeout
Pengaturan ini mewakili jumlah maksimum waktu dial menunggu koneksi dibuat.
Defaultnya adalah 30 detik.
Lihat [https://golang. org/pkg/net/\$1Dialer .Timeout](https://golang.org/pkg/net/#Dialer.Timeout)
Tetapkan `Timeout` sebagai **time.Duration.**
## Transportasi
`BuildableHTTPClient`Ini menyediakan mekanisme pembangun untuk membangun klien dengan opsi [Transportasi](https://golang.org/pkg/net/http#Transport) yang dimodifikasi.
### Mengkonfigurasi Proxy
Jika Anda tidak dapat langsung terhubung ke internet, Anda dapat menggunakan variabel lingkungan yang didukung GO (`HTTP_PROXY`/`HTTPS_PROXY`) atau membuat klien HTTP khusus untuk mengonfigurasi proxy Anda. Contoh berikut mengonfigurasi klien untuk digunakan `PROXY_URL` sebagai titik akhir proxy:
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net/http"
// ...
httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) {
proxyURL, err := url.Parse("PROXY_URL")
if err != nil {
log.Fatal(err)
}
tr.Proxy = http.ProxyURL(proxyURL)
})
```
### Pengaturan Lainnya
Di bawah ini adalah beberapa `Transport` pengaturan lain yang dapat dimodifikasi untuk menyetel klien HTTP. Pengaturan tambahan apa pun yang tidak dijelaskan di sini dapat ditemukan di dokumentasi tipe [Transport](https://golang.org/pkg/net/http/#Transport). Pengaturan ini dapat diterapkan seperti yang ditunjukkan pada contoh berikut:
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net/http"
// ...
httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) {
tr.ExpectContinueTimeout = 0
tr.MaxIdleConns = 10
})
```
#### Transportasi. ExpectContinueTimeout
Jika permintaan memiliki header “Expect: 100-continue”, pengaturan ini mewakili jumlah waktu maksimum untuk menunggu header respons pertama server setelah sepenuhnya menulis header permintaan, Kali ini tidak termasuk waktu untuk mengirim header permintaan. Klien HTTP mengirimkan payloadnya setelah batas waktu ini habis.
Default 1 detik.
Setel ke **0** tanpa batas waktu dan kirim payload permintaan tanpa menunggu. Salah satu kasus penggunaan adalah ketika Anda mengalami masalah dengan proxy atau layanan pihak ketiga yang mengambil sesi yang mirip dengan penggunaan Amazon S3 dalam fungsi yang ditampilkan nanti.
Lihat [https://golang. org/pkg/net/http/\$1Transport. ExpectContinueTimeout](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout)
Tetapkan `ExpectContinue` sebagai **time.Duration.**
#### Transportasi. IdleConnTimeout
Pengaturan ini mewakili jumlah maksimum waktu untuk menjaga koneksi jaringan idle tetap hidup antara permintaan HTTP.
Setel ke **0** tanpa batas.
Lihat [https://golang. org/pkg/net/http/\$1Transport. IdleConnTimeout](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout)
Tetapkan `IdleConnTimeout` sebagai **time.Duration.**
#### Transportasi. MaxIdleConns
Pengaturan ini mewakili jumlah maksimum koneksi idle (keep-alive) di semua host. Salah satu kasus penggunaan untuk meningkatkan nilai ini adalah ketika Anda melihat banyak koneksi dalam waktu singkat dari klien yang sama
**0** berarti tidak ada batas.
Lihat [https://golang. org/pkg/net/http/\$1Transport. MaxIdleConns](https://golang.org/pkg/net/http/#Transport.MaxIdleConns)
Tetapkan `MaxIdleConns` sebagai **int**.
#### Transportasi. MaxIdleConnsPerHost
Pengaturan ini mewakili jumlah maksimum koneksi idle (keep-alive) untuk disimpan per host. Salah satu kasus penggunaan untuk meningkatkan nilai ini adalah ketika Anda melihat banyak koneksi dalam waktu singkat dari klien yang sama
Default adalah dua koneksi idle per host.
Setel ke **0** untuk menggunakan DefaultMaxIdleConnsPerHost (2).
Lihat [https://golang. org/pkg/net/http/\$1Transport. MaxIdleConnsPerHost](https://golang.org/pkg/net/http/#Transport.MaxIdleConnsPerHost)
Tetapkan `MaxIdleConnsPerHost` sebagai **int**.
#### Transportasi. ResponseHeaderTimeout
Pengaturan ini mewakili jumlah waktu maksimum untuk menunggu klien membaca header respons.
Jika klien tidak dapat membaca header respons dalam durasi ini, permintaan gagal dengan kesalahan batas waktu.
Hati-hati menyetel nilai ini saat menggunakan fungsi Lambda yang berjalan lama, karena operasi tidak mengembalikan header respons apa pun hingga fungsi Lambda selesai atau habis waktu. Namun, Anda masih dapat menggunakan opsi ini dengan operasi API InvokeAsync \$1\$1 \$1\$1.
Default adalah tidak ada batas waktu; tunggu selamanya.
Lihat [https://golang. org/pkg/net/http/\$1Transport. ResponseHeaderTimeout](https://golang.org/pkg/net/http/#Transport.ResponseHeaderTimeout)
Tetapkan `ResponseHeaderTimeout` sebagai **time.Duration.**
#### Transportasi. TLSHandshakeBatas waktu
Pengaturan ini mewakili jumlah waktu maksimum menunggu jabat tangan TLS selesai.
Default-nya 10 detik.
Nol berarti tidak ada batas waktu.
Lihat [https://golang. org/pkg/net/http/\$1Transport. TLSHandshakeBatas waktu](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout)
Tetapkan `TLSHandshakeTimeout` sebagai **time.Duration.**
# Pencegat HTTP
Anda dapat menggunakan pencegat untuk menghubungkan eksekusi permintaan dan tanggapan API. Pencegat adalah mekanisme terbuka di mana SDK memanggil kode yang Anda tulis untuk menyuntikkan perilaku ke dalam siklus hidup. request/response Dengan cara ini, Anda dapat mengubah permintaan dalam penerbangan, proses permintaan debug, pengecualian tampilan, dan lainnya.
## Pencegat vs middleware
AWS SDK untuk Go V2 menyediakan pencegat dan middleware untuk menyesuaikan pemrosesan permintaan. Meskipun keduanya melayani tujuan yang sama, keduanya dirancang untuk audiens dan kasus penggunaan yang berbeda:
+ **Interceptor** dirancang untuk pengguna SDK yang ingin menyesuaikan request/response pemrosesan dengan API sederhana yang berfokus pada HTTP. Mereka menyediakan titik kait tertentu dalam siklus hidup permintaan dan bekerja secara langsung dengan permintaan dan tanggapan HTTP.
+ **Middleware** adalah sistem transport-agnostik yang lebih canggih yang terutama digunakan secara internal oleh SDK. Meskipun kuat, middleware membutuhkan pengetahuan yang lebih dalam tentang internal SDK dan melibatkan antarmuka yang lebih kompleks.
Keuntungan utama pencegat dibandingkan middleware untuk kasus penggunaan umum:
+ **Berfokus pada HTTP**: Interceptor bekerja secara langsung dengan permintaan dan tanggapan HTTP, menghilangkan kebutuhan untuk memeriksa tipe transport yang dibutuhkan middleware.
+ **Antarmuka yang lebih sederhana**: Setiap kait pencegat memiliki antarmuka yang spesifik dan terfokus daripada pola middleware generik.
+ **Model eksekusi yang lebih jelas**: Pencegat mengeksekusi pada titik yang terdefinisi dengan baik dalam siklus hidup permintaan tanpa memerlukan pengetahuan tentang pemesanan tumpukan middleware.
**catatan**
Pencegat dibangun di atas sistem middleware yang ada, sehingga keduanya dapat hidup berdampingan dalam aplikasi yang sama. Middleware tetap tersedia untuk kasus penggunaan lanjutan yang memerlukan perilaku transport-agnostik atau manipulasi tumpukan kompleks.
## Kait pencegat yang tersedia
AWS SDK untuk Go V2 menyediakan kait pencegat pada berbagai tahap siklus hidup permintaan. Setiap kait sesuai dengan antarmuka tertentu yang dapat Anda terapkan:
+ `BeforeExecution`- Hook pertama dipanggil selama eksekusi operasi
+ `BeforeSerialization`- Sebelum pesan masukan diserialisasikan ke dalam permintaan transport
+ `AfterSerialization`- Setelah pesan masukan diserialisasikan ke dalam permintaan transportasi
+ `BeforeRetryLoop`- Sebelum memasuki loop coba lagi
+ `BeforeAttempt`- Kait pertama disebut di dalam loop coba lagi
+ `BeforeSigning`- Sebelum permintaan transportasi ditandatangani
+ `AfterSigning`- Setelah permintaan transportasi ditandatangani
+ `BeforeTransmit`- Sebelum permintaan transportasi dikirim
+ `AfterTransmit`- Setelah menerima respon transportasi
+ `BeforeDeserialization`- Sebelum respon transportasi dideserialisasi
+ `AfterDeserialization`- Setelah membongkar respons transportasi
+ `AfterAttempt`- Kait terakhir disebut di dalam loop coba lagi
+ `AfterExecution`- Hook terakhir dipanggil selama eksekusi operasi
Anda dapat mengimplementasikan beberapa antarmuka dalam satu pencegat untuk menghubungkan ke beberapa tahap siklus hidup permintaan.
## Pendaftaran pencegat
Anda mendaftarkan pencegat ketika Anda membangun klien layanan atau ketika Anda mengganti konfigurasi untuk operasi tertentu. Pendaftaran berbeda tergantung pada apakah Anda ingin pencegat berlaku untuk semua operasi untuk klien Anda atau hanya yang spesifik.
Pencegat dikelola melalui registri pencegat yang menyediakan metode untuk menambah dan menghapus pencegat. Contoh berikut menunjukkan pencegat sederhana yang menambahkan header ID AWS X-Ray jejak ke permintaan keluar sebelum proses penandatanganan:
```
type recursionDetection struct{}
func (recursionDetection) BeforeSigning(ctx context.Context, in *smithyhttp.InterceptorContext) error {
if traceID := os.Getenv("_X_AMZN_TRACE_ID"); traceID != "" {
in.Request.Header.Set("X-Amzn-Trace-Id", traceID)
}
return nil
}
// use it on the client
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
Registri pencegat ditambahkan ke Opsi klien, yang memungkinkan konfigurasi pencegat per operasi:
```
// ... or use it per-operation
s3.ListBuckets(context.Background(), &s3.ListBucketsInput{
}, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
## Konfigurasi pencegat global
Anda juga dapat mendaftarkan pencegat secara global menggunakan `config.LoadDefaultConfig` fungsi dengan `With*` opsi yang sesuai untuk setiap jenis pencegat. Ini berlaku pencegat untuk semua klien AWS layanan yang dibuat dari konfigurasi itu:
```
type myExecutionInterceptor struct{}
func (*myExecutionInterceptor) AfterExecution(ctx context.Context, in *smithyhttp.InterceptorContext) error {
// Add your custom logic here
return nil
}
cfg, err := config.LoadDefaultConfig(context.Background(),
config.WithAfterExecution(&myExecutionInterceptor{}))
if err != nil {
panic(err)
}
// every service client created from the above config
// will include this interceptor
svc := s3.NewFromConfig(cfg)
```
# Pencatatan log
Ini AWS SDK untuk Go memiliki fasilitas pencatatan yang tersedia yang memungkinkan aplikasi Anda mengaktifkan informasi debugging untuk debugging dan mendiagnosis masalah atau kegagalan permintaan. Antarmuka [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) dan [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)merupakan komponen utama yang tersedia bagi Anda untuk menentukan bagaimana dan apa yang harus dicatat oleh klien.
## Pencatat
Saat membuat [Config [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig)](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config)menggunakan `Logger` default dikonfigurasi untuk mengirim pesan log ke kesalahan standar proses (stderr). [Logger khusus yang memenuhi antarmuka [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) dapat diteruskan sebagai argumen `LoadDefaultConfig` dengan membungkusnya dengan konfigurasi. WithLogger](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithLogger).
Misalnya, untuk mengkonfigurasi klien kami untuk menggunakan`applicationLogger`:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger))
```
Sekarang klien yang dikonfigurasi menggunakan yang dibangun `aws.Config` akan mengirim pesan log ke`applicationLogger`.
### Logger Sadar Konteks
Implementasi Logger dapat mengimplementasikan [ContextLogger](https://pkg.go.dev/github.com/aws/smithy-go/logging#ContextLogger)antarmuka opsional. Logger yang mengimplementasikan antarmuka ini akan memiliki `WithContext` metode mereka dipanggil dengan konteks saat ini. Ini memungkinkan implementasi logging Anda mengembalikan yang baru `Logger` yang dapat menulis metadata logging tambahan berdasarkan nilai yang ada dalam konteks.
## ClientLogMode
Secara default, klien layanan tidak menghasilkan pesan log. Untuk mengonfigurasi klien untuk mengirim pesan log untuk tujuan debugging, gunakan [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)anggota di`Config`. `ClientLogMode`dapat diatur untuk mengaktifkan pesan debugging untuk:
+ Tanda Tangan Versi 4 (SiGv4) Penandatanganan
+ Minta Coba Ulang
+ Permintaan HTTP
+ Tanggapan HTTP
Misalnya, untuk mengaktifkan pencatatan permintaan HTTP dan percobaan ulang:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest))
```
Lihat [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)untuk berbagai mode log klien yang tersedia.
# Jejak dan metrik
Alat AWS SDK untuk Go ini diinstrumentasi untuk merekam rentang jejak dan metrik sisi klien untuk operasi SDK. Secara default, klien menggunakan implementasi no-op untuk penelusuran dan metrik, yang berarti tidak ada data yang dikumpulkan kecuali Anda mengonfigurasi penyedia.
Klien layanan memiliki dua opsi konfigurasi untuk observabilitas:
+ [TracerProvider](https://pkg.go.dev/github.com/aws/smithy-go/tracing#TracerProvider)— Titik masuk untuk membuat pelacak dan merekam rentang jejak klien.
+ [MeterProvider](https://pkg.go.dev/github.com/aws/smithy-go/metrics#MeterProvider)— Titik masuk untuk membuat meter dan merekam metrik sisi klien.
Meskipun terinspirasi oleh spesifikasi OpenTelemetry (OTel), ini didefinisikan APIs secara independen di`smithy-go`. SDK menyediakan modul adaptor untuk menghubungkan implementasi OTel SDK konkret ke antarmuka penyedia SDK.
## Pelacakan
Gunakan modul adaptor [smithyoteltracing](https://pkg.go.dev/github.com/aws/smithy-go/tracing/smithyoteltracing) untuk menghubungkan ke klien layanan. OTel `trace.TracerProvider`
Contoh berikut menunjukkan cara mengonfigurasi penelusuran untuk klien Amazon S3:
```
import (
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go/tracing/smithyoteltracing"
"go.opentelemetry.io/otel/trace"
)
// provider is an OTel trace.TracerProvider that you have configured.
var provider trace.TracerProvider
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.TracerProvider = smithyoteltracing.Adapt(provider)
})
```
Operasi SDK diinstrumentasi dengan hierarki rentang yang mencakup komponen tingkat tinggi dari siklus hidup operasi, seperti serialisasi permintaan, penandatanganan, dan loop coba lagi.
## Metrik-metrik
Gunakan modul adaptor [smithyotelmetrics](https://pkg.go.dev/github.com/aws/smithy-go/metrics/smithyotelmetrics) untuk menghubungkan ke klien layanan. OTel `metric.MeterProvider`
Contoh berikut menunjukkan cara mengonfigurasi metrik untuk klien Amazon S3:
```
import (
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go/metrics/smithyotelmetrics"
"go.opentelemetry.io/otel/metric"
)
// provider is an OTel metric.MeterProvider that you have configured.
var provider metric.MeterProvider
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.MeterProvider = smithyotelmetrics.Adapt(provider)
})
```
### Metrik yang didukung
Klien SDK mengumpulkan metrik berikut:
| Nama metrik | Unit | Tipe | Deskripsi |
| --- | --- | --- | --- |
| client.call.duration | detik | Histogram | Durasi panggilan keseluruhan termasuk percobaan ulang dan waktu untuk mengirim atau menerima permintaan dan badan respons. |
| client.call.attempts | \$1mencoba\$1 | MonotonicCounter | Jumlah upaya untuk operasi individu. |
| client.call.errors | \$1kesalahan\$1 | MonotonicCounter | Jumlah kesalahan untuk suatu operasi. |
| client.call.attempt\$1duration | detik | Histogram | Waktu untuk terhubung ke layanan, mengirim permintaan, dan mendapatkan kembali kode status HTTP dan header (termasuk waktu antrian menunggu untuk dikirim). |
| client.call.resolve\$1endpoint\$1duration | detik | Histogram | Waktu untuk menyelesaikan titik akhir (endpoint resolver, bukan DNS) untuk permintaan. |
| client.call.deserialization\$1duration | detik | Histogram | Waktu untuk deserialisasi badan pesan. |
| client.call.auth.signing\$1duration | detik | Histogram | Waktu untuk menandatangani permintaan. |
| client.call.auth.resolve\$1identity\$1duration | detik | Histogram | Waktu untuk memperoleh identitas (AWS kredensyal, token pembawa, dll.) Dari penyedia identitas. |
Atribut (dimensi) berikut disertakan dengan setiap metrik jika berlaku:
+ `rpc.service`- Nama layanan.
+ `rpc.method`Nama operasi.
+ `exception.type`— Jenis kesalahan (disertakan dengan`client.call.errors`).
+ `auth.scheme_id`— Skema otentikasi (disertakan dengan metrik terkait auth-related).
### Metrik klien HTTP
Klien HTTP SDK mengumpulkan metrik tambahan berikut yang terkait dengan siklus hidup koneksi HTTP yang mendasarinya:
| Nama metrik | Unit | Tipe | Deskripsi |
| --- | --- | --- | --- |
| client.http.connections.acquire\$1duration | detik | Histogram | Waktu yang dibutuhkan permintaan untuk mendapatkan koneksi. |
| client.http.connections.dns\$1lookup\$1duration | detik | Histogram | Waktu yang dibutuhkan untuk melakukan pencarian DNS. |
| client.http.connections.tls\$1handshake\$1duration | detik | Histogram | Waktu yang dibutuhkan untuk melakukan jabat tangan TLS. |
| client.http.connections.usage | \$1koneksi\$1 | UpDownCounter | Keadaan koneksi saat ini di kolam renang. Menggunakan state dimensi dengan nilai idle atauacquired. |
| client.http.do\$1request\$1duration | detik | Histogram | Total waktu yang dihabiskan untuk melakukan permintaan HTTP. |
| client.http.time\$1to\$1first\$1byte | detik | Histogram | Waktu dari mengirim permintaan untuk menerima byte respons pertama. |
# Coba Ulang dan Batas Waktu
AWS SDK untuk Go Ini memungkinkan Anda untuk mengonfigurasi perilaku percobaan ulang permintaan ke layanan HTTP. Secara default, klien layanan menggunakan [Retry.standard sebagai retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) default mereka. Jika konfigurasi atau perilaku default tidak memenuhi persyaratan aplikasi, Anda dapat menyesuaikan konfigurasi retryer atau menyediakan implementasi retryer Anda sendiri.
AWS SDK untuk Go Ini menyediakan antarmuka [AWS.Retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Retryer) yang mendefinisikan kumpulan metode yang diperlukan oleh implementasi coba lagi untuk diimplementasikan. [SDK menyediakan dua implementasi untuk percobaan ulang: [retry.Standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) dan aws. NoOpRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NoOpRetryer).
## Retryer Standar
[Retry.standard retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) adalah `aws.Retryer` implementasi default yang digunakan oleh klien SDK. Retryer standar adalah retryer terbatas dengan jumlah upaya maksimal yang dapat dikonfigurasi, dan kemampuan untuk menyetel kebijakan mundur permintaan.
Tabel berikut mendefinisikan nilai default untuk retryer ini:
| Properti | Default |
| --- | --- |
| Jumlah Upaya Maks | 3 |
| Penundaan Mundur Maks | 20 detik |
Ketika kesalahan yang dapat dicoba ulang terjadi saat menjalankan permintaan Anda, retryer standar akan menggunakan konfigurasi yang disediakan untuk menunda dan kemudian mencoba kembali permintaan tersebut. Mencoba lagi menambah latensi keseluruhan permintaan Anda, dan Anda harus mengonfigurasi retryer jika konfigurasi default tidak memenuhi persyaratan aplikasi Anda.
Lihat dokumentasi paket [coba ulang](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry) untuk detail tentang kesalahan apa yang dianggap dapat dicoba ulang oleh implementasi retryer standar.
## NopRetryer
[Aw. NopRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NopRetryer)adalah `aws.Retryer` implementasi yang disediakan jika Anda ingin menonaktifkan semua upaya coba lagi. Saat menjalankan operasi klien layanan, retryer ini hanya akan mengizinkan permintaan untuk dicoba sekali, dan kesalahan apa pun yang dihasilkan akan dikembalikan ke aplikasi panggilan.
## Menyesuaikan Perilaku
SDK menyediakan satu set utilitas pembantu yang membungkus `aws.Retryer` implementasi, dan mengembalikan retryer yang disediakan yang dibungkus dengan perilaku coba lagi yang diinginkan. Anda dapat mengganti retryer default untuk semua klien, per klien, atau per operasi tergantung pada kebutuhan aplikasi Anda. Untuk melihat contoh tambahan yang menunjukkan cara melakukannya, lihat contoh dokumentasi paket [coba lagi](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry).
**Awas**
Jika menentukan `aws.Retryer` implementasi global menggunakan`config.WithRetryer`, Anda harus memastikan bahwa Anda mengembalikan instance baru dari `aws.Retryer` setiap pemanggilan. Ini akan memastikan bahwa Anda tidak akan membuat ember token coba ulang global di semua klien layanan.
### Membatasi jumlah maksimal upaya
Anda menggunakan [coba lagi. AddWithMaxAttempts](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxAttempts)untuk membungkus `aws.Retryer` implementasi untuk mengatur upaya angka maksimal ke nilai yang Anda inginkan.
**Awas**
Menggunakan `retry.AddWithMaxAttempts` dengan nilai nol akan memungkinkan SDK untuk mencoba kembali semua kesalahan yang dapat dicoba ulang hingga permintaan berhasil, atau kesalahan yang tidak dapat dicoba kembali dikembalikan. **Mengizinkan SDK untuk mencoba lagi tanpa batas dapat mengakibatkan beban kerja yang tidak terkendali dan siklus penagihan yang meningkat.**
```
import "context"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
// MaxAttempts will be infinite (will retry indefinitely)
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithMaxAttempts(retry.NewStandard(), 0)
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
Perhatikan bahwa membuat instance retryer menggunakan opsi fungsional untuk disetel MaxAttempts secara langsung akan memiliki perilaku yang sedikit berbeda. Lebih khusus lagi, menyetel nilai kurang dari atau sama dengan nol akan menyebabkan retryer menggunakan maksimum default 3 percobaan, daripada mencoba lagi tanpa batas:
```
import "context"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
// MaxAttempts will default to 3
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
o.MaxAttempts = 0
})
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Membatasi penundaan mundur maksimal
Anda menggunakan [coba lagi. AddWithMaxBackoffDelay](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxBackoffDelay)untuk membungkus `aws.Retryer` implementasi dan membatasi penundaan mundur maksimal yang diizinkan terjadi antara mencoba kembali permintaan yang gagal.
Misalnya, Anda dapat menggunakan kode berikut untuk membungkus retryer klien standar dengan penundaan maksimal lima detik yang diinginkan:
```
import "context"
import "time"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithMaxBackoffDelay(retry.NewStandard(), time.Second*5)
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Coba lagi kode kesalahan API tambahan
Anda menggunakan [coba lagi. AddWithErrorCodes](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithErrorCodes)untuk membungkus `aws.Retryer` implementasi dan menyertakan kode kesalahan API tambahan yang harus dianggap dapat dicoba ulang.
Misalnya, Anda dapat menggunakan kode berikut untuk membungkus retryer klien standar untuk menyertakan pengecualian Amazon `NoSuchBucketException` S3 sebagai dapat dicoba ulang.
```
import "context"
import "time"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
import "github.com/aws/aws-sdk-go-v2/service/s3/types"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithErrorCodes(retry.NewStandard(), (*types.NoSuchBucketException)(nil).ErrorCode())
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Pembatasan tingkat sisi klien
Ini AWS SDK untuk Go memperkenalkan mekanisme pembatasan tingkat sisi klien baru dalam kebijakan coba ulang standar untuk menyelaraskan dengan perilaku modern. SDKs [Ini adalah perilaku yang dikendalikan oleh [RateLimiter](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#RateLimiter)bidang pada opsi retryer.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#StandardOptions)
A RateLimiter beroperasi sebagai ember token dengan kapasitas yang ditetapkan, di mana kegagalan upaya operasi menggunakan token. Coba lagi yang mencoba mengkonsumsi lebih banyak token daripada yang tersedia menghasilkan kegagalan operasi dengan a [QuotaExceededError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#QuotaExceededError).
Implementasi default diparameterisasi sebagai berikut (cara memodifikasi setiap pengaturan):
+ kapasitas 500 (mengatur nilai RateLimiter pada StandardOptions penggunaan [NewTokenRateLimit](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#NewTokenRateLimit))
+ coba lagi yang disebabkan oleh biaya batas waktu 10 token (ditetapkan RetryTimeoutCost ) StandardOptions
+ percobaan lagi yang disebabkan oleh kesalahan lain membutuhkan biaya 5 token (disetel RetryCost) StandardOptions
+ operasi yang berhasil pada upaya pertama menambahkan 1 token (diatur NoRetryIncrement ) StandardOptions
+ operasi yang berhasil pada upaya ke-2 atau yang lebih baru tidak menambahkan kembali token apa pun
Jika Anda menemukan bahwa perilaku default tidak sesuai dengan kebutuhan aplikasi Anda, Anda dapat menonaktifkannya dengan [RateLimit.none](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#pkg-variables).
#### Contoh: pembatas tingkat yang dimodifikasi
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/aws/ratelimit"
"github.com/aws/aws-sdk-go-v2/aws/retry"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
// Makes the rate limiter more permissive in general. These values are
// arbitrary for demonstration and may not suit your specific
// application's needs.
o.RateLimiter = ratelimit.NewTokenRateLimit(1000)
o.RetryCost = 1
o.RetryTimeoutCost = 3
o.NoRetryIncrement = 10
})
}))
```
#### Contoh: tidak ada batas tarif menggunakan RateLimit.none
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/aws/ratelimit"
"github.com/aws/aws-sdk-go-v2/aws/retry"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
o.RateLimiter = ratelimit.None
})
}))
```
## Timeout
Anda menggunakan paket [konteks](https://golang.org/pkg/context/) untuk mengatur batas waktu atau tenggat waktu saat menjalankan operasi klien layanan. Gunakan [konteksnya. WithDeadline](https://golang.org/pkg/context/#WithDeadline)untuk membungkus konteks aplikasi Anda dan menetapkan tenggat waktu ke waktu tertentu dimana operasi yang dipanggil harus diselesaikan. Untuk mengatur batas waktu setelah [konteks `time.Duration` penggunaan tertentu. WithTimeout](https://golang.org/pkg/context/#WithTimeout). SDK meneruskan yang disediakan `context.Context` ke klien transport HTTP saat menjalankan API layanan. Jika konteks yang diteruskan ke SDK dibatalkan atau dibatalkan saat menjalankan operasi, SDK tidak akan mencoba lagi permintaan lebih lanjut dan akan kembali ke aplikasi panggilan. Anda harus menangani pembatalan konteks dengan tepat dalam aplikasi Anda jika konteks yang diberikan kepada SDK telah dibatalkan.
### Menetapkan batas waktu
Contoh berikut menunjukkan cara mengatur batas waktu untuk operasi klien layanan.
```
import "context"
import "time"
// ...
ctx := context.TODO() // or appropriate context.Context value for your application
client := s3.NewFromConfig(cfg)
// create a new context from the previous ctx with a timeout, e.g. 5 seconds
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
resp, err := client.GetObject(ctx, &s3.GetObjectInput{
// input parameters
})
if err != nil {
// handle error
}
```