Dateimetadaten verwalten

In diesem Dokument werden wichtige Aspekte zum Benennen von Dateien und zum Arbeiten mit Metadaten wie indexierbarem Text und Thumbnails behandelt. Informationen zum Einfügen und Abrufen von Dateien finden Sie in der files-Ressource.

Dateinamen und ‑erweiterungen angeben

Apps müssen beim Einfügen von Dateien mit der Google Drive API eine Dateiendung in der Titeleigenschaft angeben. Für einen Vorgang zum Einfügen einer JPEG-Datei sollte beispielsweise "name": "cat.jpg" in den Metadaten angegeben werden.

Nachfolgende GET-Antworten können die schreibgeschützte Property fileExtension enthalten, die mit der Erweiterung ausgefüllt ist, die ursprünglich in der Property name angegeben wurde. Wenn ein Google Drive-Nutzer den Download einer Datei anfordert oder die Datei über den Synchronisierungsclient heruntergeladen wird, erstellt Google Drive anhand des Titels einen vollständigen Dateinamen (mit Erweiterung). Wenn die Erweiterung fehlt, versucht Google Drive, sie anhand des MIME-Typs der Datei zu ermitteln.

Indexierbaren Text speichern

Drive indexiert Dokumente automatisch für die Suche, wenn der Dateityp erkannt wird. Dazu gehören Textdokumente, PDFs, Bilder mit Text und andere gängige Dateitypen. Wenn Ihre App andere Dateitypen speichert (z. B. Zeichnungen, Videos und Verknüpfungen), können Sie die Auffindbarkeit verbessern, indem Sie im Feld contentHints.indexableText der Datei indexierbaren Text angeben.

Indexierbarer Text wird als HTML indexiert. Wenn Sie den indexierbaren Textstring <section attribute="value1">Here's some text</section> speichern, wird „Hier ist ein Text“ indexiert, „Wert1“ jedoch nicht. Aus diesem Grund ist es nicht so nützlich, XML als indexierbaren Text zu speichern wie HTML.

Beachten Sie bei der Angabe von indexableText Folgendes:

  • Die maximale Größe für contentHints.indexableText beträgt 128 KB.
  • Erfassen Sie die wichtigsten Begriffe und Konzepte, nach denen Nutzer wahrscheinlich suchen werden.
  • Versuchen Sie nicht, Text nach Wichtigkeit zu sortieren, da dies der Indexer effizient für Sie erledigt.
  • Ihre Anwendung sollte den indexierbaren Text bei jedem Speichern aktualisieren.
  • Der Text muss sich auf den Inhalt oder die Metadaten der Datei beziehen.

Dieser letzte Punkt mag offensichtlich erscheinen, ist aber wichtig. Es ist keine gute Idee, häufig gesuchte Begriffe hinzuzufügen, um eine Datei in den Suchergebnissen zu platzieren. Das kann Nutzer frustrieren und sie sogar dazu motivieren, die Datei zu löschen.

Thumbnails hochladen

In Google Drive werden automatisch Miniaturansichten für viele gängige Dateitypen wie Google Docs, Google Tabellen und Google Präsentationen erstellt. Miniaturansichten helfen Nutzern, Drive-Dateien besser zu erkennen.

Für Dateitypen, für die in Google Drive keine Standardminiaturansicht generiert werden kann, können Sie eine von Ihrer Anwendung generierte Miniaturansicht bereitstellen. Lade beim Erstellen oder Aktualisieren einer Datei ein Thumbnail hoch, indem du das Feld contentHints.thumbnail der Ressource files festlegst.

Im Detail:

  • Legen Sie das Feld contentHints.thumbnail.image auf das URL- und Dateinamen-sichere Base64-codierte Bild fest (siehe RFC 4648 Abschnitt 5).
  • Lege im Feld contentHints.thumbnail.mimeType den entsprechenden MIME-Typ für das Thumbnail fest.

Wenn Google Drive ein Thumbnail aus der Datei generieren kann, wird das automatisch generierte Thumbnail verwendet und alle von Ihnen hochgeladenen Thumbnails werden ignoriert. Wenn keine Miniaturansicht generiert werden kann, wird die von dir bereitgestellte verwendet.

Für Thumbnails gelten folgende Regeln:

  • Sie können im PNG-, GIF- oder JPG-Format hochgeladen werden.
  • Die empfohlene Breite beträgt 1.600 Pixel.
  • Die Mindestbreite beträgt 220 Pixel.
  • Die maximale Dateigröße beträgt 2 MB.
  • Sie sollten von Ihrer Anwendung bei jedem Speichern aktualisiert werden.

Weitere Informationen finden Sie in der Ressource files.

Miniaturansichten abrufen

Sie können Metadaten, einschließlich Miniaturansichten, für Drive-Dateien abrufen. Informationen zu Thumbnails befinden sich im Feld thumbnailLink der Ressource files.

Ein bestimmtes Thumbnail zurückgeben

Das folgende Codebeispiel zeigt eine files.get-Methodeanfrage mit mehreren Feldern als Abfrageparameter, um die thumbnailLink-Metadaten für eine bestimmte Datei zurückzugeben. Weitere Informationen finden Sie unter Bestimmte Felder für eine Datei zurückgeben.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

Ersetzen Sie FILE_ID durch das fileId der Datei, die Sie finden möchten.

Sofern verfügbar, gibt die Anfrage eine kurzlebige URL zum Thumbnail der Datei zurück. Der Link ist in der Regel mehrere Stunden lang gültig. Das Feld wird nur ausgefüllt, wenn die anfragende App auf den Inhalt der Datei zugreifen kann. Wenn die Datei nicht öffentlich freigegeben ist, muss die in thumbnailLink zurückgegebene URL mit einer Anfrage mit Anmeldedaten abgerufen werden.

Liste der Thumbnails zurückgeben

Das folgende Codebeispiel zeigt eine files.list-Methodeanfrage mit mehreren Feldern als Suchparameter, um die thumbnailLink-Metadaten für eine Liste von Dateien zurückzugeben. Weitere Informationen finden Sie unter Nach Dateien und Ordnern suchen.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

Wenn Sie die Suchergebnisse auf einen bestimmten Dateityp beschränken möchten, können Sie einen Suchstring anwenden, um den MIME-Typ festzulegen. Im folgenden Codebeispiel wird beispielsweise gezeigt, wie Sie die Liste auf Google Tabellen-Dateien beschränken. Weitere Informationen zu MIME-Typen finden Sie unter Von Google Workspace und Google Drive unterstützte MIME-Typen.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)