2014年3月27日

カラーミーAPIを試してみた 2

前回「カラーミーAPIを試してみた 1」からの引き続きです。
今回は、OAuth認証~ショップのデータを取得するところまで、私が実際にやって、エラーやメッセージが出たところなどを解説しています。

カラーミーAPI関連の情報は、ネット検索してもあまり多く見つかりません。そのため、「使ってみたいんだけど、OAuth認証(=意味不明)は敷居高いなぁ」って方も多いと思います。
実際のところ、用語、PHPのコーディングについて理解していなくても、「カラーミーショップAPIドキュメント」の内容だけで十分利用できます。

ただし、「カラーミーショップAPIドキュメントの、どのコードをどう使うの?」って点について、ライトユーザー向けのわかりやすい説明は省略されています。

ここでは、その省略された部分を埋めようと考えています。
できるかぎり丁寧に進めてまいりますので、ご参考にどうぞ。

以下は、「カラーミーショップAPIドキュメント」の例を実行して、ショップIDを取得するところまで、です。
カラーミーショップAPIドキュメント」の内容をメインに据えて、当サイトはその補足という形で進めてまいります。ということで、公式ページと平行して読み進めてください。


0.必要なもの
・Webサーバが必要です。(私は)PHPを使用します。
・カラーミーデベロッパーアカウントの登録。

登録はこちらとありますので、メールアドレスとパスワードを設定してください。
しばらくすると、登録したメールアドレス宛に「カラーミーデベロッパー仮登録のご案内」として、メールが届きます。
メール本文内の登録完了のURLをクリックすれば、本登録完了します。
では早速、メールアドレスとパスワードを入力してログインしてみましょう。

1. OAuthアプリケーション登録
「アプリケーションを追加する」をクリックするとページが遷移します。

遷移した先では、アプリケーション名と、リダイレクトURLを入力します。
リダイレクトURLは、あとからでも変更可能ですが、のちほどphpファイルを作成しサーバに置く必要がありますので、そのあたりを考慮して「http://hogehoge.heteml.jp/php/auth.php」 こんな感じで設定しておきます。
アプリケーション名は、「getExpl」としておきます。ここは重要ではないので、サクッと。
そして保存。

ページ遷移後に、クライアントIDクライアントシークレット(英数字の羅列)が表示されます。
これらを取得し、次のステップに行きます。

次のステップですが、ここからが「カラーミーショップAPIドキュメント」の内容だけでは、すこしわかりにくく感じました。
2. カラーミーショップアカウントの認証ページを表示します
3. 認可コードを取得
4. 認可コードとアクセストークンを交換
各節ごとに例が記載されていますが、使いませんのですっとばしてOKです。

クライアントIDクライアントシークレットを持って、認可コードを取得し、さらにアクセストークンに交換する手続きは、「6. その他のAPIの呼び出し」の「アプリケーションのWebサーバのサンプル」というコードです(ここ重要!)。
<?php

define("OAUTH2_SITE", 'https://api.shop-pro.jp');
define("OAUTH2_CLIENT_ID",'XXXXX');      // クライアントIDを入力します。
define("OAUTH2_CLIENT_SECRET", 'XXXXX'); // クライアントシークレットを入力します。
define("OAUTH2_REDIRECT_URI", 'http://example.com/index.php');

$code = $_GET['code'];
// 認可ページへリダイレクトする
if (empty($code)) {
    $params = array(
        'client_id'     => OAUTH2_CLIENT_ID,
        'redirect_uri'  => OAUTH2_REDIRECT_URI,
        'response_type' => 'code',
        'scope'         => 'read_products write_products read_sales write_sales'
    );
    $auth_url = OAUTH2_SITE . '/oauth/authorize?' . http_build_query($params);
    header('Location: ' . $auth_url);
    exit;
}

