ご利用ガイド オブジェクトストレージを使う(RESTful API [PHP] 編)

RESTful APIを使用するにあたって

ConoHaオブジェクトストレージは、基盤ソフトウェアにOpenStack Swiftを使用しており、SwiftのRESTful APIを使いストレージを操作することができます。APIのリファレンスはオフィシャルサイトで見ることができます。

ConoHaのAPIリファレンスに日本語訳がございますので、こちらもご活用ください。

また、OpenStackには、KeyStoneという認証サービスがあります。オブジェクトストレージの認証にもKeyStoneが使用されるので、このAPIについても把握しておく必要があります。

OpenStack Identity API v2.0 Reference

OpenStackにはSDKが用意されていて、非常に多くの言語に対応しています。

OpenStack SDKs

SDKを使うと簡単に実装が進められますが、このガイドでは理解を深めるために、直接RESTful APIを使った実装をします。

オブジェクトストレージへの接続情報を調べる

ConoHaのコントロールパネルにログインして、メニューから[アカウント]->[API]と進んでください。ここにある、

• テナントID
• テナント名
• ユーザ名
• API Auth URL
• オブジェクトストレージエンドポイント

これらに加えて、あらかじめ設定したパスワードが必要になります。

実装する

RESTful APIはHTTP通信ですので、各言語にあるHTTPクライアントライブラリを使えば良いです。PHPには様々なHTTPクライアントが用意されていますが、ここではcURL関数を使ってみます 。

PHP cURL関数

サンプルコードは、アカウント情報やパスワードなど、ユーザ固有の情報は[config.php]にまとめて定義するようになっています。実際に動かしてみる場合は、定数定義(defineのところ)を変更してから試してください。

認証トークンの取得

オブジェクトストレージに接続する前に、接続するためのトークンを取得します。最初に説明したとおり、これはSwiftではなくKeyStoneが担当します。HTTP的にどのようなやりとりになるかは、オフィシャルのドキュメントがわかりやすいです。

Example 1.1. Request with headers: JSON

簡単に説明すると以下のようになります。

• 接続先はAPI Auth URLに”/tokens”を付加したURL
• メソッドはPOST
• POSTデータとしてJSON形式のデータを渡す
• 渡すデータは認証情報(username, passwordなど)
• Content-Typeはapplication/json
• レスポンスとして認証トークンを含んだJSONデータが返ってくる。

これを実装したサンプルコードは[token-get.php]こちらです。

PHPにはjson_encode(), json_decode()という、PHPの組み込み型とJSON文字列を相互変換する関数が用意されていてとても便利です。

PHP JSON関数

$data = array(
   'auth' => array(
        'tenantName' => TENANT_NAME,
        'passwordCredentials' => array(
            'username' => USERNAME,
            'password' => PASSWORD
        )
    )
);
$postdata = json_encode($data);

13行目付近では、PHPの連想配列からAPIに渡すJSON文字列を組み立てています。

サンプルコードの最後では、レスポンスのJSONデータからトークンと、オブジェクトストレージのエンドポイントURLを取得しています。このエンドポイントURLはコントロールパネルから確認できるものと同じです。ConoHaの場合は、このエンドポイントURLはユーザ毎に分かれていて、固定の値です。ただ今後もこの仕様が変わらないとは限らないので、プログラムからオブジェクトストレージにアクセスする場合は、ここで取得したURLを使うようにするべきです。

オブジェクトストレージへのアクセス

それでは、取得したトークンを用いて、オブジェクトストレージに接続します。

URI構造

オブジェクトストレージのAPIはRESTfulであり、URIで操作対象のオブジェクトを特定し、HTTPメソッドで操作方法を決定します。URIは次のような構造になっています。

/v1/{アカウント名}/{コンテナ名}/{オブジェクトID}

オブジェクトの情報を知りたい場合は上記のURIになりますが、アカウントの情報を知りたい場合は

/v1/{アカウント名}

というURIになります。URIとメソッドの動作については以下のリファレンスを確認してください。

OpenStack Object Storage API v1 Reference
ConoHa – APIドキュメント

HTTPヘッダー

オブジェクトストレージでは、HTTPリクエスト内のHTTPヘッダーで認証パラメータを送信します。認証トークンを送る場合はX-Auth-Tokenというヘッダーを送ればよく、これはRESTful APIでオブジェクトストレージを操作する場合に共通です。

HTTPヘッダーでは、コンテナやオブジェクトに対するさまざまなメタデータの設定も行えます。たとえばコンテナに対するPUTリクエストはコンテナの作成を行いますが、HTTPヘッダーで以下のような設定が可能です。

Create container – OpenStack Object Storage API v1 Reference  – API v1

コンテナの作成

まずは、オブジェクトを格納するコンテナを作成します。ここではtest-conohaと言う名前でコンテナを作成します。

