Bestimmte Felder einer Datei zurückgeben

Um genau die Felder zurückzugeben, die Sie benötigen, und um die Leistung zu verbessern, verwenden Sie den Abfrageparameter fields in Ihrem Methodenaufruf.

Standardmäßig sendet der Server eine Reihe von Feldern zurück, die für die abgefragte Ressource spezifisch sind. So gibt die Methode files.get möglicherweise nur id, name und mimeType für die Ressource files zurück. Die Methode permissions.get gibt andere Standardfelder für eine permissions-Ressource zurück.

Nachdem ein Server eine gültige Anfrage verarbeitet hat, die den Abfrageparameter fields enthält, sendet er den Statuscode HTTP 200 OK zusammen mit den angeforderten Daten zurück. Wenn der Abfrageparameter „fields“ einen Fehler enthält oder ungültig ist, gibt der Server den Statuscode HTTP 400 Bad Request zusammen mit einer Fehlermeldung zurück, aus der hervorgeht, was bei der Feldauswahl nicht stimmt. Beispiel: files.list(fields='files(id,capabilities,canAddChildren)') verursacht die Fehlermeldung „Ungültige Feldauswahl kannAddChildren“. Der richtige Abfrageparameter für Felder in diesem Beispiel ist files.list(fields='files(id,capabilities/canAddChildren)').

Rufen Sie die Dokumentationsseite der von Ihnen abgefragten Ressource auf, um die Felder zu ermitteln, die Sie mit dem Parameter fields zurückgeben können. Informationen dazu, welche Felder Sie für eine Datei zurückgeben können, finden Sie in der Dokumentation zu files-Ressourcen.

Formatierungsregeln für Feldparameter

Das Format des Feldanfrageparameters basiert grob auf der XPath-Syntax. Für den Parameter fields gelten folgende Formatierungsregeln. Alle diese Regeln verwenden Beispiele in Bezug auf die Methode files.get.

  • Verwenden Sie eine durch Kommas getrennte Liste, um mehrere Felder auszuwählen, z. B. 'name, mimeType'.

  • Verwenden Sie a/b, um das Feld b auszuwählen, das im Feld a verschachtelt ist, z. B. 'capabilities/canDownload'. Weitere Informationen finden Sie unter Felder einer verschachtelten Ressource abrufen.

  • Verwenden Sie eine Unterauswahl, um eine Reihe bestimmter Unterfelder von Arrays oder Objekten anzufordern. Setzen Sie dazu Ausdrücke in Klammern „()“. 'permissions(id)' gibt beispielsweise nur die Berechtigungs-ID für jedes Element im Berechtigungsarray zurück.

  • Wenn alle Felder in einem Objekt zurückgegeben werden sollen, verwenden Sie bei der Feldauswahl ein Sternchen als Platzhalter. Beispielsweise wählt 'permissions/permissionDetails/*' alle verfügbaren Felder mit Berechtigungsdetails pro Berechtigung aus. Die Verwendung dieses Platzhalters kann negative Auswirkungen auf die Leistung der Anfrage haben.

Beispiel ansehen

Anfrage

In diesem Beispiel stellen wir in der Anfrage den Parameter für den Datei-ID-Pfad und mehrere Felder als Abfrageparameter bereit. In der Antwort werden die Feldwerte für die Datei-ID zurückgegeben.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

Antwort

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

Felder einer verschachtelten Ressource abrufen

Wenn ein Feld auf eine andere Ressource verweist, können Sie angeben, welche Felder der verschachtelten Ressource abgerufen werden sollen.

Um beispielsweise das Feld role (verschachtelte Ressource) der Ressource permissions abzurufen, verwenden Sie eine der folgenden Optionen:

  • permissions.get mit fields=role oder fields=*.
  • files.get mit fields=permissions(role) oder fields=permissions/role.
  • files.get mit fields=permissions, um alle Felder der verschachtelten Ressource zu implizieren.
  • changes.list mit fields=changes(file(permissions(role))).

Verwenden Sie eine durch Kommas getrennte Liste, um mehrere Felder abzurufen. Beispiel: files.list mit fields=files(id,name,createdTime,modifiedTime,size).

Beispiel ansehen

Anfrage

In diesem Beispiel stellen wir den Parameter für den Datei-ID-Pfad und mehrere Felder, einschließlich bestimmter Felder der verschachtelten Berechtigungsressource, als Abfrageparameter in der Anfrage bereit. In der Antwort werden die Feldwerte für die Datei-ID zurückgegeben.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

Antwort

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}