[Goのはじめ方] Part32: JSON APIクライアントとデータ整形

多くのWebサービスやアプリケーションは、他のシステムとデータを交換するためにJSON APIを提供しています。 例えば、天気情報、ニュース記事、商品情報などを取得する際に利用されます。

このセクションでは、Goの標準パッケージを使ってJSON APIにリクエストを送り、取得したデータをGoのプログラムで扱いやすい形（構造体など）に変換（整形）する方法を学びます。 これにより、外部サービスと連携するアプリケーションを開発できるようになります。

まず、外部APIからデータを取得するための基本的な方法として、HTTPのGETリクエストを送信します。Goではnet/httpパッケージのGet関数が便利です。

package main
import ( "fmt" "io" "log" "net/http"
)
func main() { // 例として、JSONPlaceholderというダミーAPIのエンドポイントを使用します apiURL := "https://jsonplaceholder.typicode.com/todos/1" // HTTP GETリクエストを送信 resp, err := http.Get(apiURL) if err != nil { log.Fatalf("HTTP GETリクエストに失敗しました: %v", err) } // 関数終了時にレスポンスボディを必ず閉じる defer resp.Body.Close() // ステータスコードをチェック (200 OK以外はエラーとして扱う例) if resp.StatusCode != http.StatusOK { log.Fatalf("エラーレスポンスを受け取りました: %s", resp.Status) } // レスポンスボディを読み込む body, err := io.ReadAll(resp.Body) if err != nil { log.Fatalf("レスポンスボディの読み込みに失敗しました: %v", err) } // 取得したJSONデータを文字列として出力 fmt.Println("取得したJSONデータ:") fmt.Println(string(body))
}

このコードは、指定されたURLにGETリクエストを送り、レスポンスボディの内容を読み取ってコンソールに出力します。 エラーハンドリングも重要です。リクエスト自体のエラー、ステータスコードのエラー、ボディ読み込みエラーをチェックしています。 defer resp.Body.Close() はリソースリークを防ぐために不可欠です。

APIから取得したJSONデータ（バイト列）をGoのプログラムで扱いやすくするために、Goの構造体（struct）に変換します。この処理をデコードまたはアンマーシャリングと呼びます。encoding/jsonパッケージのUnmarshal関数を使います。

まず、受け取るJSONの構造に対応するGoの構造体を定義します。

// 受け取るJSONデータに対応する構造体
type Todo struct { UserID int `json:"userId"` // JSONのキー名とGoのフィールド名をマッピング ID int `json:"id"` Title string `json:"title"` Completed bool `json:"completed"`
}

構造体のフィールド名の後ろにある `json:"..."` は構造体タグと呼ばれ、JSONデータ内のキー名とGoの構造体のフィールド名を対応付けます。これにより、JSONのキー名が小文字始まりでも、Goの公開フィールド（大文字始まり）に正しくマッピングできます。

次に、取得したJSONデータ（body変数）をこのTodo構造体にデコードします。

package main
import ( "encoding/json" // jsonパッケージをインポート "fmt" "io" "log" "net/http"
)
// JSONデータに対応する構造体
type Todo struct { UserID int `json:"userId"` ID int `json:"id"` Title string `json:"title"` Completed bool `json:"completed"`
}
func main() { apiURL := "https://jsonplaceholder.typicode.com/todos/1" resp, err := http.Get(apiURL) if err != nil { log.Fatalf("HTTP GETリクエストに失敗しました: %v", err) } defer resp.Body.Close() if resp.StatusCode != http.StatusOK { log.Fatalf("エラーレスポンスを受け取りました: %s", resp.Status) } body, err := io.ReadAll(resp.Body) if err != nil { log.Fatalf("レスポンスボディの読み込みに失敗しました: %v", err) } // JSONデータをTodo構造体にデコード（アンマーシャリング） var todo Todo err = json.Unmarshal(body, &todo) // 第2引数にはデコード結果を格納する構造体のアドレス（ポインタ）を渡す if err != nil { log.Fatalf("JSONのデコードに失敗しました: %v", err) } // デコード結果の構造体の内容を出力 fmt.Println("デコードされたデータ:") fmt.Printf("UserID: %d\n", todo.UserID) fmt.Printf("ID: %d\n", todo.ID) fmt.Printf("Title: %s\n", todo.Title) fmt.Printf("Completed: %t\n", todo.Completed)
}

json.Unmarshal関数は、第1引数にJSONデータ（バイトスライス）、第2引数にデコード結果を格納する変数のポインタを取ります。エラーが発生しなければ、todo変数にJSONデータの内容が格納されます。

構造体にデコードされたデータは、Goのプログラム内で自由に扱うことができます。必要な情報だけを取り出したり、他のデータと組み合わせたり、計算したりすることが可能です。

// ... (前のコードの続き) ... // デコードされたデータを使って情報を整形して表示 fmt.Println("\n整形された情報:") status := "未完了" if todo.Completed { status = "完了" } fmt.Printf("タスク「%s」(ID: %d) は%sです。\n", todo.Title, todo.ID, status) // 例えば、特定の条件を満たすかチェック if !todo.Completed { fmt.Println("このタスクはまだ完了していません。") }

