クエリ パラメーターを使用して、応答の形式を変更する

  • [アーティクル]

OneDrive API には、応答で返される特定のデータを制御するために使用できる、さまざまなオプションのクエリ パラメーターが用意されています。

このトピックの内容

プロパティを選択する

select クエリ文字列パラメーターを使用して、Items で返されるコンマ区切りのプロパティのリストを提供できます。

例

この例では、アイテムの子を取得するときに返される name プロパティと size プロパティのみを選択します。

GET /drive/root/children?select=name,size

select=name,size クエリ文字列を指定して要求を送信することで、応答内のオブジェクトには、それらのプロパティ値だけが含まれるようになります。 select ステートメントを使用する場合は、ステートメントで返されるすべてのプロパティを指定する必要があります。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "13140a9sd9aba",
      "name": "Documents",
      "size": 1024
    },
    {
      "id": "123901909124a",
      "name": "Pictures",
      "size": 1012010210
    }
  ]
}

コレクションを展開する

OneDrive API 要求では、参照される項目の子コレクションは自動的には展開されません。 これは、ネットワーク トラフィックと、サービスからの応答の生成にかかる時間が短縮されるため、設計上の理由です。 ただし、場合によっては、これらの結果を応答に含めることができます。

expand クエリ文字列パラメーターを使用して、子コレクションを展開しそれらの結果を含めるよう OneDrive API に指示できます。

たとえば、ルート ドライブ情報とドライブの最上位レベルのアイテムを取得するには、次の例に示すように、expand パラメーターを使用します。 またこの例では、子アイテムの id および name プロパティだけを返すために、select ステートメントも使用しています。

GET /drive/root?expand=children(select=id,name)

この要求は、子コレクションを展開して、コレクションのアイテムを返します。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "12312312541",
  "name": "root",
  "size": 218753122201,
  "webUrl": "https://onedrive.live.com/?cid=0f040...",
  "folder": {
    "childCount": 4
  },
  "children": [
    {
      "id": "F04AA961744A809!48443",
      "name": "Applications",
    },
    {
      "id": "F04AA961744A809!92647",
      "name": "Attachments",
    },
    {
      "id": "F04AA961744A809!93269",
      "name": "Balsmiq Sketches",
    },
    {
      "id": "F04AA961744A809!65191",
      "name": "Camera imports",
    }
  ]
}

コレクションを並べ替える

orderby クエリ文字列を使用して、OneDrive API から返されるアイテムの並べ替え順序を制御できます。 アイテムのコレクションの場合は、orderby パラメーターの次のフィールドを使用します。

  • name
  • size
  • lastModifiedDateTime

OneDrive for Business と SharePoint Server 2016 では、orderby クエリ文字列は name および url でのみ機能することに注意してください。

昇順または降順で結果を並べ替えるには、asc または desc のいずれかをスペースで区切ってフィールド名の後に追加します。たとえば次のようにします。?orderby=name%20desc.

たとえば、OneDrive のドライブのルートのコンテンツを最大から最小の順に返すには、/drive/items/root/children?orderby=size%20desc の構文を使用します。

オプションの OData クエリ パラメーター

OneDrive API 要求で使用できるオプションの OData クエリ パラメーターの表を次に示します。

名前 値 ステータス 説明
expand string 使用可能 展開して応答に含める関係を示すコンマ区切りのリスト。 たとえば、フォルダーの子を取得するには expand=children を使用します。
select string 使用可能 応答に含めるプロパティを示すコンマ区切りのリスト。
skipToken string 使用可能 次の結果セットを取得するために使用されるページング トークン。
top int 使用可能 結果セットに返す項目の数。 OneDrive API にはハード制限があり、応答ごとにさらに多くの項目を要求できないことがあります。
orderby string 使用可能 応答コレクション内のアイテムの順序を並べ替えるために使用されるプロパティを示すコンマ区切りのリスト。 、、および フィールドに対namesizeしてlastModifiedDateTime機能します。
filter string 利用不可 一連の条件に基づいて応答をフィルター処理できるフィルター文字列。

注: OData 標準では、これらの用語の前に $ が付いています。 OneDrive API は、特殊文字の有無にかかわらずこれらのクエリ パラメーターの使用をサポートしていますが、要求全体で一貫して、これらの引数に $ 文字を使用する必要があります。