WebAPIの使い方(POSTリクエスト)

POSTとは

POSTとは、「リソース（情報）を更新・作成する」ためのHTTPメソッドです。GETはパラメーターをURL中に含めていましたが、POSTはリクエストボディーにパラメーターを配置するため、パラメーターの長さに上限がないという特徴があります。

Yahoo!デベロッパーネットワークで提供するWeb APIには、POSTを使ってリクエストしてもGET相当の結果が返ってくるものがあります。 これは長いパラメーターを受け付けるための仕様です。

GETとPOSTを区別するかしないかはWeb APIごとに対応状況が異なりますので、各Web APIのドキュメントもご覧ください。

例として、ルビ振りAPIを使って「明鏡止水」の読み方を調べてみます。

telnetコマンドを使った例

telnetコマンドを使うと具体的な通信の中身を見ることができます。まずtelnetを起動します。

telnet jlp.yahooapis.jp 80

次に、リクエストを送ります。以下のテキストを端末にコピーアンドペーストするとレスポンスが返ってくるはずです。 ただし、「<あなたのアプリケーションID>」の部分は登録したアプリケーションIDに置き換えてください。

POST /FuriganaService/V1/furigana HTTP/1.1
Host: jlp.yahooapis.jp
User-Agent: Yahoo AppID: <あなたのアプリケーションID>
Content-Type: application/x-www-form-urlencoded
Content-Length: 45

sentence=%E6%98%8E%E9%8F%A1%E6%AD%A2%E6%B0%B4

Content-TypeやContent-Lengthが正しく指定されていないと、うまくリクエストが認識できません。

（レスポンスの例）
HTTP/1.1 200 OK
Date: Mon, 06 Feb 2012 00:00:00 GMT
Vary: Accept-Encoding
Content-Type: text/xml; charset="UTF-8"
Cache-Control: private
Connection: close
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet xmlns="urn:yahoo:jp:jlp:FuriganaService"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:yahoo:jp:jlp:FuriganaService http://jlp.yahooapis.jp/FuriganaService/V1/furigana.xsd">
<Result>
  <WordList>
    <Word>
      <Surface>明鏡止水</Surface>
      <Furigana>めいきょうしすい</Furigana>
      <Roman>meikyousisui</Roman>
    </Word>
  </WordList>
</Result>
</ResultSet>

実際はこのレスポンス結果をプログラムで解析し、サービスを利用していくことになります。

アプリケーションIDについて

Yahoo!デベロッパーネットワークで公開されているWeb APIを使う際には、アプリケーションIDが必要です。
登録したアプリケーションIDは、以下のいずれかの方法でリクエストに付与してください。
Yahoo! ID連携に対応したWeb APIについては、アプリケーションIDの代わりにYahoo! ID連携のフローで取得したアクセストークンが必要となります。
リクエスト方法の詳細はYahoo! ID連携のAPIアクセス実装方法をご覧ください。

User-Agent方式

User-Agentヘッダーの末尾に以下の形式で埋め込むことでアプリケーションIDを渡します。

User-Agent: <元のUser-Agent文字列>; Yahoo AppID: <あなたのアプリケーションID>

User-Agentがもともと空の場合は、

User-Agent: Yahoo AppID: <あなたのアプリケーションID>

となります。

URLパラメーター方式

GETリクエストと同じようにURLパラメーターとしてアプリケーションIDを渡すこともできます。 こちらの方が手軽で、ヘッダーを操作できない場合でも使うことができます。

appid=<あなたのアプリケーションID>

Web APIへのパラメーターの渡し方

Web APIは渡されたパラメーターによって出力が変わります。

特に明示されていないWeb APIは、application/x-www-form-urlencoded形式のパラメーターをサポートしています。

application/x-www-form-urlencodedはGETでのクエリーストリングとほぼ同じ形式です。クエリーストリングは以下の順序で作ります。

  1. Web APIドキュメントをもとに、必要なリクエストパラメーターと、渡したい文字列を書き出します。
    sentence明鏡止水
  2. パラメーター名と、パラメーターの値をそれぞれパーセントエンコーディング形式に変換します。
    sentence%E6%98%8E%E9%8F%A1%E6%AD%A2%E6%B0%B4
  3. 変換結果を「=」で連結します。このときに使う「=」は、エンコードしてはいけません。
    sentence=%E6%98%8E%E9%8F%A1%E6%AD%A2%E6%B0%B4
  4. 各パラメーターについて1～3を行い、最後に「&」で連結します。この「&」もエンコードしてはいけません。
    appid=YOUR_APPID&sentence=%E6%98%8E%E9%8F%A1%E6%AD%A2%E6%B0%B4

たとえばPHPの場合、http_build_query（外部リンク）という標準関数で簡単にクエリーストリングを作ることができます。POSTの場合、作成したクエリーストリングをそのままリクエストボディーとして渡します。

application/x-www-form-urlencoded以外の形式をサポートするケースもありますので、各Web APIのドキュメントもお読みください。

パラメーターの文字コードについて

Web APIのドキュメントに記載がない場合、UTF-8をサポートしています。日本語の文字列などはUTF-8で渡すようにしてください。

レスポンスの解析

Web APIのレスポンスはXMLやPHPSerialize、JSONといったテキスト形式になっています。対応している形式はWeb APIによって異なります。 いずれも汎用的なデータフォーマットですので、お好きなツール・ライブラリを使って解析してください。

PHP + cURL + SimpleXML によるサンプル

以上がWeb APIを使用する際の基本になります。
これまで述べてきた内容を、Web APIをリクエストするたびに作っていると大変ですので、多くのプログラミング言語ではもう少し簡便にしたライブラリを用意しています。

たとえばPHPではcURL（外部リンク）があります。libcurlをPHPから使えるようにしたもので、高速で高機能なため、よく使われているライブラリです。

これを用いてWeb APIにリクエストし、SimpleXML（外部リンク）を使ってレスポンスのXMLを解析し、表示するサンプルを以下に示します。

<?php
/**
* ルビ振りAPIへのリクエストサンプル（POST）
*
*/
$api = 'http://jlp.yahooapis.jp/FuriganaService/V1/furigana';
$appid = '<あなたのアプリケーションID>';
$params = array(
  'sentence' => '明鏡止水'
);

$ch = curl_init($api);
curl_setopt_array($ch, array(
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_USERAGENT      => "Yahoo AppID: $appid",
  CURLOPT_POSTFIELDS     => http_build_query($params),
));

$result = curl_exec($ch);
curl_close($ch);
?>
<pre>
<?php echo htmlspecialchars(
           print_r(new SimpleXMLElement($result), true)
         ) ?>
</pre>

cURLを利用する場合、自動的にContent-TypeやContent-Lengthが設定されます。

出力は以下のようになります。

<pre>
SimpleXMLElement Object
(
  [Result] => SimpleXMLElement Object
      (
          [WordList] => SimpleXMLElement Object
              (
                  [Word] => SimpleXMLElement Object
                      (
                          [Surface] => 明鏡止水
                          [Furigana] => めいきょうしすい
                          [Roman] => meikyousisui
                      )
              )
      )
)
</pre>

今回は説明のための必要最小限のコードになっています。たとえばリクエストに失敗したとき、リトライや復帰処理が行われません。 高度なサンプルはサンプルコード集よりダウンロードできますので、そちらもお役立てください。

アプリケーションの管理

開発のヒント