概要

TextData オブジェクトフィールド

TextData API へ GET リクエストを行うと、TextData オブジェクトを取得できます。

API からのレスポンスに含まれる xsd:dateTime 型の形式にはタイムゾーン指定子は含まれていません。従ってGMT(グリニッジ標準時)での表記となっております。

TextData#status フィールドの値

TextDataGroup オブジェクトフィールド

TextDataGroup API へ GET リクエストを行うと、TextDataGroup オブジェクトを取得できます。

API リクエスト

HTTP メソッド

Authorization Code Grant

• GET
  • テキストデータの一覧取得
  • テキストデータの取得
  • テキストデータグループの一覧取得
• POST
  • テキストデータの作成
• PUT
  • テキストデータの更新
• DELETE
  • テキストデータの削除

Client Credentials Grant

• GET
  • テキストデータグループの一覧取得
  • テキストデータグループの取得
  • テキストデータの取得
• POST
  • テキストデータグループの作成
  • テキストデータの作成
• PUT
  • テキストデータの更新
• DELETE
  • テキストデータグループの削除
  • テキストデータの削除

Client Credentials Grant を使用すれば、Mobage 非会員の状態でもテキストデータの作成・更新・削除が行えますが、Mobage 非会員の状態ではテキストデータの取得以外は行わないでください。

エンドポイント URL

• Sandbox 環境

  https://sb-app.mobage.jp/social/api/restful/v2/textdata/{appid}/{gid}{-prefix|/|selector}
  

• 本番環境

  https://app.mobage.jp/social/api/restful/v2/textdata/{appid}/{gid}{-prefix|/|selector}
  

   

  URI Template パラメータ

  appid

  appid パラメータは下記のいずれかの値を指定します。

  値	説明	備考
  @app	現在実行中の application id	必須

gid

gid パラメータは下記のいずれかの値を指定します。

selector

selector パラメータは下記のいずれかの値を指定します。

{textDataId} ですが、セミコロン区切りで複数の TextData#id を指定し、TextData コレクションリソースとして取得する事が出来ます

クエリパラメータ

下記のクエリパラメータを指定する事が出来ます。

format

レスポンス形式を指定する事が出来ます。

fields

取得したい TextData 情報を指定する事が出来ます。指定可能なフィールド名については TextData オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
fields パラメータを省略した場合、下記の属性情報全てを取得します。

パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。

count

コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。selector に @all を指定した場合や複数の TextData#id を指定した場合に指定出来ます。

デフォルト値は 50 件で、最大 1000 件まで指定出来ます。

パフォーマンス向上の為に、必要な件数のみを取得するようにして下さい。

startIndex

コレクションリソースの開始値を指定します。省略時は 1 が指定されます。また TextDataGroup のコレクションリソース取得時には startIndex の指定は無視され 1 となります。

filterBy

filterBy は TextData コレクションの取得時にのみ使う事が出来ます。

filterBy を指定すると、レスポンスとして返って来る TextData オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterBy 値は検索条件のキーとなるフィールドを指定します。

現在指定可能な filterBy 値は以下の表になります。

filterBy を指定する場合、filterOp, filterValue も指定されている必要があります。
また、ownerId, writerId の両方を用いたい場合は ',' (カンマ) で区切る必要があります。

例として、ownerId (guid:5), writerId (guid:10) の両方を指定した filter を掛けたい場合は、

GET /api/restful/textdata/@app/messageboard/@all?count=10&startIndex=11&filterBy=ownerId,writerId&filterOp=equals,equals&filterValue=5,10

のように API にアクセスします。

filterOp

filterOp は TextData コレクションの取得時にのみ使う事が出来ます。

filterOp を指定すると、レスポンスとして返って来る TextData オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterOp 値は検索条件のキーと値に対してどのような評価を行うかを指定します。

現在指定可能な filterOp 値は以下の表になります。

filterOp を指定する場合、filterBy, filterValue も指定されている必要があります。
filterBy に複数のフィールドを指定した場合、その個数分だけ ',' (カンマ) 区切りで filterOp の値を指定する必要があります。

filterValue

filterValue は TextData コレクションの取得時にのみ使う事が出来ます。

filterValue を指定すると、レスポンスとして返って来る TextData オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterValue 値は検索条件のキーに対して、どのような値と評価するかを指定する事ができます。

現在指定可能な filterValue 値は以下の表になります。

filterValue を指定する場合、filterBy, filterOp も指定されている必要があります。
filterBy に複数のフィールドを指定した場合、その個数分だけ ',' (カンマ) 区切りで filterValue の値を指定する必要があります。

sortBy

sortBy は TextData コレクションの取得時にのみ使う事が出来ます。

sortBy と sortOrder を指定すると、レスポンスとして返って来る TextData オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortBy 値はソートのキーとなるフィールドを指定する事が出来ます。

現在指定可能な sortBy 値は以下の表になります。

sortBy を指定する場合、sortOrder も指定されている必要があります。

sortOrder

