Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Konfigurasikan Titik Akhir Klien
<a name="configure-endpoints"></a>

**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
<a name="customization"></a>

 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`
<a name="v2-endpointresolverv2--baseendpoint"></a>

 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`
<a name="endpointresolverv2-parameters"></a>

 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
<a name="a-note-about-amazon-s3"></a>

 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
<a name="examples"></a>

#### dengan `BaseEndpoint`
<a name="with-baseendpoint"></a>

 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`
<a name="with-endpointresolverv2"></a>

 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
<a name="with-both"></a>

 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`
<a name="v1-endpointresolver"></a>

**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
<a name="examples-1"></a>

#### Dengan fallback
<a name="with-fallback"></a>

 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
<a name="without-fallback"></a>

 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
<a name="immutable-endpoints"></a>

**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
<a name="migration"></a>

 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
<a name="note-on-host-prefixes"></a>

 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
<a name="examples-2"></a>

#### Titik akhir yang bisa berubah
<a name="mutable-endpoint"></a>

 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
<a name="immutable-endpoint"></a>

```
// 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
<a name="disable-host-prefix"></a>

```
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/<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 *<service>.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 <service>.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 := <service>.NewFromConfig(cfg, func(o *<service>.Options) {
        o.EndpointResolverV2 = staticResolver{}
    })

    _, err = svc.<Operation>(context.Background(), &<service>.<OperationInput>{ /* ... */ },
        addDisableEndpointPrefix)
    if err != nil {
        panic(err)
    }
}
```