WebAPIの基本構成

こんにちは、くのへです！
先日、エクセルVBAで生成AIのGeminiにWebAPIアクセスし、癒しのお姉さんと対話できるエクセルを作ったところ、結構反響があったので、その作り方を解説したいと思います。

VBAでWebAPIを使い、Geminiに癒しのお姉さんになってもらい、返信してもらうツールを作ってしまったｗ

我ながらバカすぎるｗ

しかし、これを使えば、生成AIで色々できるぞ、、、 pic.twitter.com/ngJIFo6JQJ
— くのへ＠くのへ塾やってます (@MasazaneKunohe) October 31, 2024

今回はその第２段として、そもそも論である「WebAPIの基本構成」をザッと解説します。

Web APIの基本構成について理解しよう

Web APIを活用すると、異なるアプリケーションやシステム間でデータをやり取りすることができます。
例えば、あるサービスから情報を取得したり、Google Apps Script (GAS) で自動処理したり、Pythonでデータ分析に活用したりと、さまざまな場面で利用が可能です。
WebAPIのを使う時のリクエスト文章の構成を理解しておくと、どのプログラミング言語を使うにしても、コードの理解が進むと思います。

リクエストの基本構成

Web APIにアクセスするリクエストは、主に「URL」と「パラメータ（Param）」で構成されています。この構成要素を押さえておくことで、Web APIと効率的にやりとりすることができます。

URL（エンドポイント）
エンドポイントとは、APIサービスを提供しているサーバーが用意するURLのことです。エンドポイントは、特定のデータや機能にアクセスするための「場所」を示します。「入口」と読み替えても良いと思います。
例えば、https://api.example.com/users のようなURLがエンドポイントです。アクセスしたい情報や機能によってエンドポイントは異なります。
（しかし、入口なのに「エンド」という名前が付いているのは、分かりにくいと思うんですよね。。。）

なお、リクエストするときは、URLの後ろにパラメータを書いてリクエストすることがあります。
このパラメータのことを「クエリパラメータ」といいます。
エンドポイントURLの最後に?を書き、その後にa=XXXX&b=YYYYのようにパラメータを&で繋げて記載すると、サーバ側に条件などの情報を伝えることが出来ます。
Param（パラメータ）←Optionと称されることもあります
リクエストのパラメータには、Method,Headers,Payloadの3つの要素が基本構成として含まれます。
- Method
  リクエストには、特定の情報を取得したり、サーバにデータを送信して処理してもらうなど、さまざまな種類があります。主要なリクエストには「GETリクエスト」と「POSTリクエスト」があります。
  - GETリクエスト：サーバーから情報を取得するためのリクエストです。例えば、ユーザー情報や天気データを取得する際に使います。GETリクエストは通常、エンドポイントのURLにパラメータを付加して必要な情報を指定します（クエリパラメータという）。
    リクエスト自体がシンプルであり、サーバー側のデータを変更しないため、安全に使用できるとされています。
  - POSTリクエスト：サーバーにデータを送信し、データの作成や変更、または複雑な処理を行ってもらうためのリクエストです。たとえば、新しいユーザーを登録する場合や、フォームから送信されたデータを処理する場合に使われます。
    POSTリクエストでは、データをURLではなくリクエストの「ボディ（Payload）」に含めて送信します。
  - 他のリクエスト：GETやPOSTの他にも、PUT（データの更新）やDELETE（データの削除）といったメソッドもあります。目的に応じて適切なメソッドを選択し、リクエストを送信します。
- Headers
  ヘッダーにはリクエストに関する追加情報を含めます。一般的なヘッダーには、次のようなものがあります：
  - Content-Type：送信するデータの形式を指定します（例：application/json）。この設定により、サーバー側でデータの読み取りが正しく行われます。
  - Authorization：APIキーやトークンなどの認証情報を含め、アクセスを許可されたユーザーとしてリクエストを送信できるようにします。
- Payload
  リクエストボディとも呼ばれ、リクエストに含まれるデータそのものです。特にPOSTやPUTリクエストで使われ、サーバー側に渡すデータ（例えばユーザー情報など）をJSON形式やXML形式で含めます。
  GETリクエストの場合は、通常Payloadを使わず、必要な情報はURLのクエリパラメータに含めます。

これがWebAPIを使う時の基本構成になります。例えばGASだとこのような感じでコードを記載します。

function sendPostRequest() {
  // APIのエンドポイントURL
  const url = "https://api.example.com/endpoint";

  // 送信するデータ（Payload）
  const payload = {
    "name": "Taro Yamada",
    "email": "Taro_Yamada@example.com"
  };

  // リクエストオプションの設定
  const param = {
    method: "post",
    headers: {
      "Content-Type": "application/json",       // Content-Typeをheadersの中に指定
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"  // 認証トークン
    },
    payload: JSON.stringify(payload)  // JSON形式に変換
  };

  try {
    // POSTリクエストの送信
    const response = UrlFetchApp.fetch(url, param);

    // レスポンスをJSONとして取得
    const jsonResponse = JSON.parse(response.getContentText());
    Logger.log(jsonResponse);  // ログに出力
  } catch (error) {
    Logger.log("Error: " + error.message);  // エラーのログ出力
  }
}

WebAPIを学習する方は、まず、Paramの構成を丸暗記したらいいと思います。
　メソッド、ヘッダー、ペイロード、、、ヘッダーの中はContent-TypeとAuthorization、、、
　メソッド、ヘッダー、ペイロード、、、ヘッダーの中はContent-TypeとAuthorization、、、
　メソッド、ヘッダー、ペイロード、、、ヘッダーの中はContent-TypeとAuthorization、、、
とブツブツしゃべっていればそのうち覚えられますよ！