ページ分割された結果

グラフAPIの基本的な用語と構造については、「グラフAPIの概要」で確認してください。このドキュメントでは、APIリクエストから返される結果について詳しく説明します。

ページ分割された結果のページ送り

通常、ノードやエッジにAPIリクエストを実行すると、1つの応答でそのリクエストの結果すべてを受信するわけではありません。応答によっては数千のオブジェクトが含まれている場合があるため、大半の応答はデフォルトでページ分割されています。

カーソルベースのページ分割

カーソルベースのページ分割は、最も効率的なページ分割方法であり、可能な時は常に使用してください。カーソルは、データのリスト内の特定のアイテムをマークする、ランダムな文字列を参照します。カーソルは常にこのアイテムを指します。ただし、アイテムが削除されるとこの機能は無効になります。このため、アプリではカーソルを保管したり、それらのカーソルが将来も有効であることを前提にしたりしないでください。

カーソルページ分割をサポートしているエッジを読み取ると、次のJSON応答が表示されます。

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

カーソルページ分割のエッジでは、以下のパラメーターがサポートされています。

• before: このカーソルは、返されたデータのページの先頭に置かれます。
• after: このカーソルは、返されたデータのページの最後に置かれます。
• limit: 返される可能性があるオブジェクトの最大数です。フィルタリングされるため、クエリが返すオブジェクトの数はlimitよりも少なくなる場合があります。クエリがデータリストの末尾に達したことを判断する際、結果のデータ数がlimitの値よりも小さいことを判断基準とするのではなく、下記で説明されているように、nextがないことを判断基準としてください。たとえば、limitを10に設定し、返された結果が9個の場合、データがほかにもまだあるかもしれませんが、プライバシーフィルターによってアイテムが1つ削除されています。パフォーマンス上の理由により、一部のエッジでは、limit値に上限を設けている場合があります。いずれの場合でも、APIから正しくページ分割されたリンクが返されます。
• next: データの次ページを返すグラフAPIエンドポイントです。含まれていない場合、これがデータの最終ページになります。ページ分割と可視性やプライバシーとの関係よって、空のページにnextページングリンクが含まれている場合があります。nextリンクが表示されなくなったら、ページ送りをストップしてください。
• previous: データの前のページを返すグラフAPIエンドポイントです。含まれていない場合、これはデータの最初のページになります。

時間ベースのページ分割

時間によるページ分割は、データのリストの特定の時間を示すUnixタイムスタンプを使って、結果データをナビゲートします。

時間ベースのページ分割を利用するエンドポイントを使うと、以下のJSON応答が表示されます。

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774"
  }
}

時間のページ分割エッジでは、以下のパラメーターがサポートされています。

• until: 時間ベースのデータ範囲の末尾を指すUnixタイムスタンプまたはstrtotimeデータ値です。
• since: 時間ベースのデータ範囲の先頭を指すUnixタイムスタンプまたはstrtotimeデータ値です。
• limit: 返される可能性があるオブジェクトの最大数です。フィルタリングされるため、クエリが返すオブジェクトの数はlimitよりも少なくなる場合があります。クエリがデータリストの末尾に達したことを判断する際、結果のデータ数がlimitの値よりも小さいことを判断基準とするのではなく、下記で説明されているように、nextがないことを判断基準としてください。たとえば、limitを10に設定し、返された結果が9個の場合、データがほかにもまだあるかもしれませんが、プライバシーフィルターによってアイテムが1つ削除されています。パフォーマンス上の理由により、一部のエッジでは、limit値に上限を設けている場合があります。いずれの場合でも、APIから正しくページ分割されたリンクが返されます。
• next: データの次ページを返すグラフAPIエンドポイントです。
• previous: データの前のページを返すグラフAPIエンドポイントです。

オフセットベースのページ分割

オフセットページ分割は、時系列についてはこだわらず、特定のオブジェクト数だけを返してほしい時に使用できます。これは、エッジでカーソルベースや時間ベースのページ分割がサポートされていない場合にのみ、使うようにしてください。

オフセットページ分割エッジでは、以下のパラメーターがサポートされています。

• offset: 各ページの先頭を指定した数だけオフセットします。
• limit: 返される可能性があるオブジェクトの最大数です。フィルタリングされるため、クエリが返すオブジェクトの数はlimitよりも少なくなる場合があります。クエリがデータリストの末尾に達したことを判断する際、結果のデータ数がlimitの値よりも小さいことを判断基準とするのではなく、下記で説明されているように、nextがないことを判断基準としてください。たとえば、limitを10に設定し、返された結果が9個の場合、データがほかにもまだあるかもしれませんが、プライバシーフィルターによってアイテムが1つ削除されています。パフォーマンス上の理由により、一部のエッジでは、limit値に上限を設けている場合があります。いずれの場合でも、APIから正しくページ分割されたリンクが返されます。
• next: データの次ページを返すグラフAPIエンドポイントです。含まれていない場合、これがデータの最終ページになります。ページ分割と可視性やプライバシーとの関係よって、空のページにnextページングリンクが含まれている場合があります。nextリンクが表示されなくなったら、ページ送りをストップしてください。
• previous: データの前のページを返すグラフAPIエンドポイントです。含まれていない場合、これはデータの最初のページになります。

ページ分割されているアイテムリストに新しいオブジェクトが追加されると、オフセットベースの各ページのコンテンツが変わります。

commentsのような、多数のアイテム(数万件に及ぶ可能性がある)が返されるオブジェクトの場合、ページング中に最大数に達する可能性があります。アプリがカーソル上限に達すると、APIからエラーが返されます。

{
  "error": {
    "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint",
    "type": "OAuthException",
    "code": 100
  }
}

次のステップ

これで、グラフAPIに関する理解が深まりました。次は、グラフエクスプローラツールガイドでコードの作成を必要としないグラフについて調べるか、一般的な用途にアクセスしてよく実行されるタスクを見るか、使用可能なSDKを確認してください。