Bestimmte Felder zurückgeben

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

Der Parameter fields verwendet eine FieldMask für die Antwortfilterung. Mit Feldmasken wird eine Teilmenge der Felder 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.

Standardmäßig gibt der Server eine Reihe von Feldern zurück, die für die abgefragte Ressource spezifisch sind. Die Methode get() für die Ressource files gibt beispielsweise nur id, name und mimeType zurück. Die Methode get() der Ressource permissions gibt eine andere Reihe von Standardfeldern zurück.

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 anderweitig ungültig ist, gibt der Server den Statuscode HTTP 400 Bad Request zusammen mit einer Fehlermeldung zurück, die angibt, was mit der Feldauswahl falsch war. Beispiel: files.list(fields='files(id,capabilities,canAddChildren)') führt zu dem Fehler „Ungültige Feldauswahl canAddChildren“. Der richtige Parameter für „fields“ in diesem Beispiel ist files.list(fields='files(id,capabilities/canAddChildren)').

Welche Felder mit dem Parameter fields zurückgegeben werden können, sehen Sie auf der Dokumentationsseite der abgefragten Ressource. Informationen dazu, welche Felder du beispielsweise für eine Datei zurückgeben kannst, findest du in der files-Ressourcendokumentation.

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. Für alle diese Regeln werden Beispiele aus der 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. Setzen Sie dazu Ausdrücke in Klammern: „()“. Mit 'permissions(id)' wird beispielsweise nur die Berechtigungs-ID für jedes Element im Berechtigungs-Array zurückgegeben.

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

Beispiel ansehen

Anfrage

In diesem Beispiel geben wir den Pfadparameter der Datei-ID und mehrere Felder als Suchparameter 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

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.

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() durch fields=* ersetzen, um alle permissions-Felder anzuzeigen.
  • files.get() durch fields=permissions(role) oder fields=permissions/role.
  • files.get() durch fields=permissions ersetzen, 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).

Beispiel ansehen

Anfrage

In diesem Beispiel geben wir den Pfadparameter der Datei-ID 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"
    }
  ]
}