NIFTY CloudのREST APIを使うために必要な知識

 

クラウドを有効活用しようと思った時に避けては通れないAPI。活用できれば非常に便利ですが、初めて使う人にとってはなかなかハードルが高いのではないでしょうか。

ニフティクラウドのREST APIを利用するための前提条件をもとに、APIを使うために必要なことをまとめておきます。ニフティクラウド以外のクラウド、例えばAWS（AmazonWebServices)などでも応用できる情報だと思います。

ニフティクラウドやAWSのREST APIを使うために必要なこと

ニフティクラウドのドキュメントを見ると、REST APIを使うための前提は次のように書かれています。

REST API の利用には、前提知識以外に別途以下の知識を持つ方を前提としています。

  • XMLに関する知識（「W3 Schools XML Tutorial」参照）
  • Webサービスの基本構造に関する知識（「W3 Schools Web Services Tutorial」参照）
  • プログラミングに関する知識
  • ニフティクラウドでのサーバー構築・運用に関する知識
  • REST通信に関する知識
  • Hmacハッシュ方式に関する知識

XMLに関する知識

ニフティクラウドのREST APIのレスポンスはXML形式で返却されてきます。そのため、XMLをパースするための知識が必要になります。

XMLとは、下のような書式のフォーマットです。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<all_syain>
    <syain>
        <name>山田太郎</name>
        <no>1</no>
    </syain>
    <syain>
        <name>山田花子</name>
        <no>2</no>
    </syain>
</all_syain>

phpでは、次のような形でパースすることができます。


<?php

$xml="/tmp/test.xml";
$res=simplexml_load_file($xml);
foreach($res->syain as $syain) {
    echo $syain->no . ":" . $syain->name ."\n";
}
?>

実際REST APIからレスポンスを受け取った場合は、ファイルではなく文字列となるので、simplexml_load_string　関数でパースすると良いです。

Webサービスの基本構造に関する知識

最低限HTTPメソッドの知識と、URLに関する知識があればよいと思います。

HTTPメソッド

  • GET：リソースの情報取得。指定したURIの情報を取得するためのメソッドです
  • POST：リソースの作成
  • PUT：リソースの更新
  • DELETE：リソースの削除

一般的なWEBサイトでは、GETかPOSTが良く使われています。REST APIになると、PUTやDELETEメソッドなんかも使うようになります。

URLの構造

URLは次のような構造になっています。

http://naoberry.com/tech/?id=999&hoge=xxx

URLを分解してみると

プロトコル://ドメイン（エンドポイント）/URI?URLパラメータ&URLパラメータ2

となっています。それぞれ解説すると次のような内容です。

  • プロトコル：httpまたはhttpsを指定します
  • ドメイン（エンドポイント）：アクセス先のFQDNを指定します
  • URI：アクセス先のリソースを指定します
  • URLパラメータ：キー=値の書式でサーバへ送信するパラメータを指定します。複数ある場合は「&」で連結させます。

プログラミングに関する知識

REST APIでは、ブラウザへURLを直接入力することで操作することも可能ですが、使いこなそうと思うと、プログラミングが必要不可欠です。

phpなどでは、curlライブラリを使ってプログラムからREST APIを実行します。

http://naoberry.com/tech/?id=999&hoge=xxxを、phpから実行する場合は次のような形で実行が可能です。


<?php
$params = Array();
$params["id"]="999";
$params["hoge"]="xxx";

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "http://naoberry.com/tech/?". http_build_query($params));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

$res = curl_exec($curl);
$header = curl_getinfo($curl);

$code = $header["http_code"];
if ($code == 200) {
    echo $res;
}else{
    echo "ERROR " . $code;
}

?>

ニフティクラウドでのサーバー構築・運用に関する知識

「APIを使いたい」と思っているはずなので、何がやりたいかが明確になっていると思います。

やりたいことを実現するための知識を調べましょう。

REST通信に関する知識

REST APIを簡単にまとめると下のような感じです。

  • REST APIはREpresentational State Transferの略称
  • HTTPプロトコルに則ったAPI
  • レスポンスは、xmlだったりjsonだったりする

簡単にいうと、所定の形式に従ったリクエストを投げることで、サーバ側に対して操作が可能になるということです。

