client

README

api-client-go

さくらのクラウド向けAPI/HTTPクライアントライブラリ

License

sacloud/api-client-go Copyright (C) 2022-2025 The sacloud/api-client-go Authors.

This project is published under Apache 2.0 License.

Documentation

Index

• Constants
• Variables
• type Client
  • func NewClient(apiUrl string, params ...ClientParam) (*Client, error)
  • func NewClientWithParams(params *ClientParams) (*Client, error)
  • func (c *Client) NewHttpRequestDoer() HttpRequestDoer
  • func (c *Client) Options() *Options
  • func (c *Client) ServerURL() string
• type ClientParam
  • func WithApiKeys(accessToken string, secretToken string) ClientParam
  • func WithDisableEnv(disable bool) ClientParam
  • func WithDisableProfile(disable bool) ClientParam
  • func WithOptions(options *Options) ClientParam
  • func WithProfile(profile string) ClientParam
  • func WithUserAgent(ua string) ClientParam
• type ClientParams
• type Factory
  • func NewFactory(options ...*Options) *Factory
  • func (f *Factory) NewHttpRequestDoer() HttpRequestDoer
  • func (f *Factory) Options() *Options
• type HttpRequestDoer
• type Options
  • func DefaultOption() (*Options, error)
  • func DefaultOptionWithProfile(profileName string) (*Options, error)
  • func MergeOptions(opts ...*Options) *Options
  • func OptionsFromEnv() *Options
  • func OptionsFromProfile(profileName string) (*Options, error)
  • func (o *Options) ProfileConfigValue() *profile.ConfigValue

Constants

const Version = "0.3.0"

Version バージョン

Variables

var DefaultUserAgent = fmt.Sprintf(
	"api-client-go/v%s (%s/%s; +https://github.com/sacloud/api-client-go) %s",
	Version,
	runtime.GOOS,
	runtime.GOARCH,
	sacloudhttp.DefaultUserAgent,
)

DefaultUserAgent デフォルトのユーザーエージェント

Types

type Client

type Client struct {
	// APIRootURL APIのリクエスト先URLプレフィックス
	APIRootURL string
	// contains filtered or unexported fields
}

Client APIクライアント

func NewClient

func NewClient(apiUrl string, params ...ClientParam) (*Client, error)

Clientを初期化してから返す。WithXXXを使って特定の設定を初期化可能

func NewClientWithParams

func NewClientWithParams(params *ClientParams) (*Client, error)

設定したいパラメータが多い場合は直接ClientParamsを初期化して渡す

func (*Client) NewHttpRequestDoer

func (c *Client) NewHttpRequestDoer() HttpRequestDoer

func (*Client) Options

func (c *Client) Options() *Options

func (*Client) ServerURL

func (c *Client) ServerURL() string

type ClientParam

type ClientParam func(*ClientParams)

func WithApiKeys

func WithApiKeys(accessToken string, secretToken string) ClientParam

func WithDisableEnv

func WithDisableEnv(disable bool) ClientParam

func WithDisableProfile

func WithDisableProfile(disable bool) ClientParam

func WithOptions

func WithOptions(options *Options) ClientParam

func WithProfile

func WithProfile(profile string) ClientParam

func WithUserAgent

func WithUserAgent(ua string) ClientParam

type ClientParams

type ClientParams struct {
	// APIのリクエスト先URLプレフィックス
	APIRootURL string
	// APIキー群
	Token  string
	Secret string
	// クライアントから送られるユーザエージェント
	UserAgent string
	// Options HTTPクライアント関連オプション
	Options *Options
	// Profile usacloud互換プロファイル名
	Profile string
	// usacloud互換プロファイルからの設定読み取りを無効化
	DisableProfile bool
	// 環境変数からの設定読み取りを無効化
	DisableEnv bool
}

SDKライブラリから設定するパラメータ。WithXXXを使って特定のパラメータだけ設定可能

type Factory

type Factory struct {
	// contains filtered or unexported fields
}

Factory client.HttpRequestDoerを作成して返すファクトリー

func NewFactory

func NewFactory(options ...*Options) *Factory

NewFactory 指定のオプションでFactoryを生成する

func (*Factory) NewHttpRequestDoer

