Skip to main content

TextData

概要​

ユーザーからの自由文入力を取得・保存する API です。
TextData オブジェクトをグルーピングする為の TextDataGroup オブジェクトは事前に作成しておく必要があります。
なお、Textdata API を使用している場合は、Profanity API を利用する必要はありません。

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

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

値説明型補足
idTextData オブジェクトの idxs:string–
groupNameTextDataGroup オブジェクトの namexs:string–
parentId親に当る TextData オブジェクトの idxs:string–
writerIdこのデータを書き込んだ人の guidxs:string–
ownerIdこのデータの所有者の guidxs:string–
dataテキストデータxs:string2048byte まで
status論理ステータス値xs:int–
published生成日時xs:dateTimeGMT
updated更新日時xs:dateTimeGMT
note

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

TextData#status フィールドの値​

status説明
0通常
11ユーザーによる編集
21オペレータによる編集
31パートナーによる編集

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

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

値説明型補足
idTextDataGroup オブジェクトの idxs:string–
nameTextDataGroup オブジェクトの名前xs:string32byteまで
appIdapplication の idxs:string–
parentId親に当る TextDataGroup オブジェクトの idxs:string–

API リクエスト​

HTTP メソッド​

Authorization Code Grant

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

Client Credentials Grant

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

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}

{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説明
ownerIdTextData#ownerId
writerIdTextData#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説明
equalsfilterBy で指定したフィールドが 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説明
idTextData の id
updatedTextData の更新日時

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

sortOrder​

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

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

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

sortOrder説明
ascending昇順
descending降順

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

API レスポンス​

レスポンスコード​

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

リクエスト HTTP メソッドレスポンスコードレスポンスメッセージ説明
GET200OKデータ の取得が正常に終了しました
POST201Createdデータ の生成が成功しました
PUT/DELETE202Acceptedデータ の更新または削除が成功しました
GET/PUT/DELETE404Not Foundデータ が存在しないか、物理的に削除されています
GET/PUT/DELETE403Forbidden認証エラー以外の理由でアクセス出来ない場合です
GET/POST/PUT/DELETE400Bad Requestリクエストデータが不正です
GET/POST/PUT/DELETE401UnauthorizedOAuth による認可が失敗しています
GET/POST/PUT/DELETE405Method Not Allowedメソッドが許可されていません
GET/POST/PUT/DELETE500Internal Server ErrorAPI 側の問題による失敗です

利用フロー​

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

  1. パートナー様にて TextDataGroup を作成します。(Trusted)
  2. 作成した TextDataGroup に対し下記機能が利用できます。(Trusted)
  • TextDataGroup の取得
  • TextDataGroup の削除
  1. TextDataGroup に属する TextData エントリを作成します。(Trusted/Proxy)
  2. 作成した 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
  • 概要
  • TextData オブジェクトフィールド
    • TextData#status フィールドの値
  • TextDataGroup オブジェクトフィールド
  • API リクエスト
    • HTTP メソッド
    • エンドポイント URL
    • クエリパラメータ
  • API レスポンス
    • レスポンスコード
  • 利用フロー
  • 注意事項
  • 制限事項
  • サンプル
    • TextDataGroup の追加
    • TextDataGroup の削除
    • TextDataGroup コレクションの取得
    • TextDataGroup の取得
    • グループからの TextData コレクションの取得
    • TextData#id を複数指定しての TextData エントリの取得
    • TextData エントリの作成
    • TextData エントリの取得
    • TextData エントリの更新
    • TextData エントリの削除