helper/api: client builder

[yamamoto-febc]

closes #784

環境変数やプロファイルからのAPIクライアント構築処理をUsacloudから切り出して移植する。

実装

互換性維持のため、既存のfunc api.NewCaller()のシグニチャを変更しないように実装する。

既存のfunc:

 // NewCaller 指定のオプションでsacloud.APICallerを構築して返す 
 func NewCaller(opts *CallerOptions) sacloud.APICaller

これに対し追加で以下のようなfuncを提供する。

環境変数/プロファイル対応:

// OptionsFromEnv 環境変数からCallerOptionsを組み立てて返す
func OptionsFromEnv() *CallerOptions

// OptionsFromProfile 指定のプロファイルからCallerOptionsを組み立てて返す
// プロファイル名に空文字が指定された場合はカレントプロファイルが利用される
func OptionsFromProfile(profileName string) (*CallerOptions, error)

複数のオプションのマージ:

// MergeOptions 指定のCallerOptionsの非ゼロ値フィールドをoのコピーにマージして返す
func MergeOptions(opts ...*CallerOptions) *CallerOptions

ユーティリティ:

// DefaultOption 環境変数、プロファイルからCallerOptionsを組み立てて返す
//
// プロファイルは環境変数`SAKURACLOUD_PROFILE`または`USACLOUD_PROFILE`でプロファイル名が指定されていればそちらを優先し、
// 未指定の場合は通常のプロファイル処理(~/.usacloud/currentファイルから読み込み)される。
// 同じ項目を複数箇所で指定していた場合、環境変数->プロファイルの順で上書きされたものが返される
func DefaultOption() (*CallerOptions, error)

// NewDefaultCaller デフォルトのオプションでsacloud.APICallerを構築して返す
func NewDefaultCaller() (sacloud.APICaller, error)

関連する環境変数

OptionsFromEnv()では以下の環境変数が参照される。

• AccessToken: SAKURACLOUD_ACCESS_TOKEN
• AccessTokenSecret: SAKURACLOUD_ACCESS_TOKEN_SECRET
• APIRootURL: SAKURACLOUD_API_ROOT_URL
• DefaultZone: SAKURACLOUD_DEFAULT_ZONE
• Zones: SAKURACLOUD_ZONES
• AcceptLanguage: SAKURACLOUD_ACCEPT_LANGUAGE
• HTTPRequestTimeout: SAKURACLOUD_API_REQUEST_TIMEOUT
• HTTPRequestRateLimit: SAKURACLOUD_API_REQUEST_RATE_LIMIT
• RetryMax: SAKURACLOUD_RETRY_MAX
• RetryWaitMax: SAKURACLOUD_RETRY_WAIT_MAX
• RetryWaitMin: SAKURACLOUD_RETRY_WAIT_MIN
• TraceAPI: SAKURACLOUD_TRACE
• TraceHTTP: SAKURACLOUD_TRACE
• FakeMode: SAKURACLOUD_FAKE_MODE
• FakeStorePath: SAKURACLOUD_FAKE_STORE_PATH

また、DefaultOption()ではSAKURACLOUD_PROFILEまたはUSACLOUD_PROFILEも利用可能。 ただしZonesについてはアプリケーション側で適切にハンドリングする必要がある。

注意事項

FakeModeやTraceなどのbool値でオプションを指定するケースでは、 非ゼロ値(true)の場合のみプロファイル/環境変数で上書き可能にする。 これにより、プロファイル/環境変数/直接指定いずれかでtrueになった場合はfalseに戻せない仕様となっている。