Bestimmte Felder zurückgeben

Verwenden Sie den fields-Systemparameter in Ihrem Methodenaufruf, um genau die Felder zurückzugeben, die Sie benötigen, und die Leistung zu verbessern.

In diesem Dokument wird beschrieben, wie Sie den Parameter fields in Google Drive verwenden.

Funktionsweise des Parameters „fields“

Der Parameter fields verwendet eine FieldMask für die Antwortfilterung. Mit Feldmasken wird eine Teilmenge von Feldern angegeben, die in einer Anfrage zurückgegeben werden sollen. Mit Feldmasken lässt sich verhindern, dass unnötige Daten angefordert werden, was wiederum hilft, unnötige Verarbeitungszeiten zu vermeiden.

Wenn Sie den Parameter fields nicht angeben, gibt der Server eine Standardgruppe von Feldern zurück, die für die Methode spezifisch sind. Die Methode list für die Methode files gibt beispielsweise nur die Felder kind, id, name und mimeType zurück. Die Methode get für die Ressource permissions gibt einen anderen Satz von Standardfeldern zurück.

Für alle Methoden der Ressourcen about, comments (außer delete) und replies (außer delete) muss der Parameter fields festgelegt werden. Bei diesen Methoden wird kein Standardsatz von Feldern zurückgegeben.

Nachdem ein Server eine gültige Anfrage verarbeitet hat, die den Parameter fields enthält, gibt er einen Statuscode HTTP 200 OK zusammen mit den angeforderten Daten zurück. Wenn der Parameter „fields“ einen Fehler enthält oder ungültig ist, gibt der Server den Statuscode HTTP 400 Bad Request zusammen mit einer Fehlermeldung zurück, die angibt, was bei Ihrer Feldauswahl falsch ist. Beispiel: files.list(fields='files(id,capabilities,canAddChildren)') führt zu einem Fehler vom Typ „Invalid field selection canAddChildren“. Der richtige Parameter „fields“ für dieses Beispiel ist files.list(fields='files(id,capabilities/canAddChildren)').

Informationen zu den Feldern, die Sie mit dem Parameter fields zurückgeben können, finden Sie auf der Dokumentationsseite der Ressource, die Sie abfragen. Wenn Sie beispielsweise sehen möchten, welche Felder für eine Datei zurückgegeben werden können, lesen Sie die Dokumentation zur files-Ressource. Weitere dateispezifische Suchbegriffe finden Sie unter Suchbegriffe und Operatoren.

Formatierungsregeln für Feldparameter

Das Format des Anfrageparameters „fields“ basiert grob auf der XPath-Syntax. Im Folgenden finden Sie Formatierungsregeln für den Parameter fields. In allen diesen Regeln werden Beispiele für die files.get-Methode verwendet.

  • Mit einer durch Kommas getrennten Liste kannst du mehrere Felder auswä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 ein untergeordnetes Auswahlzeichen, um eine Reihe von untergeordneten Feldern von Arrays oder Objekten anzufordern, indem Sie Ausdrücke in Klammern „()“ setzen. Beispiel: 'permissions(id)' gibt nur die Berechtigungs-ID für jedes Element im Array „permissions“ zurück.

  • Wenn Sie alle Felder in einem Objekt zurückgeben möchten, verwenden Sie ein Sternchen (*) als Platzhalter in der Feldauswahl. Mit 'permissions/permissionDetails/*' werden beispielsweise alle verfügbaren Felder mit Berechtigungsdetails pro Berechtigung ausgewählt. Die Verwendung des Platzhalters kann sich negativ auf die Leistung der Anfrage auswirken.

Anfrage

In diesem Beispiel stellen wir den Pfadparameter „fileId“ und mehrere Felder als Abfrageparameter in der Anfrage bereit. Die Antwort gibt die Feldwerte für die Datei-ID zurück.

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 sich ein Feld auf eine andere Ressource bezieht, können Sie angeben, welche Felder der verschachtelten Ressource abgerufen werden sollen.

Wenn Sie beispielsweise das Feld role (verschachtelte Ressource) der Ressource permissions abrufen möchten, haben Sie folgende Möglichkeiten:

  • permissions.get mit fields=role.
  • permissions.get mit fields=*, um alle permissions-Felder anzuzeigen.
  • files.get mit fields=permissions(role) oder fields=permissions/role.
  • files.get mit fields=permissions, um alle permissions-Felder anzuzeigen.
  • changes.list mit fields=changes(file(permissions(role))).

Wenn Sie mehrere Felder abrufen möchten, verwenden Sie eine durch Kommas getrennte Liste. Beispiel: files.list mit fields=files(id,name,createdTime,modifiedTime,size).

Anfrage

In diesem Beispiel geben wir den Pfadparameter „fileId“ und mehrere Felder, einschließlich bestimmter Felder der verschachtelten Berechtigungsressource, als Abfrageparameter in der Anfrage an. Die Antwort gibt die Feldwerte für die Datei-ID zurück.

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