Alibaba Cloud SDK：用戶端初始化和請求方式

用戶端初始化方式

• 使用AccessKey

  阿里雲帳號和RAM使用者可以產生用於調用OpenAPI的AccessKey金鑰組，您可以使用該AccessKey初始化用戶端。

  重要

  由於主帳號AccessKey有資源完全的許可權，一旦泄露風險巨大。建議您使用RAM使用者的AccessKey，並設定定期輪換，建立RAM使用者AccessKey的方法請參見建立AccessKey。

  package main
  
  import (
  	"os"
  
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  )
  
  func main() {
  	// 使用AccessKey初始化SDK用戶端
          // 這裡通過環境變數擷取RAM使用者的AccessKey ID和AccessKey Secret，以避免寫入程式碼帶來的安全風險
  	client, err := sdk.NewClientWithAccessKey("<regionId>", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
  }
  

• 使用STS Token

  通過Security Token Service（Security Token Service，簡稱 STS），申請臨時安全憑證（Temporary Security Credentials，簡稱 TSC），建立臨時安全用戶端。

  package main
  
  import (
  	"os"
  
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  )
  
  func main() {
  	// 使用STS（Security Token Service）令牌建立SDK用戶端
  	// 這種方式適用於需要臨時存取權限的情境，比如ECI（Elastic Container Instance）
  	client, err := sdk.NewClientWithStsToken("<regionId>", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"), os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN"))
  }

