> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Client

> rest パッケージは Go SDK へのエントリーポイントです。API キーでクライアントを初期化し、アプリケーション、データベース、workspace、ユーザー、プラットフォームサービスといったすべてのリソースに単一のインターフェースを通してアクセスします。

## 要件

* **Go 1.24** 以降
* **外部依存関係ゼロ** — SDK は Go の標準ライブラリのみで構築されています
* 有効な API キー — [Square Cloud ダッシュボード](https://squarecloud.app/ja/dashboard) の **My Account → Regenerate API/CLI KEY** でリクエストできます

## インストール

```bash theme={null}
go get github.com/squarecloudofc/sdk-api-go/v2
```

モジュールは 2 つのパッケージを提供します:

| Package       | Import path                                           | Contents                                          |
| ------------- | ----------------------------------------------------- | ------------------------------------------------- |
| `rest`        | `github.com/squarecloudofc/sdk-api-go/v2/rest`        | HTTP クライアント、リソースインターフェース、リクエストオプション、エラー、SSE ストリーム |
| `squarecloud` | `github.com/squarecloudofc/sdk-api-go/v2/squarecloud` | すべてのリクエスト/レスポンス型と構造体                              |

## クライアントの初期化

```go theme={null}
package main

import (
	"fmt"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v2/rest"
)

func main() {
	client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
	defer client.Close()

	api := rest.New(client)

	user, err := api.SelfUser()
	if err != nil {
		panic(err)
	}
	fmt.Println(user.Name)
}
```

`rest.NewClient(token, opts...)` は基盤となる HTTP クライアントを構築し、`rest.New(client)` はそれをすべてのリソースを公開するインターフェースである `rest.Rest` にラップします。アイドル接続を解放するため、常に `defer client.Close()` を呼び出してください。

### クライアント設定（`ConfigOpt`）

`rest.NewClient` はトークンの後にオプションの `ConfigOpt` を受け取ります:

| Option                              | Default                          | Description                              |
| ----------------------------------- | -------------------------------- | ---------------------------------------- |
| `rest.WithLogger(*slog.Logger)`     | discarded                        | リクエスト/レスポンスのデバッグ用の構造化ロガー                 |
| `rest.WithHTTPClient(*http.Client)` | 30s timeout                      | カスタム `*http.Client`（プロキシ、トランスポート、タイムアウト） |
| `rest.WithURL(string)`              | `https://api.squarecloud.app/v2` | API のベース URL                             |
| `rest.WithUserAgent(string)`        | SDK default                      | カスタム `User-Agent` ヘッダー                   |

```go theme={null}
client := rest.NewClient(
	os.Getenv("SQUARECLOUD_API_KEY"),
	rest.WithLogger(slog.Default()),
	rest.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)
```

## モジュール

`rest.Rest` はリソースドメインごとに 1 つのインターフェースを埋め込んでおり、加えてこのページで解説するユーザーおよびサービスのメソッドを備えています:

| Interface      | Coverage                                        | Documentation                                   |
| -------------- | ----------------------------------------------- | ----------------------------------------------- |
| `Applications` | 管理、アップロード、ファイル、環境変数、snapshot、デプロイ、ネットワーク、リアルタイム | [アプリケーションの管理](/ja/sdks/go/managing_application) |
| `Databases`    | 作成、管理、認証情報、snapshot                             | [Databases](/ja/sdks/go/databases)              |
| `Workspaces`   | 作成、メンバー、共有アプリケーション                              | [workspace](/ja/sdks/go/workspaces)             |

## 認証済みユーザーの取得

`api.SelfUser()` は、アカウント詳細と現在のプランを含む `squarecloud.User` を返します。

```go theme={null}
user, err := api.SelfUser()
if err != nil {
	panic(err)
}

fmt.Println(user.ID)       // "abcdef0123456789abcdef01"
fmt.Println(user.Name)     // "John Doe"
fmt.Println(user.Email)    // "john@example.com"
fmt.Println(user.Locale)   // "en-US"
fmt.Println(user.Plan.Name)             // 例: "standard"
fmt.Println(user.Plan.Duration)         // プランの期間、例: "monthly"
fmt.Println(user.Plan.Memory.Limit)     // MB
fmt.Println(user.Plan.Memory.Available) // MB
fmt.Println(user.Plan.Memory.Used)      // MB
fmt.Println(user.CreatedAt)
```

| Field       | Type                   | Description                                            |
| ----------- | ---------------------- | ------------------------------------------------------ |
| `ID`        | `string`               | ユーザー ID（24 文字の 16 進数）                                  |
| `Name`      | `string`               | 表示名                                                    |
| `Email`     | `string`               | アカウントのメールアドレス                                          |
| `Locale`    | `string`               | 優先ロケール、例: `"en-US"`                                    |
| `Plan`      | `squarecloud.UserPlan` | `Name`、`Memory{Limit, Available, Used}`（MB）、`Duration` |
| `CreatedAt` | `string`               | アカウント作成日                                               |

## アプリケーションとデータベースの一覧取得

`api.GetApplications()` と `api.GetDatabases()` は `/users/me` エンドポイントを通して所有するすべてのリソースを一覧取得し、コンパクトな `squarecloud.UserApplication` / `squarecloud.UserDatabase` ディスクリプタを返します:

```go theme={null}
apps, err := api.GetApplications()
if err != nil {
	panic(err)
}
for _, app := range apps {
	fmt.Printf("%s (%s) — %dMB\n", app.Name, app.ID, app.RAM)
}

dbs, err := api.GetDatabases()
if err != nil {
	panic(err)
}
for _, db := range dbs {
	fmt.Printf("%s (%s)\n", db.Name, db.ID)
}
```

単一リソースの完全なレコードを取得するには `GetApplication` / `GetDatabase` を使用します — [アプリケーションの管理](/ja/sdks/go/managing_application) と [Databases](/ja/sdks/go/databases) を参照してください。

## snapshot 履歴の一覧取得（アカウント全体）

`api.UserSnapshots(scope)` は、指定したドメインについて所有するすべての snapshot を返します:

```go theme={null}
appSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeApplications)
if err != nil {
	panic(err)
}

dbSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeDatabases)
if err != nil {
	panic(err)
}
```

snapshot ペイロードの詳細については [Snapshots](/ja/sdks/go/snapshots) を参照してください。

## プラットフォームステータス

`api.ServiceStatus()` は、集約されたプラットフォームの健全性（公開ステータスページに表示されるものと同じデータ）を公開します。

```go theme={null}
status, err := api.ServiceStatus()
if err != nil {
	panic(err)
}

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // 人間が読める要約
```

<Note>
  ほとんどの v2 エンドポイントとは異なり、このルートはペイロードを標準の `{ status, code, response }` エンベロープで **ラップしません** — `{ status, message }` を直接返します。
</Note>

## リクエストオプション

すべてのメソッドは、末尾に `...rest.RequestOpt` を受け取り、個々のリクエストをカスタマイズできます:

| Option                            | Description                              |
| --------------------------------- | ---------------------------------------- |
| `rest.WithContext(ctx)`           | キャンセルやデッドラインのために `context.Context` を付与する |
| `rest.WithQueryParam(key, value)` | クエリパラメータを追加する                            |
| `rest.WithHeader(key, value)`     | リクエストヘッダーを設定する                           |
| `rest.WithToken(token)`           | このリクエストに限り認証トークンを上書きする                   |

```go theme={null}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

user, err := api.SelfUser(rest.WithContext(ctx))
if err != nil {
	panic(err)
}
```

## エラーハンドリング

2xx 以外のレスポンスはすべて、`StatusCode`、`Code`、`Message` を公開する `*rest.APIError` として返されます。慣用的な `errors.As` でアンラップしてください:

```go theme={null}
app, err := api.GetApplication("invalid-id")
if err != nil {
	var apiErr *rest.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode) // 例: 404
		fmt.Println(apiErr.Code)       // 例: "APP_NOT_FOUND"
		fmt.Println(apiErr.Message)
	}
	return
}
```

よくあるチェックを簡単にする 2 つのヘルパーがあります:

* `rest.ErrorCode(err) string` — API のエラーコードを返します（エラーが `*rest.APIError` でない場合は `""`）
* `rest.IsRateLimit(err) bool` — エラーがレートリミット系のコード（`KEEP_CALM`、`RATE_LIMIT`、`RATE_LIMIT_EXCEEDED`、`RATELIMIT`、`DELAY_NOW`）のいずれかであるかを報告します

```go theme={null}
if err != nil {
	if rest.IsRateLimit(err) {
		time.Sleep(5 * time.Second)
		// リトライする...
	}

	switch rest.ErrorCode(err) {
	case "APP_NOT_FOUND":
		fmt.Println("application does not exist")
	case "ACCESS_DENIED":
		fmt.Println("invalid API key")
	}
}
```

エラーコードは `@squarecloud/api-types` で使われているものと同一です — [JS SDK リファレンスの完全なコード表](/ja/sdks/js/client) を参照してください。