このように、デコード後のデータをGoの変数として扱えるため、条件分岐（if文）や文字列フォーマット（fmt.Printf）などを活用して、目的に合わせたデータ整形や処理を行うことができます。

データを取得するだけでなく、APIにデータを送信する場合もあります。よく使われるのがHTTP POSTリクエストでJSONデータを送信する方法です。Goの構造体をJSONデータ（バイト列）に変換する処理をエンコードまたはマーシャリングと呼び、encoding/jsonパッケージのMarshal関数を使います。

package main
import ( "bytes" // バイト列を扱うために必要 "encoding/json" "fmt" "io" "log" "net/http"
)
// 送信するデータ構造
type NewTodo struct { UserID int `json:"userId"` Title string `json:"title"` Completed bool `json:"completed"`
}
func main() { apiURL := "https://jsonplaceholder.typicode.com/todos" // POST先のエンドポイント // 送信するデータを作成 newTodo := NewTodo{ UserID: 1, Title: "GoでPOSTリクエストの練習", Completed: false, } // Goの構造体をJSONデータ（バイト列）にエンコード（マーシャリング） jsonData, err := json.Marshal(newTodo) if err != nil { log.Fatalf("JSONへのエンコードに失敗しました: %v", err) } fmt.Printf("送信するJSONデータ: %s\n", string(jsonData)) // HTTP POSTリクエストを作成 req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(jsonData)) if err != nil { log.Fatalf("リクエストの作成に失敗しました: %v", err) } // Content-Typeヘッダーを設定 (JSONデータを送信することを示す) req.Header.Set("Content-Type", "application/json; charset=UTF-8") // HTTPクライアントを作成してリクエストを送信 client := &http.Client{} resp, err := client.Do(req) if err != nil { log.Fatalf("POSTリクエストの送信に失敗しました: %v", err) } defer resp.Body.Close() // レスポンスを確認 fmt.Printf("レスポンスステータス: %s\n", resp.Status) body, _ := io.ReadAll(resp.Body) fmt.Printf("レスポンスボディ: %s\n", string(body)) // 作成されたリソースの情報などが返ってくることが多い
}

このコードでは、まず送信したいデータをNewTodo構造体で定義し、json.MarshalでJSONバイト列に変換します。次にhttp.NewRequestでPOSTリクエストオブジェクトを作成し、bytes.NewBufferを使ってJSONデータをリクエストボディに設定します。 重要なのは、Content-Typeヘッダーをapplication/jsonに設定することです。これにより、サーバーは送信されたデータがJSON形式であることを認識できます。 最後に、http.Clientを使ってリクエストを送信し、レスポンスを受け取ります。

APIクライアントを実装する際には、様々なエラーが発生する可能性を考慮する必要があります。

• ネットワークエラー: サーバーに接続できない、タイムアウトするなど。http.Getやclient.Doがエラーを返します。
• HTTPステータスコードエラー: サーバーがエラーを示すステータスコード (4xx, 5xx) を返す場合。resp.StatusCodeをチェックして適切に対応します (例: 404 Not Found, 500 Internal Server Error)。
• JSONデコード/エンコードエラー: 受信したデータが期待するJSON形式でない、または構造体とのマッピングに失敗する場合。json.Unmarshalやjson.Marshalがエラーを返します。
• API固有のエラー: APIによっては、成功時 (2xx) でもレスポンスボディ内にエラー情報を含める場合があります。APIのドキュメントを確認し、レスポンス内容に基づいたエラー処理が必要です。

堅牢なアプリケーションを開発するためには、これらのエラーケースを網羅的にハンドリングすることが重要です。エラーが発生した場合にログを出力したり、処理をリトライしたり、ユーザーに分かりやすいメッセージを表示したりするなどの対応を検討しましょう。

効果的なエラーハンドリング戦略については、例えばJSON:API仕様のエラー形式やGoogle JSON Style Guideのエラー形式などを参考に、一貫性のあるエラーレスポンス設計を検討するのも良いでしょう。

このセクションでは、Goの標準パッケージnet/httpとencoding/jsonを使って、JSON APIクライアントを実装し、データを整形する方法を学びました。

• http.Getやhttp.Post (またはhttp.NewRequestとclient.Do) でAPIにリクエストを送信できる。
• io.ReadAllでレスポンスボディを読み取る。
• json.UnmarshalでJSONデータをGoの構造体にデコードできる。構造体タグ (`json:"..."`) がマッピングに役立つ。
• json.MarshalでGoの構造体をJSONデータにエンコードできる。
• 適切なエラーハンドリング (ネットワーク、HTTPステータス、JSON処理、API固有) が重要。

これらの知識を使えば、様々な外部APIと連携するGoアプリケーションを作成できます。ぜひ実際のAPIを叩いて試してみてください！