// 認可後
$params = array(
    'client_id'     => OAUTH2_CLIENT_ID,
    'client_secret' => OAUTH2_CLIENT_SECRET,
    'code'          => $code,
    'grant_type'    => 'authorization_code',
    'redirect_uri'  => OAUTH2_REDIRECT_URI
);
$request_options = array(
    'http' => array(
        'method'  => 'POST',
        'content' => http_build_query($params)
    )
);
$context = stream_context_create($request_options);

$token_url = OAUTH2_SITE . '/oauth/token';
$response_body = file_get_contents($token_url, false, $context);
$response_json = json_decode($response_body);

echo $response_body;// 今回追加した行
サンプルコード上部にクライアントIDクライアントシークレットを入力する箇所があります。早速、さきほどの文字列をコピペしましょう。リダイレクトURLは、アプリケーションの登録で入力したものを。ここでは「http://hogehoge.heteml.jp/php/auth.php」です。
そして、サンプルの一番下に一行、文字列(アクセストークン)を出力するコードを追加します。
以上で、コードの準備は完了です。

ファイル名を「auth.php」としてファイル保存し、phpファイルをWebサーバに置きます。
アプリケーションの登録で入力したリダイレクトURLと同じにする必要があります。ここでは、すぐ上と同様に「http://hogehoge.heteml.jp/php/auth.php」です。

Webサーバに置いたら、ブラウザで「http://hogehoge.heteml.jp/php/auth.php」を開きます。
下図が「2. カラーミーショップアカウントの認証ページを表示します」のいうところの認可ページです。
コンシューマ(アプリケーション提供者)がユーザーのショップ・データにアクセスしますけどいい?って、ユーザー(あなた)に聞いています。今回はコンシューマ=ユーザーなのでもちろんOKです。
カラーミーショップのログインID、パスワードを入力し、ログイン(=承認)します。

承認すると、下図のようにページ遷移します。

リダイレクトURLとphpファイルの置き場所が一致しないと、「404エラー(ページが見つかりません)」が返ってきます。