sortOrder は TextData コレクションの取得時にのみ使う事が出来ます。

sortBy と sortOrder を指定すると、レスポンスとして返って来る TextData オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortOrder 値はソート時の昇順、降順を指定する事が出来ます。

現在指定可能な sortOrder 値は以下の表になります。

sortOrder を指定する場合、sortBy も指定されている必要があります。

API レスポンス

レスポンスコード

API のレスポンスコードは以下のいずれかになります。

利用フロー

各機能のリクエスト/レスポンス形式の例は下記サンプルをご確認ください。

1. パートナー様にて TextDataGroup を作成します。(Trusted)
2. 作成した TextDataGroup に対し下記機能が利用できます。(Trusted)

• TextDataGroup の取得
• TextDataGroup の削除

3. TextDataGroup に属する TextData エントリを作成します。(Trusted/Proxy)
4. 作成した TextData エントリに対し下記機能が利用できます。(Trusted/Proxy)

• TextData の取得
• TextData の更新
• TextData の削除

注意事項

• TextDataGroup は Trusted Model (OAuth Consumer Request) による API アクセスによって管理して下さい
• TextDataGroup#name 値は英数字及びアンダースコアのみ利用可能です。
• TextDataGroup#parentId, TextData#parentId は親子関係を表現する為に、子から見た親の id 値を入れるようになっています。監視の為に必要ですので親子関係のあるデータ構造の場合は必ず入れて下さい。
• TextData#data フィールドには文章と判断出来る文字列を入れて下さい。認識出来ない場合はオペレータにより削除される場合がありますのでご注意下さい。
• TextData#data フィールドにプラットフォームの運営ポリシーに反する禁止ワードが含まれる場合の TextData エントリの追加、更新は 400 Bad Request となります。
• TextData#writerId はその書き込みを行ったユーザーの guid が入ります。guid の数値部分が 0 の場合はパートナー様による Trusted Model による更新データ扱いになります。
• TextData#writerId とは異なるユーザーのアクセスによって更新されようとする TextData に対するパーミッションの管理はパートナー様の方で制御して下さい。API 側では TextData#writerId と異なる場合でも更新します。
  • 例として WiKi のような形式に利用する場合を考えると、同一データに対して複数人が更新すると言う事が考えられます。
• TextData#ownerId は元の所有者、あるいは親データの所有者などを表現する為に用意されたフィールドです。所有者に対するエントリ、または Trusted Model によるエントリには、必ず設定して下さい。
  • 例としてユーザーごとに割り当てられた伝言板に任意のユーザーが書き込みをする場合、所有者は伝言板を割り当てられたユーザーとなる為、TextData#ownerIdには所有者のIDを設定します。
• TextData#ownerId のユーザーが viewer を black list に登録していた場合、BlackList API を使用して書き込みができないようにして下さい。
• TextData#data のサイズは 2048 byte 以内として下さい。
• TextData#id を複数指定した GET は同一グループ内の id のみを指定して下さい。異なるグループに属する id は取得する事が出来ません。
• 削除した TextData は GET でエントリを取得することができなくなります。（404 Not Foundが返ります）
• ユーザーがそのアプリケーションをインストールしていない場合、レスポンスコードは 403 が返ります。
• POST の時に ownerId と parentId の値が含まれていない場合、初期値は 0 が返ります。

制限事項

• 1アプリケーションにつき作成できる TextDataGroup は 5 個になります。
• 各 TextDataGroup に格納できる最大エントリ数は アプリケーションをインストールしたユーザー数が 10,000 ユーザーまでは 100,000 件になります
  • 前日までのアプリケーションをインストールしたユーザー数が 10,000 ユーザーを超えた場合は、前日までの集計におけるインストールしたユーザー数 × 10 件になります。
• 最大エントリ数を超えた場合はそのグループに属するエントリで最も古いエントリから随時物理的に消されていきます。(404 Not Foundが返ります)
• 複数のカテゴリに属するTextDataを、1つのTextDataGroup IDで管理しないようお願いします。（例えば、「あいさつ」機能の投稿内容と「作戦会議」機能の投稿内容は、それぞれ別のTextDataGroup IDとしてください。なお、例えば「作戦会議」の投稿フォームに「タイトル」「作戦内容」の２つを別のカラムで入力させる場合は、1つのTextDataGroup IDとしてください。）
• Unicode6.0（iOS端末 絵文字）へは対応しておりません。文字コードは入出力共に UTF-8 となります。

サンプル

TextDataGroup の追加

新しい TextDataGroup を追加する例です。

リクエスト形式

POST /api/restful/v2/textdata/@app/@all
Content-Type: application/json; charset=utf8

{
  "name": "diary"
}

レスポンス形式

201 Created

TextDataGroup の削除

リクエスト形式

DELETE /api/restful/v2/textdata/@app/diary/@self

レスポンス形式

202 Accepted

TextDataGroup コレクションの取得

TextDataGroup コレクションに対して、count, startIndex クエリパラメータを適用した例です。

リクエスト形式

