4. オブジェクトストレージ¶

JSON 形式でオブジェクトを保存、読み出しすることができます。

オブジェクトは「バケット」毎に分類されます。バケットとは、SQL データベースでいうところの「テーブル」に該当する概念で、同一種類のオブジェクトを格納する入れ物です。

オブジェクトストレージの API エンドポイントは以下の URL となります。

https://{server}/api/1/{tenant}/objects/{bucketName}

4.1. オブジェクトバケットの作成¶

オブジェクトを格納する前に、オブジェクトバケットを作成しておく必要があります。

バケットの作成はデベロッパーコンソールで行うことができます。また、REST API や各 SDK から実行することも可能です。

4.2. オブジェクトの作成¶

curl -X POST \
 -H "X-Application-Id: {app_id}" \
 -H "X-Application-Key: {app_key}" \
 -H "Content-Type: application/json" \
 -d '{"name":"Foo", "score":80}' \
 https://{server}/api/1/{tenant}/objects/scores

ここでは scores バケットに JSON オブジェクトを書き込んでいます。

正常にオブジェクトが書き込まれると、200 OK が返り、以下のように作成されたオブジェクトが返却されます。

{
  "_id": "521c36d4ac521e1ffa000007",
  "name": "Foo",
  "score": 80
  "ACL": {
    "r": ["g:anonymous"],
    "w": ["g:anonymous"]
  },
  "createdAt": "2013-08-27T05:19:16.000Z",
  "updatedAt": "2013-08-27T05:19:16.000Z"
}

'_id' にはオブジェクトのIDが入ります。
'ACL' には、以下で説明する ACL が入ります。
'createdAt はオブジェクトの作成時刻です
'updatedAt はオブジェクトの更新時刻です

主なステータスコードは以下の通り。

200 OK : 正常登録した
400 Bad Request : パラメータ/リクエストボディ不正
401 Unauthorized : 認証エラー
403 Forbidden :権限エラー
404 Not Found : バケットが存在しない

4.3. アクセス制御¶

オブジェクトには ACL (Access Control List)を設定することで、アクセス制御を行うことができます。

ACL は、オブジェクト作成時に 'ACL' キーを指定することで設定します。

ACL キー内の 'owner' キーに、オブジェクトのオーナのユーザIDを指定します。オーナはオブジェクトの読み書きの権限がすべて与えられます。

ACL キー内の 'r' に読み込み可能なユーザ一覧、'w' に書き込み・削除可能なユーザ一覧を配列で指定します。

また、グループ名を指定することも可能です。グループ名を指定する場合は "g:groupA" のように先頭に "g:" を付与してください。

なお、ログイン済み全ユーザを表す "authenticated" グループと、未ログインユーザ全員を表す "anonymous" グループも使用できます。

ユーザ・グループ、いずれかの条件に合致すると、オブジェクトへのアクセスが許可されます。

{
  "name":"Foo",
  "score":80,
  "ACL": {
    "owner": "52116f01ac521e1742000001",
    "r": ["g:anonymous"],
    "w": ["g:groupA"],
  }
}

上記の例では、誰でも読み込み可能で、書き込みは groupA が可能。オーナとなる 52116f01ac521e1742000001 ユーザはすべて可能という指定となります。

なお、ACL を指定せずにオブジェクトを作成した場合は、以下のような動作となります。

X-Session-Token ヘッダでセッショントークンを送信した状態でオブジェクトを作成すると、そのユーザIDでのみ読み書き可能な状態でオブジェクトが作成されます。
X-Session-Token ヘッダが送信されない状態でオブジェクトを作成した場合、誰でも読み書き可能な状態でオブジェクトが作成されます。
いずれの場合もグループは指定されません。

4.4. オブジェクトの取得¶

オブジェクトIDを指定することでデータを読み出します。

curl -X GET \
 -H "X-Application-Id: {app_id}" \
 -H "X-Application-Key: {app_key}" \
 https://{server}/api/1/{tenant}/objects/scores/52117490ac521e5637000001

以下のように結果が得られます。

{
  "_id": "52117490ac521e5637000001",
  "name": "Foo",
  "score": 80
  "ACL": {
    "owner": "52116f01ac521e1742000001",
    "r": [],
    "w": []
  },
  "createdAt": "2013-08-27T05:19:16.000Z",
  "updatedAt": "2013-08-27T05:19:16.000Z"
}

createdAt はオブジェクトの作成時刻、updatedAt はオブジェクトの更新時刻です。

主なステータスコードは以下のとおりです:

200 OK : 正常にオブジェクトを取得した
400 Bad Request : リクエストが不正
401 Unauthorized : 認証エラー
403 Forbidden : 読み出し権限がない
404 Not Found : 該当するオブジェクトがない、または読み込み権限がない

4.5. クエリ¶

以下のようにすると、すべてのオブジェクトのリストを読み出します。ただし、読み出し権限がないオブジェクトは取得されません。

