本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 設定軟體開發套件
<a name="configure-gosdk"></a>

 在 適用於 Go 的 AWS SDK V2 中，您可以設定服務用戶端的常見設定，例如記錄器、日誌層級和重試組態。大多數設定都是選用的。不過，您必須為每個服務用戶端指定 AWS 區域和您的登入資料。SDK 使用這些值將請求傳送至正確的區域，並使用正確的登入資料簽署請求。您可以在程式碼中或透過執行環境以程式設計方式指定這些值。

## 載入 AWS 共用組態檔案
<a name="loading-aws-shared-configuration"></a>

 有多種方式可初始化服務 API 用戶端，但以下是建議使用者使用的最常見模式。

 若要設定 SDK 以使用 AWS 共用組態檔案，請使用下列程式碼：

```
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())` 將使用 AWS 共用組態來源建構 [aws.Config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config)。這包括設定登入資料提供者、設定 AWS 區域，以及載入服務特定組態。服務用戶端可以使用載入的 建構`aws.Config`，提供建構用戶端的一致模式。

 如需 AWS 共用組態檔案的詳細資訊，請參閱《 AWS SDKs和工具參考指南》中的[組態](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html)。

## 指定 AWS 區域
<a name="specifying-the-aws-region"></a>

 當您指定 區域時，您可以指定傳送請求的位置，例如 `us-west-2`或 `us-east-2`。如需每個服務的區域清單，請參閱《》中的[服務端點和配額](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) Amazon Web Services 一般參考。

 軟體開發套件沒有預設區域。若要指定區域：