GET /api/restful/v2/textdata/@app/@all?count=2&startIndex=1

レスポンス形式

{
   "entry" : [
      {
         "parentId" : "0",
         "appId" : "12000002",
         "name" : "diary",
         "id" : "1"
      },
      {
         "parentId" : "0",
         "appId" : "12000002",
         "name" : "bbs",
         "id" : "2"
      }
   ],
   "startIndex" : 1,
   "itemsPerPage" : 2,
   "totalResults" : 5
}

TextDataGroup の取得

リクエスト形式

GET /api/restful/v2/textdata/@app/diary/@self

レスポンス形式

200 OK
Content-Type: application/json; charset=utf8

{
   "startIndex" : 1,
   "textDataGroup" : {
      "parentId" : "0",
      "appId" : "12000002",
      "name" : "diary",
      "id" : "1"
   },
   "itemsPerPage" : 1,
   "totalResults" : 1
}

グループからの TextData コレクションの取得

リクエスト形式

GET /api/restful/v2/textdata/@app/diary/@all?count=5&fields=id,data

レスポンス形式

{
   "entry" : [
      {
         "id" : "1",
         "data" : "今日の晩ご飯"
      },
      {
         "id" : "2",
         "data" : "ミラシスタ捕まえた"
      },
      {
         "id" : "3",
         "data" : "モントラが面白い"
      },
      {
         "id" : "4",
         "data" : "ヌヌエンバの画像にびっくり！！！"
      },
      {
         "id" : "5",
         "data" : "バースト運を試したよ"
      }
   ],
   "startIndex" : 1,
   "itemsPerPage" : 5,
   "totalResults" : 8
}

TextData#id を複数指定しての TextData エントリの取得

リクエスト形式

GET /api/restful/v2/textdata/@app/messages/@all/100;1107;1108?format=json

レスポンス形式

{
   "entry" : [
      {
         "status" : "0",
         "data" : "無限1upしてきました",
         "writerId" : "sb.mbga.jp:10001",
         "published" : "2010-01-19T06:29:57",
         "parentId" : "0",
         "id" : "1107",
         "updated" : "2010-01-19T06:29:57",
         "groupName":"messages",
         "ownerId" : "sb.mbga.jp:0"
      },
      {
         "status" : "0",
         "data" : "ポール越えしたい！",
         "writerId" : "sb.mbga.jp:12003",
         "published" : "2010-01-19T06:30:03",
         "parentId" : "0",
         "id" : "1108",
         "updated" : "2010-01-19T06:30:03",
         "groupName":"messages",
         "ownerId" : "sb.mbga.jp:0"
      }
   ],
   "startIndex" : 1,
   "itemsPerPage" : 50,
   "totalResults" : 2
}

TextData エントリの作成

diary TextDataGroup に TextData エントリを新しく追加する例です。
例) 10009 のユーザーがアプリ内の日記に書き込みをした場合

リクエスト形式

POST /api/restful/v2/textdata/@app/diary/@all
Content-Type: application/json; charset=utf8

{
   "data" : "怪盗ロワイヤルもやってます"
}

レスポンス形式

201 Created
Location: /api/restful/v2/textdata/@app/diary/@all/19

    "published" : "2009-12-09T06:39:01",
    "writerId" : "10009",
    "updated" : "2009-12-09T06:39:01",
    "id" : "19",
    "groupName" : "diary",
    "data" : "怪盗ロワイヤルもやってます"

例) 10009 のユーザーの日記に対して、10012 のユーザーがコメントをした場合

リクエスト形式

POST /api/restful/v2/textdata/@app/diary/@all
Content-Type: application/json; charset=utf8

{
   "data" : "僕もやってるよー",
   "ownerId" : "10009"
}

レスポンス形式

201 Created
Location: /api/restful/v2/textdata/@app/diary/@all/44

    "published" : "2009-12-09T08:42:23",
    "writerId" : "sb.mbga.jp:10012",
    "updated" : "2009-12-09T08:42:23",
    "id" : "44",
    "parentId" : "19",
    "groupName" : "diary",
    "data" : "僕もやってるよー",
    "ownerId" : "sb.mbga.jp:10009"

TextData エントリの取得

リクエスト形式

GET /api/restful/v2/textdata/@app/diary/@all/5

レスポンス形式

    "status": 0,
    "data" : "バースト運を試したよ",
    "writerId" : "sp.mbga.jp:10012",
    "published":"2009-11-26T12:59:29",
    "parentId" : "0",
    "id" : "5",
    "updated" : "2009-11-26T12:59:29",
    "groupName" : "diary",
    "ownerId" : "sp.mbga.jp:0"

TextData エントリの更新

リクエスト形式

PUT /api/restful/v2/textdata/@app/diary/@all/5
Content-Type: application/json; charset=utf8

{
  "data": "Lv30 になりました"
}

レスポンス形式

202 Accepted

TextData エントリの削除

リクエスト形式

DELETE /api/restful/v2/textdata/@app/diary/@all/5

レスポンス形式

404 Not Found