func (f *Factory) NewHttpRequestDoer() HttpRequestDoer

NewHttpRequestDoer オプションを反映したsacloud向けのHTTPクライアントを生成して返す

func (*Factory) Options

func (f *Factory) Options() *Options

Options Doerの生成で用いるOptionsを返す

type HttpRequestDoer

type HttpRequestDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HttpRequestDoer API/HTTPクライアントインターフェース

type Options

type Options struct {
	// AccessToken APIキー:トークン
	AccessToken string
	// AccessTokenSecret APIキー:シークレット
	AccessTokenSecret string

	// AcceptLanguage APIリクエスト時のAccept-Languageヘッダーの値
	AcceptLanguage string

	// Gzip APIリクエストでgzipを有効にするかのフラグ
	Gzip bool

	// HttpClient APIリクエストで使用されるHTTPクライアント
	//
	// 省略した場合はhttp.DefaultClientが使用される
	HttpClient *http.Client

	// HttpRequestTimeout HTTPリクエストのタイムアウト秒数
	HttpRequestTimeout int
	// HttpRequestRateLimit 1秒あたりの上限リクエスト数
	HttpRequestRateLimit int

	// RetryMax リトライ上限回数
	RetryMax int

	// RetryWaitMax リトライ待ち秒数(最大)
	RetryWaitMax int
	// RetryWaitMin リトライ待ち秒数(最小)
	RetryWaitMin int

	// UserAgent ユーザーエージェント
	UserAgent string

	// Trace HTTPリクエスト/レスポンスのトレースログ(ダンプ)出力
	Trace bool
	// TraceOnlyError HTTPリクエスト/レスポンスのトレースログ(ダンプ)出力で非200番台のレスポンス時のみ出力する
	TraceOnlyError bool

	// RequestCustomizers リクエスト前に*http.Requestのカスタマイズを行うためのfunc
	RequestCustomizers []sacloudhttp.RequestCustomizer

	// CheckRetryFunc リトライすべきか判定するためのfunc
	//
	// CheckRetryStatusCodesより優先される
	CheckRetryFunc func(ctx context.Context, resp *http.Response, err error) (bool, error)

	// CheckRetryStatusCodes リトライすべきステータスコード
	//
	// CheckRetryFuncが指定されていない、かつこの値が指定されている場合、指定のステータスコードを持つレスポンスを受け取ったらリトライする
	CheckRetryStatusCodes []int
	// contains filtered or unexported fields
}

Options sacloudhttp.Clientを作成する際のオプション

func DefaultOption

func DefaultOption() (*Options, error)

DefaultOption 環境変数、プロファイルからCallerOptionsを組み立てて返す

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

func DefaultOptionWithProfile

func DefaultOptionWithProfile(profileName string) (*Options, error)

DefaultOptionWithProfile 環境変数、プロファイルからCallerOptionsを組み立てて返す

プロファイルは引数を優先し、空の場合は環境変数`SAKURACLOUD_PROFILE`または`USACLOUD_PROFILE`が利用され、 それも空の場合は通常のプロファイル処理(~/.usacloud/currentファイルから読み込み)される。 同じ項目を複数箇所で指定していた場合、環境変数->プロファイルの順で上書きされたものが返される

func MergeOptions

func MergeOptions(opts ...*Options) *Options

MergeOptions 指定のCallerOptionsの非ゼロ値フィールドをoのコピーにマージして返す

func OptionsFromEnv

func OptionsFromEnv() *Options

OptionsFromEnv 環境変数からCallerOptionsを組み立てて返す

func OptionsFromProfile

func OptionsFromProfile(profileName string) (*Options, error)

OptionsFromProfile 指定のプロファイルからCallerOptionsを組み立てて返す

プロファイルは引数を優先し、空の場合は環境変数`SAKURACLOUD_PROFILE`または`USACLOUD_PROFILE`が利用され、 それも空の場合は通常のプロファイル処理(~/.usacloud/currentファイルから読み込み)される。

func (*Options) ProfileConfigValue

func (o *Options) ProfileConfigValue() *profile.ConfigValue

ProfileConfigValue プロファイルから読み込んだprofile.ConfigValueを返す