サンプルコード記載ファイル→[container-create.php]

// HTTPヘッダー
$headers = array(
    // X-Auth-Tokenヘッダーでトークンを指定します
	'X-Auth-Token: ' . AUTH_TOKEN,
	'Content-Length: 0',

	// Acceptヘッダーでレスポンスの形式を指定できる
	// application/jsonの他にapplication/xmlやtext/xmlなど
	'Accept: application/json'
);

トークンはX-Auth-Tokenヘッダーで指定します。

// リクエストURL
// リクエストURL
// /(スラッシュ)区切りの最後のフィールドがコンテナ名になる
$url = ENDPOINT_URL . '/test-conoha';

この「test-container」の部分が作成するコンテナ名です。(tenane_name)の部分はコントロールパネルで表示される値で、ユーザ毎によって違う値になります。

// リクエスト/レスポンスが見やすいように冗長表示する
CURLOPT_VERBOSE => true,

リクエストが正しく処理されたかどうかは、レスポンスのHTTPステータスコードで判断します。レスポンスにはボディは含まれません、ヘッダーのみです。少しわかりにくいので、CURLOPT_VERBOSEをセットしてHTTP通信の詳細を表示するようにしてあります。

// HTTPステータスコードを取得します。
// 以下のようなステータスコードが返ってきます。
// 
// 201 Created     正常にコンテナが作成された
// 202 Accepted    リクエストが受け付けられた(すでに同じ名前のコンテナがあった場合など)
// 401 Unauthorize 認証失敗
$status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
echo "status code: " . $status_code . "n";

HTTPステータスコードを取得して表示します。コメントにあるとおり、基本的には201や202が返ってきます。

コンテナ一覧の取得

次にコンテナの一覧を取得して、コンテナが作成されていることを確認します。コンテナの一覧を取得する場合は、テナントに対してGETリクエストを送ります。

サンプルコード記載ファイル→[container-list.php]

// リクエストURL
$url = ENDPOINT_URL;

cURLは明示的にメソッドを指定しないとGETリクエストを送信するので、オプションなどでのメソッド指定はありません。

[
  {
    "name": "test-conoha",
    "bytes": 0,
    "count": 0
  }
]

レスポンスは、このようなJSON形式の文字列になります(見やすくするために改行とインデントを入れてます)。test-conohaと言うコンテナが作成されていることが確認できます。byteフィールドはコンテナ内のオブジェクトの使用容量、countはオブジェクト数です。

オブジェクトのアップロードとダウンロード

次に作成したコンテナに、オブジェクトのアップロードとダウンロードを試してみます。基本的にはコンテナの作成や一覧の取得と同じで、オブジェクトをアップロードする場合はPUT リクエスト、オブジェクトをダウンロードする場合はGETリクエスト、オブジェクトの一覧を取得する場合は、コンテナに対してGETメソッドでリクエストを送信します。

サンプルコード記載ファイル→[object-upload.php][object-download.php]

// アップロードするデータを作成
$content = 'ConoHa_TEST';
$fp = tmpfile();
fwrite($fp, $content, strlen($content));
fseek($fp, 0, SEEK_SET);

PHPのcURLでPUTリクエストを送る場合、cURLのオプションにファイルハンドルを渡す必要があります。ファイルハンドルとは、fopen()などが返すリソース型の変数です、ここではtmpfile()という関数を使っています。tmpfile()は、一時ファイルを作成そのファイルハンドルを返してくれる関数です。tmpfile()を使うメリットは、スクリプトの終了時に処理系が一時ファイルを自動的に削除してくれることです。

// Content-Typeヘッダーでアップロードするオブジェクトの形式を指定します。
'Content-Type: text/plain; charset=utf-8',

オブジェクトストレージは、テキスト、画像、動画など、どんな形式のデータでも扱うことができるのが特徴です。オブジェクトをアップロードする際に、その形式をContent-Typeヘッダーで指定することができます。

オブジェクトをダウンロードする際には、アップロード時に指定したContent-TypeがHTTPレスポンスヘッダーにセットされます。

// オブジェクトを作成する場合はPUT
CURLOPT_PUT => true,

// オブジェクトデータ
CURLOPT_INFILE => $fp,

オブジェクトの作成や更新にはPUTメソッドを使います。また、cURLで送信するファイルは、CURLOPT_INFILEオプションで指定します。先ほど説明したとおり、ここに渡すのはファイルハンドルです。

オブジェクトの作成、更新が完了すると、HTTPステータスコード201が返ります。

まとめ

RESTfulなAPIを使用することで、コンテナでもオブジェクトでも同じような操作が可能です。コンテナとオブジェクトの基本的な操作のみを取り上げましたが、オブジェクトストレージのほんの一部の機能しか使用していません。今回の基本を押さえておけば、あとはリファレンスを頼りに実装していくことが可能です。