また、クライアントID、クライアントシークレット、リダイレクトURLが間違っていると、下記のようなエラーがでます。
Warning: file_get_contents(https://api.shop-pro.jp/oauth/token): failed to open stream: HTTP request failed! HTTP/1.1 401 Unauthorized in ~(略)

またまた、インストールされているPHPのバージョンによっては、下記のようなエラーがでます。
Fatal error: Call to undefined function: http_build_query() in ~(略)
http_build_query関数はPHP5以上が必要です(参考:PHP マニュアル)。WebサーバにインストールされているPHPのバージョンを確認し、場合によっては古いバージョンでも動くコードに修正する必要があります。

私が使っているヘテムルの場合は拡張子phpではダメで、php54に修正します(これで、PHP5.4を使うようになります)。
アプリケーション登録のリダイレクトURLと、phpファイル内のリダイレクトURLもあわせて修正(重要!)。

修正を終えたらもう一度。
ブラウザで「http://hogehoge.heteml.jp/php/auth.php54」を開きます。
リダイレクトURLが不一致でなければ、こんな感じで返ってきます。
Notice: file_get_contents(): Content-type not specified assuming application/x-www-form-urlencoded in  ~(略)
{"access_token":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","token_type":"bearer","scope":"read_products write_products read_sales write_sales"}
1行目のNoticeは無視してOKです(ネット検索すれば原因と消し方も載っています)。
2行目のaccess_token以下の長々とした英数字の羅列が、アクセストークンです。
これを持って、「5. アカウントの情報を取得するには」のサンプルコードへ。
<?php
$request_options = array(
    'http' => array(
        'method'  => 'GET',
        'header'=> "Authorization: Bearer 62971343fdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\r\n"
    )
);
$context = stream_context_create($request_options);

$url = 'https://api.shop-pro.jp/v1/shop.json';
$response_body = file_get_contents($url, false, $context);

$response_json = json_decode($response_body, true);// 今回追加した行
echo $response_json['shop']['id'];// 今回追加した行
サンプルコードの青部分を、さきほど取得したアクセストークンに置き換えます。
そして、一番下に2行追加。データ取得した結果を出力するコードです。

ファイル名を「getExpl.php54」としてファイル保存、Webサーバにアップロード、ブラウザで開く。
私が使っているヘテムルでは、下記のようなエラーメッセージがでました。
Warning: Cannot modify header information - headers already sent by (output started at ~(略)
原因として3つ挙げられていますが、それらはネット検索すると数多く情報が入手できます。
私はヘテムルですので、「nekonomemo.net」様の解説がとてもわかりやすく、助かりました。
php.iniの設定で、output_bufferingをOnにする(ここ、はまった)。

「PA*******」(=ショップID)と結果が表示されれば、カラーミーAPIでのアクセスが無事終了。
お疲れ様でした。


さて、いかがだったでしょうか。
$urlを変更することで、顧客情報や商品情報なども参照できます。 
アクセスできる情報は「カラーミーAPIインターフェイス v1」にあります。 
また、「カラーミーショップAPIドキュメントの一番下」には、更新のサンプルもあります。
実際使うことになった場合には、わかりやすくて助かると思います。

公式ページによると「アクセストークンの有効期限はない」とのことです。
アプリケーション(今回はgetExpl.php54)内に埋め込んで使っています。
毎回取得する必要はなく、アプリケーション毎に取得する必要も、実際のところはありません(とはいえ、機能を制限したアクセストークンを用意し、適切に使うことにはセキュリティの意味では有用です)。


【おわりに、と補足】
前回からの読者の方は、XAMPP使ってないよ!って話ですが。
次回は、もう少し実践的なカラーミーAPIを使ったサンプルを作って、紹介しようと思います(ので、今後はローカルな環境で作成、テストします)。
PHP寄り(整えたり、出力したり)の話題になると思います。

拡張子がphp54なのは、私が使っているヘテムルの仕様です。他のレンタルサーバは、どうなんでしょうね。

PHPの閉じタグ「?>」がないのはなぜ?って興味のある方は、ネットで検索してくださいね。

この記事は、2014年3月末時点のもので、いつのまにか「カラーミーショップAPIドキュメント」の内容が変わっていることも予想されます。あしからずご了承ください。

余談ですが、私はFirefoxのFirebugアドオンを入れているので、HTTPリクエスト、レスポンスを見ることができます。影の薄い認可コードがどう受け渡されたのか、リダイレクトURLが不一致だとなんでマズイのか、そして、auth.phpの$_GET['code']からアクセストークン取得までの一連のコードは、やり慣れない私にとって目新しく、興味深かったです。

2014年3月26日

カラーミーAPIを試してみた 1

カラーミーショップの本気を見た、カラーミーAPI。
Q.何ができるのか? A.むちゃくちゃできます。

太っ腹なことに、一番安いライトプランでも使用可能となっています。
色々と調査していると、すでにアプリケーション(顧客情報からDMを送る、複数のネットショップの在庫管理を一元化する等)が存在するようで、企業がサービスとして提供されているようです。

ここで取り上げるカラーミーAPIの話題は、主にアプリケーションの自作についてです。
(アプリケーションと呼ぶにはおおげさですが)機能追加のための必要データを、サーバから引っ張ってきたり。
ちなみに、参照以外に、更新も可能です(現時点です。今後も機能拡張されるようです)。


カラーミーAPIの使用に際し必要なものは、「カラーミーショップAPIドキュメント」に記載されています。
・カラーミーデベロッパーアカウント → すぐ作れます
・Webサーバ → ヘテムルなど。(私は)PHPを利用することにします


今回のテーマは下記のとおりで、カラーミーAPI利用前の準備編です。
・OAuth2.0やJSONといった用語について
・XAMPP for Windows(PHPのテスト環境)のインストール


1.OAuth2.0とは
カラーミーショップの「カラーミーショップAPIドキュメント」にサンプルがありますので、認証手順については、いちいち理解しなくても事足りますが、一応は読んでおくことをおすすめします。
カラーミーショップAPIドキュメント」中の用語(クライアントID=コンシューマ・キー、認可コード、アクセストークンなど) がチンプンカンプンでは少々心もとないので。
今回はアプリケーションを自作しますので、ユーザー=コンシューマになります。

【参考】
@IT-APIアクセス権を委譲するプロトコル、 OAuthを知る


2.JSON
軽量なデータ記述言語のひとつ。
更新、参照時にデータを送受信する必要がありますが、カラーミーAPIでは、リクエスト、レスポンス、どちらもJSONでやりとりを行います。


3.XAMPP for Windowsのインストール
PHP開発において通常、ローカル環境(たとえば、自分のWindows PC)で作成、テストした後に、サーバ(ヘテムルなど)にアップロードします。
修正→テストのたびに毎回アップロードする手間がかからなかったり、意図しないバグ混入によってサーバに多大な負荷をかけることがなかったり、そんな理由です。
インストール手順と設定については、ネット上に解説記事が数多くあります。セキュリティ設定をするところまでの解説が載っているものを参照してください。
PHPのコーディング自体は、テキストエディタがあれば、いまのところは十分です。

【参考】
XAMPP for Windows のダウンロードとインストールと設定


さて、次回の「カラーミーAPIを試してみた 2」は、「カラーミーショップAPIドキュメント」のサンプルを使って、カラーミーAPIを利用するためのOAuth認証~実際にショップのデータを取得するまで、です。
PHP初学者の方は、「PHPプロ!-PHP基礎講座」で自習しながらお待ちください。
次回につづく!

2014年3月25日

カラーミー追加機能案、あれこれ

クライアント様から、ウェブサイト・リニューアルに伴う機能追加の依頼がありました。
いただいた追加機能案について、カラーミーショップで実現可能か検討してみました。

1.Facebookのいいねボックス設置
→「Facebooke Developer Conference - Like Box

コードが取得できますので、手間をかけることなく完了。
横幅の最小が292pxとなっています。
CSSをいじって、180pxに詰め込んでみましたが、「いいね!」ボタン付近が崩れる場合がありますね。


2.カートの中身をサイドバーに表示
→「カラーミーショップ - 助け合い掲示板」を参考に。

独自タグ<{$incart}>があります。
実装されている無料テンプレートもすでにあるようです。そちらの中を見ても良いです。
マニュアルに載っていない(?)独自タグ<{$incart_delivery}>なんてのも出ているので、一読すべきか。


3.ログイン中のお客様の保有ポイントを表示
→ログイン中の顧客IDが、独自タグ<{$members_id}>にあるのだそうな。

カラーミーAPIで顧客の登録情報を取得できるので、可能だと思います。


4.トップページや商品一覧ページに「カートに入れる」を設置
→「どこでもカラーミー」で可能。デザイン的な裏技を記事にする予定。


5.検索ボタンを押すと検索キーワードがクリアされるのをなんとかして!
→JavaScriptで作れそうかなと思います。


6.商品一覧/検索結果ページ下のナビゲーション
→こんなやつ。できそうですよね。


7.商品画像の表示方法の工夫(漠然と)
→お客様に対して、商品の何をどのように伝えるのか。
いま一度、有名通販サイトなどを取り上げて、どのような工夫がされているのか、検証してみようと思います。


8.より良い検索機能(漠然と)
→ショップ内の商品検索についてです。

わりと重要な課題だと個人的には思っていますので、なにかしらの成果があれば、記事にしようと思います。


9.その他、個人的な調べ物
QRコード、Twitter API、jQueryのオシャレ機能、正規表現、PHP etc.


ということで、小ネタがいくつか溜まりましたので、適宜、記事として消化していく予定。
次回は、大変お待たせしました、カラーミーAPIを試してみた話題についてです。
どうぞおたのしみに。