• 使用RamRoleArn

  通過指定RAM角色的ARN（Alibabacloud Resource Name）來初始化用戶端。其底層實現邏輯是用戶端在發起請求前，先調用STS服務擷取STS Token。

  package main
  
  import (
      "os"
  
      "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  )
  
  func main() {
      // 使用SDK建立一個用戶端執行個體，該執行個體使用RAM角色ARN進行身分識別驗證
      // "<regionId>"：指定SDK用戶端要訪問的阿里雲地區ID
      // os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")：從環境變數中擷取RAM使用者AccessKey ID
      // os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")：從環境變數中擷取RAM使用者AccessKey Secret
      // "<roleArn>"：指定要扮演的RAM角色的ARN
      // "<roleSessionName>"：指定角色會話的名稱，用於標識和區分不同的會話
      client, err := sdk.NewClientWithRamRoleArn("<regionId>", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"), "<roleArn>", "<roleSessionName>")
  }
  

• 使用RamRoleArn（自訂許可權）

  如果您想限制產生的STS Token的許可權，您可以自訂權限原則來初始化用戶端。

  package main
  
  import (
  	"os"
  
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  )
  
  func main() {
  	// 使用SDK建立一個用戶端執行個體，該執行個體使用RAM角色ARN和自訂策略進行認證
  	// "<regionId>"：指定SDK用戶端要訪問的阿里雲地區ID
  	// os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")：從環境變數中擷取RAM使用者AccessKey ID
  	// os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")：從環境變數中擷取RAM使用者AccessKey Secret
  	// "<roleArn>"：指定要扮演的RAM角色的ARN
  	// "<roleSessionName>"：指定角色會話的名稱，用於標識和區分不同的會話
  	// "<policy>"：指定一個自訂的授權策略，用於限制角色會話的許可權
  	client, err := sdk.NewClientWithRamRoleArnAndPolicy("<regionId>", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
  		os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"), "<roleArn>", "<roleSessionName>", "<policy>")
  }

• 使用ECS執行個體RAM角色

  通過使用ECS執行個體綁定的RAM角色名稱，調用ECS的中繼資料服務（Metadata Server）擷取STS Token，完成用戶端初始化。

  package main
  
  import (
  	"os"
  
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  )
  
  func main() {
      // 通過ECS執行個體的RAM角色來擷取訪問憑證，從而建立一個阿里雲用戶端
      // 它適用於那些需要在ECS執行個體上運行，並且需要訪問其他阿里雲資源的程式
      // 參數"<regionId>"指定用戶端要訪問的阿里雲地區，"<roleName>"指定要使用的RAM角色名稱
      client, err := sdk.NewClientWithEcsRamRole("<regionId>", "<roleName>")
  }
  

• 使用OIDCRoleArn

  在Container ServiceKubernetes版中配置了Worker節點RAM角色後，您可以基於RRSA功能在叢集內實現Pod層級的應用關聯RAM角色功能。各個應用可以獨立扮演不同的RAM角色，並利用擷取的臨時憑證訪問雲資源，從而實現應用RAM許可權的最小化，並滿足無AccessKey訪問阿里雲OpenAPI的需求，以避免AccessKey泄露。

  阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC - OIDC角色SSO時擷取扮演角色的臨時身份憑證介面換取綁定角色的STS Token。詳情請參見通過RRSA配置ServiceAccount的RAM許可權實現Pod許可權隔離。

  package main
  
  import (
  	"os"
  
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
  )
  
  func main() {
  	config := sdk.NewConfig()
  
  	// 使用OIDCRoleArn初始化SDK用戶端
  	oidcProvider, _ := credentials.NewOIDCCredentialsProviderBuilder().
  		// OIDC供應商ARN，可以通過環境變數ALIBABA_CLOUD_OIDC_PROVIDER_ARN設定OIDCProviderARN
  		WithOIDCProviderARN(os.Getenv("ALIBABA_CLOUD_OIDC_PROVIDER_ARN")).
  		// OIDC Token檔案路徑，可以通過環境變數ALIBABA_CLOUD_OIDC_TOKEN_FILE設定OIDCTokenFilePath
  		WithOIDCTokenFilePath(os.Getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE")).
  		// RAM角色名稱ARN，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
  		WithRoleArn(os.Getenv("ALIBABA_CLOUD_ROLE_ARN")).
  		// 自訂角色會話名稱
  		WithRoleSessionName("<RoleSessionName>").
  		// 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
  		WithPolicy("<Policy>").
  		// 設定session到期時間
  		WithDurationSeconds(3600).
  		Build()
  
  	client, err := sdk.NewClientWithOptions("cn-beijing", config, oidcProvider)
  }
  

• 使用Bearer Token

  目前只有Cloud Call CenterCCC這款產品支援Bearer Token的憑據初始化方式。

  package main
  
  import (
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  )
  
  func main() {
      // 使用Bearer Token初始化SDK用戶端
      // regionId用於指定服務的地區，bearerToken是一種認證方式，用於授權訪問API
      client, err := sdk.NewClientWithBearerToken("<regionId>", "<bearerToken>")
  }

• 使用預設憑證鏈建立用戶端

  當您在初始化憑據用戶端不傳入任何參數時，將使用預設憑證提供者鏈建立用戶端，也可以自訂程式鏈。可通過自訂程式鏈代替預設程式鏈的尋找順序，也可以自行編寫閉包傳入提供者。

  package main
  
  import (
      "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
      "github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials/provider"
  )
  
  func main() {
      ProviderEnv := provider.NewEnvProvider()
      ProviderProfile := provider.NewProfileProvider()
      ProviderInstance := provider.NewInstanceCredentialsProvider()
  
      // 可以自訂憑據程式鏈代替預設憑證程式鏈，預設順序為ProviderEnv, ProviderProfile, ProviderInstance
      client, err := sdk.NewClientWithProvider("<regionId>", ProviderInstance, ProviderProfile, ProviderEnv)
  }

  預設憑證提供者鏈尋找可用的用戶端，尋找順序如下：

  程式首先會在環境變數裡尋找環境憑證，如果定義了 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 環境變數且不為空白，程式將使用它們建立預設用戶端。如果請求指定的用戶端不是預設用戶端，程式會在設定檔中載入和尋找用戶端。

  如果使用者主目錄存在預設檔案 ~/.alibabacloud/credentials （Windows 為 C:\Users\USER_NAME\.alibabacloud\credentials），程式會自動建立指定類型和名稱的用戶端。預設檔案可以不存在，但解析錯誤會拋出異常。 用戶端名稱不分大小寫，若用戶端同名，後者會覆蓋前者。也可以手動載入指定檔案： AlibabaCloud::load('/data/credentials', 'vfs://AlibabaCloud/credentials', ...); 不同的專案、工具之間可以共用這個設定檔，因為超出專案之外，也不會被意外提交到版本控制。Windows 上可以使用環境變數引用到主目錄 %UserProfile%。類 Unix 的系統可以使用環境變數 $HOME 或 ~ (tilde)。 可以通過定義 ALIBABA_CLOUD_CREDENTIALS_FILE 環境變數修改預設檔案的路徑。

  [default]                          # 預設用戶端
  type = access_key                  # 認證方式為 access_key
  access_key_id = foo                # Key
  access_key_secret = bar            # Secret
  
  [client1]                          # 命名為 `client1` 的用戶端
  type = ecs_ram_role                # 認證方式為 ecs_ram_role
  role_name = EcsRamRoleTest         # Role Name
  
  [client2]                          # 命名為 `client2` 的用戶端
  type = ram_role_arn                # 認證方式為 ram_role_arn
  access_key_id = foo
  access_key_secret = bar
  role_arn = role_arn
  role_session_name = session_name

  如果定義了環境變數 ALIBABA_CLOUD_ECS_METADATA 且不為空白，程式會將該環境變數的值作為角色名稱，請求 http://100.100.100.200/latest/meta-data/ram/security-credentials/ 擷取臨時安全憑證，並建立一個預設用戶端。

• 建立帶運行時參數的用戶端

  用戶端初始化還支援配置運行時參數，包含代理配置、逾時配置、重試機制配置、啟用非同步呼叫等。

  package main
  
  import (
  	"fmt"
  	"os"
  
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  	"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
  )
  
  func main() {
  	// 配置運行時參數
  	config := sdk.NewConfig()
  	// 使用RAM使用者AccessKeyID和AccessKeySecret
  	credential := credentials.NewAccessKeyCredential(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
  	client, err := sdk.NewClientWithOptions("<regionId>", config, credential)
  	if err != nil {
  		panic(err)
  	}

請求方式

使用CommonRequest進行調用

只需核心包即可發起調用，無需安裝各雲產品的SDK。通過CommonRequest構造請求參數，調用ProcessCommonRequest函數發起請求。更多詳情，請參見使用CommonRequest進行調用。

使用雲產品SDK提供的特化調用

需要安裝雲產品SDK，雲產品擷取方式：

1. 訪問SDK 中心。

2. 在頂部功能表列選擇雲產品，例如選擇Elastic Compute Service。

3. 選擇API 版本，如果雲產品有多個版本，請選擇推薦版本或者最新版本。

4. 選擇SDK 版本，選擇V1.0。

5. 在所有語言中選擇Go。

6. 在安裝方式中複製命令到終端執行。

go get github.com/aliyun/alibaba-cloud-sdk-go/services/ecs

調用樣本

package main

import (
	"fmt"

	"os"

	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
	"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
	ecs "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)

func main() {
	// 配置運行時參數
	config := sdk.NewConfig()
	// 使用RAM使用者AccessKeyID和AccessKeySecret
	credential := credentials.NewAccessKeyCredential(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
	client, err := ecs.NewClientWithOptions("cn-hangzhou", config, credential)
	if err != nil {
		panic(err)
	}
	// 使用雲產品SDK提供的Request對象
	request := ecs.CreateDescribeRegionsRequest()
	request.Scheme = "https" // 佈建要求協議
	// 請求參數
	request.InstanceChargeType = "PrePaid" // 執行個體的計費方式
	request.ResourceType = "instance" // 資源類型
	// 發起請求並擷取傳回值
	response, err := client.DescribeRegions(request)
	if err != nil {
		fmt.Print(err.Error())
	}
	fmt.Printf("response is %#v\n", response)
}