TextData
概要
ユーザーからの自由文入力を取得・保存する API です。
TextData オブジェクトをグルーピングする為の TextDataGroup オブジェクトは事前に作成しておく必要があります。
なお、Textdata API を使用している場合は、Profanity API を利用する必要はありません。
TextData オブジェクトフィールド
TextData API へ GET リクエストを行うと、TextData オブジェクトを取得できます。
| 値 | 説明 | 型 | 補足 |
|---|---|---|---|
| id | TextData オブジェクトの id | xs:string | – |
| groupName | TextDataGroup オブジェクトの name | xs:string | – |
| parentId | 親に当る TextData オブジェクトの id | xs:string | – |
| writerId | このデータを書き込んだ人の guid | xs:string | – |
| ownerId | このデータの所有者の guid | xs:string | – |
| data | テキストデータ | xs:string | 2048byte まで |
| status | 論理ステータス値 | xs:int | – |
| published | 生成日時 | xs:dateTime | GMT |
| updated | 更新日時 | xs:dateTime | GMT |
API からのレスポンスに含まれる xsd:dateTime 型の形式にはタイムゾーン指定子は含まれていません。従ってGMT(グリニッジ標準時)での表記となっております。
TextData#status フィールドの値
| status | 説明 |
|---|---|
| 0 | 通常 |
| 11 | ユーザーによる編集 |
| 21 | オペレータによる編集 |
| 31 | パートナーによる編集 |
TextDataGroup オブジェクトフィールド
TextDataGroup API へ GET リクエストを行うと、TextDataGroup オブジェクトを取得できます。
| 値 | 説明 | 型 | 補足 |
|---|---|---|---|
| id | TextDataGroup オブジェクトの id | xs:string | – |
| name | TextDataGroup オブジェクトの名前 | xs:string | 32byteまで |
| appId | application の id | xs:string | – |
| parentId | 親に当る TextDataGroup オブジェクトの id | xs:string | – |
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} |
{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 側の問題による失敗です |
利用フロー
各機能のリクエスト/レスポンス形式の例は下記サンプルをご確認ください。
- パートナー様にて TextDataGroup を作成します。(Trusted)
- 作成した TextDataGroup に対し下記機能が利用できます。(Trusted)
- TextDataGroup の取得
- TextDataGroup の削除
- TextDataGroup に属する TextData エントリを作成します。(Trusted/Proxy)
- 作成した 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