Verwenden von Abfrageparametern zum Ändern der Form einer Antwort

Artikel
04/08/2023

Die OneDrive-API bietet mehrere optionale Abfrageparameter, mit denen die spezifischen Daten gesteuert werden können, die in einer Antwort zurückgegeben werden.

In diesem Thema wird Folgendes behandelt:

Auswählen von Eigenschaften
Erweitern von Sammlungen
Sortieren von Sammlungen

Auswählen von Eigenschaften

Mithilfe des Abfragezeichenfolgenparameters select können Sie eine kommagetrennte Liste von Eigenschaften angeben, die für Elemente zurückgegeben werden sollen.

Beispiel

In diesem Beispiel werden nur die Eigenschaftenname und size zur Rückgabe ausgewählt, wenn die untergeordneten Elemente eines Elements abgerufen werden.

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

Wenn Sie die Anforderung mit der Abfragezeichenfolge select=name,size senden, enthalten die Objekte in der Antwort nur diese Eigenschaftswerte. Wenn Sie die select-Anweisung verwenden, müssen Sie alle zurückzugebenden Eigenschaften in der Anweisung angeben.

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

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

Erweitern von Sammlungen

In Anforderungen der OneDrive-API werden untergeordnete Sammlungen von referenzierten Elementen nicht automatisch erweitert. Dies ist beabsichtigt, da so der Netzwerkdatenverkehr und die Zeit zum Generieren einer Antwort vom Dienst reduziert werden. Möglicherweise möchten Sie jedoch in einigen Fällen diese Ergebnisse in einer Antwort einbeziehen.

Sie können den Abfragezeichenfolgenparameter expand verwenden, um die OneDrive-API anzuweisen, eine untergeordnete Sammlung zu erweitern und diese Ergebnisse einzuschließen.

Wenn Sie beispielsweise die Stammlaufwerksinformationen und die Elemente auf der obersten Ebene eines Laufwerks abrufen möchten, verwenden Sie den Parameter expand wie im folgenden Beispiel gezeigt. In diesem Beispiel wird auch eine select-Anweisung verwendet, um nur die Eigenschaftenid und name der untergeordneten Elemente zurückzugeben.

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

Die Anforderung gibt die Sammlungselemente mit der erweiterten untergeordneten Sammlung zurück.

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",
    }
  ]
}

Sortieren von Sammlungen

Verwenden Sie zum Steuern der Sortierreihenfolge der von der OneDrive-API zurückgegebenen Elemente die Abfragezeichenfolge orderby. Verwenden Sie für eine Sammlung von Elementen die folgenden Felder im Parameter orderby.

name
size
lastModifiedDateTime

Beachten Sie, dass in OneDrive for Business und SharePoint Server 2016 die Abfragezeichenfolge orderby nur mit name und url funktioniert.

Wenn Sie die Ergebnisse in aufsteigender oder absteigender Reihenfolge sortieren möchten, fügen Sie entweder asc oder desc an den Namen des Felds getrennt durch ein Leerzeichen an, z. B. ?orderby=name%20desc.

Beispiel: Um den Inhalt des Stammverzeichnisses eines Laufwerks in OneDrive vom größten zum kleinsten Element sortiert zurückzugeben, verwenden Sie folgende Syntax: /drive/items/root/children?orderby=size%20desc.

Optionale OData-Abfrageparameter

Es folgt eine Tabelle mit optionalen OData-Abfrageparametern, die Sie in Ihren OneDrive-API-Anforderungen verwenden können.

Name	Wert	Status	Beschreibung
expand	string	Verfügbar	Durch Trennzeichen getrennte Liste der Beziehungen, die erweitert und in die Antwort eingeschlossen werden sollen. Zum Abrufen der untergeordneten Elemente eines Ordners verwenden Sie z. B. `expand=children`.
select	string	Verfügbar	Durch Trennzeichen getrennte Liste der Eigenschaften, die in die Antwort eingeschlossen werden sollen.
skipToken	string	Verfügbar	Pagingtoken, das zum Abrufen des nächsten Resultsets verwendet wird.
top	Int	Verfügbar	Die Anzahl der Elemente, die in einem Resultset zurückgegeben werden sollen. Die OneDrive-API hat möglicherweise eine feste Einschränkung, die die Anforderung von mehr Elementen pro Antwort verhindert.
orderby	string	Verfügbar	Durch Trennzeichen getrennte Liste von Eigenschaften, die zum Sortieren der Elemente in der Antwortsammlung verwendet werden. Kann für die Felder `name`, `size` und `lastModifiedDateTime` verwendet werden.
filter	string	Nicht verfügbar	Filterzeichenfolge, mit der Sie die Antwort basierend auf einer Reihe von Kriterien filtern können.

Hinweis: Die OData-Norm stellt diesen Begriffen das Präfix $ voran. Die OneDrive-API unterstützt die Verwendung dieser Abfrageparameter mit dem oder ohne das Sonderzeichen, Sie müssen das Zeichen $ jedoch innerhalb der Anforderung konsistent für diese Argumente verwenden.

Freigeben über