+  將`AWS_REGION`環境變數設定為預設區域。
+  載入組態`config.LoadDefaultConfig`時，使用 [config.WithRegion](https://github.com/aws/aws-sdk-go-v2/blob/config/v0.2.2/config/provider.go#L127) 明確地將區域設定為 的引數。

 檢閱：如果您使用所有這些技術設定區域，開發套件會使用您明確指定的區域。

### 使用環境變數設定區域
<a name="configure-region-with-environment-variable"></a>

#### Linux、macOS 或 Unix
<a name="linux-macos-or-unix"></a>

```
export AWS_REGION=us-west-2
```

#### Windows
<a name="windows"></a>

```
set AWS_REGION=us-west-2
```

### 以程式設計方式指定區域
<a name="specify-region-programmatically"></a>

```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
```

## 指定憑證
<a name="specifying-credentials"></a>

 適用於 Go 的 AWS SDK 需要登入資料 （存取金鑰和私密存取金鑰） 才能簽署請求 AWS。您可以根據您的特定使用案例，在多個位置指定您的登入資料。如需取得登入資料的資訊，請參閱 [開始使用 適用於 Go 的 AWS SDK](getting-started.md)。

 當您使用 初始化`aws.Config`執行個體時`config.LoadDefaultConfig`，開發套件會使用其預設登入資料鏈來尋找 AWS 登入資料。此預設登入資料鏈結會依下列順序尋找登入資料：

1.  環境變數.

   1.  靜態登入資料 (`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_SESSION_TOKEN`) 

   1.  Web 身分字符 (`AWS_WEB_IDENTITY_TOKEN_FILE`) 

1.  共用組態檔案。

   1.  SDK 預設為位於您電腦主`.aws`資料夾中 資料夾下的 `credentials` 檔案。

   1.  SDK 預設為位於您電腦主`.aws`資料夾中 資料夾下的 `config` 檔案。

1.  如果您的應用程式使用 Amazon ECS 任務定義或 RunTask API 操作，則為任務使用 IAM 角色。

1.  如果您的應用程式在 Amazon EC2 執行個體上執行，則為 Amazon EC2 的 IAM 角色。

 SDK 會自動偵測並使用內建提供者，而不需要手動設定。例如，如果您將 IAM 角色用於 Amazon EC2 執行個體，您的應用程式會自動使用執行個體的登入資料。您不需要在應用程式中手動設定登入資料。

 根據最佳實務， AWS 建議您依下列順序指定登入資料：

1.  如果您的應用程式使用 Amazon ECS 任務定義或 RunTask API 操作，請使用任務的 IAM 角色。

1.  將 IAM 角色用於 Amazon EC2 （如果您的應用程式在 Amazon EC2 執行個體上執行）。

    IAM 角色在執行個體上提供應用程式臨時安全登入資料來 AWS 呼叫 。IAM 角色提供在多個 Amazon EC2 執行個體上分佈和管理登入資料的簡單方法。

1.  使用共用的登入資料或組態檔案。

    登入資料和組態檔案會與其他 AWS SDKs和 共用 AWS CLI。作為安全最佳實務，建議使用登入資料檔案來設定敏感值，例如存取金鑰 IDs和私密金鑰。以下是每個這些檔案的[格式要求](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。

1.  使用環境變數。

    如果您在 Amazon EC2 執行個體以外的機器上執行開發工作，設定環境變數非常有用。

### 任務的 IAM 角色
<a name="iam-roles-for-tasks"></a>

 如果您的應用程式使用 Amazon ECS 任務定義或`RunTask`操作，請使用[任務的 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)來指定可由任務中的容器使用的 IAM 角色。

### Amazon EC2 執行個體的 IAM 角色
<a name="iam-roles-for-ec2-instances"></a>

 如果您在 Amazon EC2 執行個體上執行應用程式，請使用執行個體的 [IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)取得臨時安全登入資料來呼叫 AWS。

 如果您已將執行個體設定為使用 IAM 角色，軟體開發套件會自動將這些登入資料用於您的應用程式。您不需要手動指定這些登入資料。

### 共用登入資料和組態
<a name="shared-credentials-and-configuration"></a>

 共用的登入資料和組態檔案可用於在 AWS SDKs 和其他工具之間共用常見的組態。如果您將不同的登入資料用於不同的工具或應用程式，即可在同一個組態檔案中使用*描述檔*設定多個存取金鑰。

 您可以使用 提供多個登入資料或組態檔案位置`config.LoadOptions`，根據預設，軟體開發套件會載入存放在 中提及的預設位置的檔案[指定憑證](#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"},
    )   
)
```

 使用共用登入資料和組態檔案時，如果指定了重複的設定檔，則會合併這些設定檔以解析設定檔。如果發生合併衝突，

1.  如果在相同的登入資料/組態檔案中指定了重複的設定檔，則後者設定檔中指定的設定檔屬性優先。

1.  如果跨多個登入資料檔案或多個組態檔案指定了重複的設定檔，則會根據檔案輸入至 的順序來解析設定檔屬性`config.LoadOptions`。後者檔案中的設定檔屬性優先。

1.  如果 設定檔同時存在於登入資料檔案和組態檔案中，則登入資料檔案屬性優先。

 如有需要，您可以在 `LogConfigurationWarnings`上啟用 `config.LoadOptions` 並記錄設定檔解析步驟。

#### 建立登入資料檔案
<a name="creating-the-credentials-file"></a>

 如果您沒有共用的登入資料檔案 (`.aws/credentials`)，您可以使用任何文字編輯器在主目錄中建立一個。將下列內容新增至您的登入資料檔案，以您的登入資料取代 *<YOUR\$1ACCESS\$1KEY\$1ID>* 和 *<YOUR\$1SECRET\$1ACCESS\$1KEY>*。

```
[default]
aws_access_key_id = <YOUR_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>
```

 `[default]` 標題會定義預設設定檔的登入資料，除非您將其設定為使用另一個設定檔，否則軟體開發套件將使用該登入資料。

 您也可以將工作階段字符新增至您的設定檔，以使用臨時安全登入資料，如下列範例所示：

```
[temp]
aws_access_key_id = <YOUR_TEMP_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_TEMP_SECRET_ACCESS_KEY>
aws_session_token = <YOUR_SESSION_TOKEN>
```

 登入資料檔案中非預設設定檔的區段名稱不得以字詞 開頭`profile`。您可以在 [AWS SDKs和工具參考指南](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds)中閱讀更多資訊。

#### 建立 Config 檔案
<a name="creating-the-config-file"></a>

 如果您沒有共用的登入資料檔案 (`.aws/config`)，您可以使用任何文字編輯器在主目錄中建立一個。將下列內容新增至您的組態檔案，將 *<REGION>* 取代為所需的區域。

```
[default]
region = <REGION>
```

 `[default]` 標題會定義預設描述檔的組態，除非您將其設定為使用另一個描述檔，否則軟體開發套件將使用它。

 您可以使用具名設定檔，如下列範例所示：

```
[profile named-profile]
region = <REGION>
```

 組態檔案中非預設設定檔的區段名稱必須一律以單字 開頭`profile`，後面接著預期的設定檔名稱。您可以在 [AWS SDKs和工具參考指南](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-config)中閱讀更多資訊。

#### 指定設定檔
<a name="specifying-profiles"></a>

 您可以透過將每組存取金鑰與設定檔建立關聯，在相同的組態檔案中包含多個存取金鑰。例如，在您的登入資料檔案中，您可以宣告多個設定檔，如下所示。

```
[default]
aws_access_key_id = <YOUR_DEFAULT_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_DEFAULT_SECRET_ACCESS_KEY>

[test-account]
aws_access_key_id = <YOUR_TEST_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_TEST_SECRET_ACCESS_KEY>

[prod-account]
; work profile
aws_access_key_id = <YOUR_PROD_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_PROD_SECRET_ACCESS_KEY>
```

 依預設，軟體開發套件會檢查 `AWS_PROFILE` 環境變數來判斷要使用哪個設定檔。如果未設定`AWS_PROFILE`變數，則 SDK 會使用 `default`設定檔。

 有時，您可能想要在應用程式中使用不同的設定檔。例如，您想要將`test-account`登入資料與`myapp`應用程式搭配使用。您可以使用下列命令來使用此設定檔：

```
$ AWS_PROFILE=test-account myapp
```

 您也可以使用指示 SDK 在呼叫 `os.Setenv("AWS_PROFILE", "test-account")`之前呼叫 來選取設定檔`config.LoadDefaultConfig`，或傳遞明確設定檔做為引數，如下列範例所示：

```
cfg, err := config.LoadDefaultConfig(context.TODO(), 
    config.WithSharedConfigProfile("test-account"))
```

**注意**  
如果您在環境變數中指定登入資料，無論指定哪個設定檔，開發套件一律都會使用這些登入資料。

### 環境變數
<a name="environment-variables"></a>

 根據預設，軟體開發套件會偵測您環境中設定的 AWS 登入資料，並使用它們來簽署請求 AWS。如此一來，您就不需要在應用程式中管理登入資料。

 SDK 會在下列環境變數中尋找登入資料：
+  `AWS_ACCESS_KEY_ID` 
+  `AWS_SECRET_ACCESS_KEY` 
+  `AWS_SESSION_TOKEN` (選用) 

 下列範例示範如何設定環境變數。

#### Linux、OS X，或 Unix
<a name="linux-os-x-or-unix"></a>

```
$ export AWS_ACCESS_KEY_ID=YOUR_AKID
$ export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
$ export AWS_SESSION_TOKEN=TOKEN
```

#### Windows
<a name="windows-1"></a>

```
> set AWS_ACCESS_KEY_ID=YOUR_AKID
> set AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
> set AWS_SESSION_TOKEN=TOKEN
```

### 以程式設計方式指定登入資料
<a name="specify-credentials-programmatically"></a>

 `config.LoadDefaultConfig` 可讓您在載入共用組態來源時提供明確的 [aws.CredentialProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)。若要在載入共用組態時傳遞明確的登入資料提供者，請使用 [config.WithCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithCredentialsProvider)。例如，如果 `customProvider`參考`aws.CredentialProvider`實作的執行個體，它可以在組態載入期間傳遞，如下所示：

```
cfg, err := config.LoadDefaultConfig(context.TODO(), 
    config.WithCredentialsProvider(customProvider))
```

 如果您明確提供登入資料，如本範例所示，開發套件只會使用這些登入資料。

**注意**  
傳遞至 或由 傳回的所有登入資料提供者`LoadDefaultConfig`都會自動包裝在 [CredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsCache) 中。這可啟用並行安全的快取和登入資料輪換。如果您`aws.Config`直接在 上明確設定提供者，您還必須使用 [NewCredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NewCredentialsCache) 明確包裝具有此類型的提供者。

#### 靜態登入資料
<a name="static-credentials"></a>

 您可以使用登入資料在應用程式中硬式編碼[登入資料。NewStaticCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials#NewStaticCredentialsProvider) 登入資料提供者可明確設定要使用的存取金鑰。例如：

```
cfg, err := config.LoadDefaultConfig(context.TODO(), 
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("AKID", "SECRET_KEY", "TOKEN")),
)
```

**警告**  
 請勿在應用程式中內嵌登入資料。僅將此方法用於測試目的。

#### 單一登入登入資料
<a name="single-sign-on-credentials"></a>

 開發套件提供登入資料提供者，以使用 擷取臨時 AWS 登入資料 AWS IAM Identity Center。使用 AWS CLI，您可以使用 AWS 存取入口網站進行身分驗證，並授權存取臨時 AWS 登入資料。然後，您將應用程式設定為載入單一登入 (SSO) 設定檔，開發套件會使用 SSO 登入資料來擷取臨時 AWS 登入資料，該登入資料將在過期時自動續約。如果您的 SSO 憑證過期，您必須再次使用 登入 IAM Identity Center 帳戶，以明確續約憑證 AWS CLI。

 例如，您可以建立設定檔、`dev-profile`、使用 驗證和授權該設定檔 AWS CLI，以及設定您的應用程式，如下所示。

1.  首先建立 `profile`和 `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.  使用 登入 AWS CLI 以驗證和授權 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.  接著，將應用程式設定為使用 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
}
```

 如需設定 SSO 設定檔和使用 驗證的詳細資訊， AWS CLI 請參閱《 使用者指南》中的[設定 AWS CLI 要使用 AWS IAM Identity Center](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html)的 AWS CLI 。如需以程式設計方式建構 SSO 憑證提供者的詳細資訊，請參閱 [ssocreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ssocreds) API 參考文件。

#### 登入憑證
<a name="login-credentials"></a>

您可以使用現有的 AWS 管理主控台登入憑證，以程式設計方式存取 AWS 服務。在瀏覽器型身分驗證流程之後， AWS 會產生臨時登入資料，可用於 CLI AWS Tools for PowerShell 和 AWS SDKs AWS 等本機開發工具。此功能可簡化設定和管理 AWS CLI 登入資料的程序，尤其是如果您偏好互動式身分驗證，而不是管理長期存取金鑰。

1. 使用 CLI AWS 啟動登入流程，並遵循瀏覽器提示。在此範例中，我們會將登入工作階段儲存至新的設定檔 **dev-profile**，但這是選用的。

   ```
   $ aws --profile dev-profile login
   ```

1. （選用） 檢查您的 AWS 共用組態檔案，以確認工作階段已建立。

   ```
   [profile dev-profile]
   login_session = arn:aws:sts::account id>:role
   ```

1. 接著，將應用程式設定為使用登入設定檔。

   ```
   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
   }
   ```

如需設定登入設定檔及使用 AWS CLI 驗證的詳細資訊，請參閱[使用主控台登入資料進行 AWS 本機開發的登入](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)。

#### 其他登入資料提供者
<a name="other-credentials-providers"></a>

 SDK 提供在登入資料模組中擷取[登入](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials)資料的其他方法。例如，您可以從 擷取臨時安全登入資料 AWS Security Token Service ，或從加密儲存擷取登入資料。

 **可用的登入資料提供者**：
+  [ec2rolecreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds) – 透過 Amazon EC2 IMDS 從 Amazon EC2 執行個體角色擷取登入資料。
+  [endpointcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/endpointcreds) – 從任意 HTTP 端點擷取登入資料。
+  [processcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/processcreds) – 從外部程序擷取登入資料，該程序將由主機環境的 shell 叫用。
+  [stscreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/stscreds) – 從 擷取登入資料 AWS STS