TextData

概要

ユーザーからの自由文入力を取得・保存する API です。保存されているテキストは監視対象となります。
TextData オブジェクトをグルーピングする為の TextDataGroup オブジェクトは事前に作成しておく必要があります。
 

Profanity API と違い、Textdata API では人による監視が行われます。DeNA によるテキスト投稿監視を行わない場合には、Profanity API のみを使用してください。Textdata API を使用している場合は、Profanity API を利用する必要はありません。

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

説明

名前空間

補足

id

TextData オブジェクトの id

xs:string

http://ns.dena.jp/mbga/gameapi/

groupName

TextDataGroup オブジェクトの name

xs:string

http://ns.dena.jp/mbga/gameapi/

parentId

親に当る TextData オブジェクトの id

xs:string

http://ns.dena.jp/mbga/gameapi/

writerId

このデータを書き込んだ人の guid

xs:string

http://ns.dena.jp/mbga/gameapi/

ownerId

このデータの所有者の guid

xs:string

http://ns.dena.jp/mbga/gameapi/

data

テキストデータ

xs:string

http://ns.dena.jp/mbga/gameapi/

2048byte まで

status

論理ステータス値

xs:int

http://ns.dena.jp/mbga/gameapi/

published

生成日時

xs:dateTime

http://ns.dena.jp/mbga/gameapi/

GMT

updated

更新日時

xs:dateTime

http://ns.dena.jp/mbga/gameapi/

GMT

 

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

 

TextData#status フィールドの値

status

説明

0

通常

11

ユーザーによる編集

21

オペレータによる編集

31

パートナーによる編集

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

説明

名前空間

補足

id

TextDataGroup オブジェクトの id

xs:string

http://ns.dena.jp/mbga/gameapi/v1

name

TextDataGroup オブジェクトの名前

xs:string

http://ns.dena.jp/mbga/gameapi/

32byteまで

appId

application の id

xs:string

http://ns.dena.jp/mbga/gameapi/

parentId

親に当る TextDataGroup オブジェクトの id

xs:string

http://ns.dena.jp/mbga/gameapi/

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 パラメータは下記のいずれかの値を指定します。

説明

備考

@all

テキストデータグループ全体を表します

任意

{gid}

テキストデータをカテゴライズする gid 値 (TextDataGroup.name フィールド値) を指定します。テキストデータの一覧を示すコレクションリソースとなります。

任意

selector

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

説明

備考

@self

指定されたテキストデータグループエントリを指します

任意

@all

指定されたテキストデータグループに属するテキストデータコレクションを指します。

任意

@all/{-join|;|textDataId}

指定されたテキストデータグループに属する、指定された id を持つテキストデータエントリを指します

任意

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


クエリパラメータ

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

format

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

説明

備考

json

"application/json; charset=utf8"

任意、デフォルト値

fields

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

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

count

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

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

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

startIndex

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

filterBy

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

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

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

filterBy

説明

ownerId

TextData#ownerId

writerId

TextData#writerId

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

説明

equals

filterBy で指定したフィールドが filterValue で指定した値と一致するかどうか

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

filterValue

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

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

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

filterValue

説明

{guid}

guid の値 (整数値)

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

sortBy

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

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

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

sortBy

説明

id

TextData の id

updated

TextData の更新日時

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

sortOrder

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

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

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

sortOrder

説明

ascending

昇順

descending

降順

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

API レスポンス

レスポンスコード

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

リクエスト HTTP メソッド

レスポンスコード

レスポンスメッセージ

説明

GET

200

OK

データ の取得が正常に終了しました

POST

201

Created

データ の生成が成功しました

PUT/DELETE

202

Accepted

データ の更新または削除が成功しました

GET/PUT/DELETE

404

Not Found

データ が存在しないか、物理的に削除されています

GET/PUT/DELETE

403

Forbidden

認証エラー以外の理由でアクセス出来ない場合です

GET/POST/PUT/DELETE

400

Bad Request

リクエストデータが不正です

GET/POST/PUT/DELETE

401

Unauthorized

OAuth による認可が失敗しています

GET/POST/PUT/DELETE

405

Method Not Allowed

メソッドが許可されていません

GET/POST/PUT/DELETE

500

Internal Server Error

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としてください。なお、例えば「作戦会議」の投稿フォームに「タイトル」「作戦内容」の2つを別のカラムで入力させる場合は、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
PREVIOUS

Avatar

NEXT

Profanity