curl -X GET \
 -H "X-Application-Id: {app_id}" \
 -H "X-Application-Key: {app_key}" \
 https://{server}/api/1/{tenant}/objects/scores

結果は、以下のよう、results 内に、配列でオブジェクトが格納された形で得られます。

{
  "results":[
    {
      "_id":"52117490ac521e5637000001",
      "name":"Foo",
      "score":80,
      "ACL": {
        "owner": "52116f01ac521e1742000001",
        "r": [],
        "w": []
      },
      "createdAt": "2013-08-27T05:19:16.000Z",
      "updatedAt": "2013-08-27T05:19:16.000Z"
    }
  ]
}

4.5.1. 条件指定クエリ¶

条件指定は where= パラメータで行う。

curl -X GET \
 -H "X-Application-Id: {app_id}" \
 -H "X-Application-Key: {app_key}" \
 -G \
 --data-urlencode 'where={"name":"Foo"}' \
 https://{server}/api/1/{tenant}/objects/scores

where には JSON でパラメータを指定します。

特定のキーに対して完全一致させたい場合は、以下のように JSON で指定します。

{"name": "Foo"}

比較を行う場合は、以下の演算子を利用できます。

$lt, $gt : Less Than / Greater Than
$lte, $gte : Less or Equal / Greater of Equal
$ne : Not equal to

例) score が 70 超のものを選択したい場合

{"score": {"$gt": 70}}

その他の演算子。これらは MongoDB のクエリがそのまま使用できます。

$in
$nin
$all
$regex
$exists
$not
$and
$or
$nor

4.5.2. 順序指定¶

順序指定は order パラメータで行います。

curl -X GET \
 -H "X-Application-Id: {app_id}" \
 -H "X-Application-Key: {app_key}" \
 -G \
 --data-urlencode 'order=age' \
 https://{server}/api/1/{tenant}/objects/scores

order に指定したキーの昇順でソートされます。

降順にしたい場合は "order=-age" のように "-" を付けてください。

4.5.3. skip / limit¶

limit で検索件数上限、skip でスキップする検索数を指定できます。

curl -X GET \
 -H "X-Application-Id: {app_id}" \
 -H "X-Application-Key: {app_key}" \
 -G \
 --data-urlencode 'skip=100' \
 --data-urlencode 'limit=50' \
 https://{server}/api/1/{tenant}/objects/scores

4.6. 更新¶

PUT メソッドで、オブジェクトの URI を指定して更新を行います。オブジェクトの書き込み権限が必要です。

curl -X PUT \
 -H "X-Application-Id: {app_id}" \
 -H "X-Application-Key: {app_key}" \
 -H "Content-Type: application/json" \
 -d '{"name":"Foo", "score":90}' \
 https://{server}/api/1/{tenant}/objects/scores/52117490ac521e5637000001

上記書式の場合、指定したフィールドだけが更新されます。指定していないフィールドは、'updatedAt' 以外更新されません。 ('updatedAt' フィールドは現在時刻に更新されます)

主なステータスコードは以下のとおりです:

200 OK : 正常にオブジェクトを更新した
401 Unauthorized : 認証エラー
403 Forbidden : 書き込み権限がない
404 Not Found : 該当するオブジェクトがない

データの指定方法により、完全上書きと、一部更新の２通りを選択することができます。

4.6.1. 部分更新¶

オブジェクトの一部のみを更新する方法です。

以下は、score を 80 に変更する例です。指定していないフィールドは変更されません。

{"score": 80}

$set 演算子を使用することも可能です。

{"$set": {"score": 80}}

$inc 演算子を使用すると、インクリメントを行うことができます。

{"$inc": {"score": 10}}

他に、 MongoDB の更新演算子がすべて使用できます。

注釈

updatedAt は、現在時刻で更新されます。また、etag は自動的に変更されます。

4.6.2. 完全上書き¶

完全上書きを行う場合は $full_update 演算子を使用します。

{"$full_update": {"name":"Bar", "score":90, "ACL": {"owner":"xxx", "r":[], "w":[]}}}

この方法では、指定したデータでオブジェクトが置き換えられます。

注意

指定されなかったフィールドは削除されます。また、ACL を指定しない場合は 400 Bad Request エラーとなります。

注釈

updatedAt は、現在時刻で更新されます。 createdAt は、指定しない限り元の値が維持されます。また、etag は自動的に変更されます。

4.7. 削除¶

DELETE メソッドで、オブジェクトの URI を指定して削除を行います。オブジェクトの書き込み権限が必要です。

curl -X DELETE \
 -H "X-Application-Id: {app_id}" \
 -H "X-Application-Key: {app_key}" \
 https://{server}/api/1/{tenant}/objects/scores/52117490ac521e5637000001

主なステータスコードは以下のとおりです:

200 OK : 正常にオブジェクトを削除した
401 Unauthorized : 認証エラー
403 Forbidden : 書き込み権限がない
404 Not Found : 該当するオブジェクトがない