APIによっては、レスポンスがxml形式だったり、json形式だったりするので、それぞれの形式に合わせた形でパースしてあげる必要があります。

Hmacハッシュ方式に関する知識

実際使ってみようと思った時にはまったのは、「Signature（シグネチャー）」。一体シグネチャーって何なのさ？と思いドキュメントを確認してみると、リクエストが正常なリクエストということを証明するためのもののようです。

しかし、対応バージョンが0から4まで複数あり、機能ごとに対応バージョンが異なっており混乱します。

参考：ニフティクラウド　シグネチャーについて

今回試してみたい機能がバージョン2に対応しているものだったので、ドキュメントを見てみるとこんな記載がありました。

StringToSign = HTTPリクエストメソッド + \n
endpointのドメイン部分 + \n
URLエンコードしたendpointのパス部分 + \n
リクエスト文字列

Signature = Base64(SignatureMethod によるハッシュ(SecretAccessKey, StringToSign) )

参考：ニフティクラウド　REST共通パラメーターと認証方式

StringToSignの文字列を、SignatureMethodのアルゴリズムでハッシュ値を取って、Base64方式でエンコードするといいみたいです。うん、正直よくわからない・・・

SignatureMethod によるハッシュ

リクエスト文字列のSignatureMethodへ、APIの認証ロジックとして、「HmacSHA1」や「HmacSHA256」を指定しています。このロジックを使い、コンパネから取得可能なSercret_Keyを使いハッシュ値を作成するようです。

phpのソースだと次のような形になります。

$hash=hash_hmac("sha256", $StringToSign, {SERCRET_KEY}, true);

Base64

上記で取得したハッシュ値を、MIME Base64方式でデータをエンコードしてあげます。

phpのソースだと次のような形になります。

$base64=base64_encode($hash);

サンプルコード

ニフティクラウドのメッセージキューのREST APIを使って、キュー内のメッセージ数を取得するサンプルコードです。

{SERCRET_KEY}と{AccessKeyId}は、コンパネのAPI認証から取得可能です。{@niftyID}と{キュー名}は自身の環境に合わせて設定してください。


<?php
// 内部エンコーディングとして UTF-8を使用 (php.iniで設定してもよい)
ini_set("mbstring.internal_encoding", "UTF-8");

// APIのルートとなる URL
define("SERCRET_KEY",{SERCRET_KEY});
define("END_POINT","mq.jp-east-1.api.cloud.nifty.com");
define("API_URL", "https://" . END_POINT);
define("API_URI", "/{@niftyID}/{キュー名}/");

// URLパラメータを APIに渡すパラメータとして再構成
$params = Array();
$params["AccessKeyId"]={AccessKeyId};
$params["Action"]="GetQueueAttributes";
$params["AttributeName.1"]="ApproximateNumberOfMessages";
$params["SignatureMethod"]="HmacSHA256";
$params["SignatureVersion"]="2";

// シグネチャー作成
$StringToSign="GET\n" . END_POINT . "\n" . API_URI . "\n" . http_build_query($params);
$params["Signature"]=base64_encode(hash_hmac("sha256", $StringToSign, SERCRET_KEY,true));

// curl(HTTPクライアントライブラリ)を使ってAPIを呼び出す
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL,API_URL . API_URI . "?". http_build_query($params));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$res = curl_exec($curl);
$header = curl_getinfo($curl);

// APIのHTTPコードをチェック
$code = $header["http_code"];
if ($code >= 400) {
    header("HTTP", true, $code);
    echo $res; // APIのエラー表示をそのままブラウザへ返す
    exit();
}else{ // 正常に取得できた場合、メッセージ数を出力
    $xml=simplexml_load_string($res);
    echo $xml->GetQueueAttributesResult->Attribute->Value;
}
?>
  • このエントリーをはてなブックマークに追加
  • Pocket

この記事へのコメントはこちら

メールアドレスは公開されませんのでご安心ください。
また、* が付いている欄は必須項目となりますので、必ずご記入をお願いします。

内容に問題なければ、下記の「コメント送信」ボタンを押してください。

PREV：
Fluentd、ElasticsearchとKibanaが使えそうな一つのシチュエーション
NEXT：
rsyncコマンドでデータの同期を行う