このドキュメントは極力無駄なリクエストを行わないようし、アプリケーションの高速化を行う為のガイドラインです。

パートナー様からの API リクエスト数が異常な回数行われていたり、リクエストの仕方が非効率であると判断した場合には直接パートナー様へ改善の依頼を行う場合がございます。また緊急を要する場合にはメンテナンスモードに移行させて頂く場合や API の利用制限を掛けさせて頂く場合がございます。予めご了承下さい。

People API の @all, @friends を利用したアクセスについて

Mobage では友達数の上限値が設けられていないため、数万人単位で友達が居るユーザーが存在します。このようなユーザーの友達一覧を取得する API リクエストはある一定以上の実行時間が掛かってしまう事が考えられますので、友達一覧を随時必要とするようなサービスの場合は次のような事をご検討下さい。

1. ユーザーのログイン時などプラットフォームから渡される Access Token や Refresh Token を利用して、バックエンドで API アクセスを行う
2. API の実行結果は24時間程度であればデータベース等に保存する事を許可している為、保存したデータを再利用をする

API アクセスでは一度に最大で1000件しか取得出来ません。このようなユーザーの全ての友達を取得したい場合は、

startIndex x itemsPerPage > totalResults

という条件を満たすまで API を実行して下さい。
複数回 API にアクセスする場合は、プラットフォーム から渡される Access Token と Refresh Token を expire 付きで user ごとに管理する必要があります。
 

count, fields パラメータを用いて必要なデータを明示的に取得する

取得系の API に関しては count, fields パラメータを用いる事が出来ます。例えば People API で用いるフィールドが id, nickname, thumbnailUrl, profileUrl だけで、ページ辺り 7 件しか出さないのであれば、
 
fields
　　id,nickname,thumbnailUrl,profileUrl
count
　　7

のように指定して下さい。さらにアプリケーションをインストールしているユーザーだけを抽出したい場合は filter を用いて hasApp が true のユーザーだけを抽出するように設定して下さい。

リクエストサンプル

GET /api/restful/v2/people/@me/@friends?count=7&fields=id,nickname,thumbnailUrl,profileUrl&format=json&filterBy=hasApp&filterOp=equals&filterValue=true

レスポンスサンプル

200 OK

{
   "entry" : [
      {
         "nickname" : "OFFすずき",
         "thumbnailUrl" : "http://sp.mbga.jp/img_u/10033/0.0.gif",
         "id" : "mbga.jp:10033",
         "profileUrl" : "http://sp.mbga.jp/_u?u=10033"
      },
      {
         "nickname" : "え☆まーる",
         "thumbnailUrl" : "http://sp.mbga.jp/img_u/10059/0.0.gif",
         "id" : "mbga.jp:10059",
         "profileUrl" : "http://sp.mbga.jp/_u?u=10059"
      }
   ],
   "startIndex" : 1,
   "sorted" : false,
   "itemsPerPage" : 7,
   "updatedSince": false,
   "totalResults" : 2,
   "filtered": true
}

つまり取得系 API では、

• count で必要な件数しか取得しない
• fields で必要な属性しか取得しない
• filter で欲しい条件に一致したデータしか取得しない

という事を常に考えてリクエストして下さい。

Message API の実行間隔について

Message API ではそれぞれ実行間隔に制約がついており、制約に引っかかった場合は 503 Service Unavailable が返って来ます。
 
以下に制約のガイドラインをまとめます。

Authorization Code Grant 時の制約に関しては、大量にユーザーへの Message フィードが配信される事は望ましくありません。アプリケーションに応じて必要最小限かつ効果的な部分に対してのみ適用して下さい。また技術的に対応可能であれば上記制約をアプリケーション側で制御し、API リクエスト自体送信されないようにして下さい。今後、上記制約は API 等の負荷を見て変更される場合がございますので、柔軟に対応出来るようにして下さい。

Message API の Client Credentials Grant での配信ですが、4時間おきにリクエストをするのが望ましいですが、適当なインターバル (1秒程度) を設定してリクエストを送信して下さい。並列にアクセスしても結果的に API サーバー側ではロックが発生し期待通りの早さは得られず他のアプリケーションにも影響を与えかねません。

以上まとめると、Message API では、

• 不要な Message の投稿は極力さける
• 可能ならば上記制約に引っかかる事の無いようにアプリケーション側で API リクエストその物を抑止する
• Client Credentials Grant による Message 投稿は並列でアクセスせず適当なインターバルを設けてリクエストする

として下さい。

API レスポンスのキャッシュについて

TextData API は内容の確認をする兼ね合い上、パートナー様側で内容のキャッシュを持つ事は出来ませんが、他の GET 系の API レスポンスで即時性を伴わないものに関しては 24 時間程度のキャッシュを行って構いません。例えばユーザーのプロフィールや Avatar 画像への URL などはアプリケーションの実行上差し支えなければ積極的にキャッシュするようにお願い致します。

TextData API を使ったデータ取得について

TextData API をパートナー様がご利用になる場合、パートナー様が持つデータベースでは、TextData#id 値を保存するようになると思われます。
この際に TextData#status 値相当も同様に保存される事をお勧め致します。status 値相当の値は TextData API への PUT, DELETE 時にお手元の status 値相当の値も更新して下さい。
この際に手元の status 相当値と異なる値が返って来る場合がありますが、それは弊社カスタマーサポートによるペナルティ判定された投稿ですので、その際には「管理者により削除されました」等の文言をお出し頂ければと思います。
 
また可能な限り ownerId, writerId を POST 時に指定して下さい。ownerId, writerId の組み合わせで必要最小限のデータセットとなるよう設計頂きますようお願い致します。filterBy を用いない GET アクセスはデータ量が多くなると大変遅くなってしまいますのでご注意下さい。

TextData API では id, updated 値でソートしつつ、writerId, ownerId 値を条件としたコレクションリソースの取得が出来ますが、直接 id を複数指定したコレクションの取得を行う事が出来ます。こちらの方が直感的でかつ早いレスポンスが期待出来るので積極的にご利用下さい。

リクエストサンプル

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

レスポンスサンプル

200 OK


{
   "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
}

更新履歴

• 2015/02/05
  
  • 新規作成