Dateien erstellen und verwalten

In diesem Leitfaden wird beschrieben, wie Sie mit der Google Drive API Dateien in Google Drive erstellen und verwalten.

Datei erstellen

Wenn Sie in Drive eine Datei mit Inhalten (Medien) erstellen möchten, müssen Sie Dateidaten hochladen. Sie können die Metadaten und den Inhalt einer Datei zusammen in einer einzigen Anfrage hochladen (mehrteiliger Upload) oder nur Medien (einfacher Upload). Weitere Informationen finden Sie unter Dateidaten hochladen.

Wenn Sie eine Datei ohne Metadaten oder Inhalt erstellen möchten, verwenden Sie die create Methode für die files Ressource ohne Parameter.

Wenn Sie die Datei erstellen, gibt die Methode eine files-Ressource zurück. Die Datei erhält die kind-Angabe drive.file, eine id, den name „Unbenannt“ und den mimeType application/octet-stream. The uploadType ist als erforderlich gekennzeichnet, hat aber standardmäßig den Wert media. Sie müssen ihn also nicht angeben.

Weitere Informationen zu den Dateilimits in Drive finden Sie unter Datei- und Ordnerlimits.

In den folgenden Codebeispielen wird gezeigt, wie Sie eine Datei ohne Metadaten oder Inhalt erstellen:

Node.js

/**
 * Create an empty file.
 * @return {string} The created file's ID.
 */
async function createEmptyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.create({});
    console.log('File ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

Ersetzen Sie Folgendes:

  • ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Parameter „fields“ verwenden

Wenn Sie die Felder angeben möchten, die in der Antwort zurückgegeben werden sollen, können Sie den fields System parameter mit einer beliebigen Methode der files Ressource festlegen. Wenn Sie den Parameter fields weglassen, gibt der Server eine Standardgruppe von Feldern zurück, die für die Methode spezifisch sind. Die Methode list gibt beispielsweise nur die Felder kind, id, name, mimeType und resourceKey für jede Datei zurück. Informationen zum Zurückgeben anderer Felder finden Sie unter Bestimmte Felder zurückgeben.

Dateieigentümerschaft

Wenn eine Datei mit der Drive API erstellt wird, hängt die Eigentümerschaft von den Authentifizierungsanmeldedaten ab, die von der App verwendet werden:

  • Nutzerkonto (OAuth 2.0): Wenn die Anwendung im Namen eines Nutzers authentifiziert wird, wird dieser Nutzer zum Dateieigentümer. Die Datei befindet sich dann im Ordner „Meine Ablage“ oder in einem angegebenen Ordner. Sie verbraucht das Speicherkontingent des Nutzers.

  • Dienstkonto: Wenn die Anwendung mit einem Dienstkonto authentifiziert wird, ist das Dienstkonto der Dateieigentümer. Die Datei befindet sich dann im dedizierten Drive-Speicherplatz des Dienstkontos. Dateien werden nicht in anderen Drive-Speicherplätzen angezeigt, es sei denn, sie wurden explizit freigegeben. Wenn das Dienstkonto gelöscht wird, werden alle Dateien, deren Eigentümer es ist, sofort gelöscht.

    Wenn Sie ein Dienstkonto verwenden, aber möchten, dass ein bestimmtes Nutzerkonto Eigentümer einer Datei ist, verwenden Sie die domainweite Delegation. So kann das Dienstkonto die Identität eines Nutzers annehmen und in seinem Namen Dateien erstellen. Weitere Informationen finden Sie unter Domainweite Befugnisse an das Dienstkonto delegieren.

Weitere Informationen zu Dateiberechtigungen finden Sie unter Dateien, Ordner und Ablagen freigeben.

IDs für Ihre Dateien generieren

Mit der generateIds Methode für die files Ressource können Sie eindeutige Datei IDs vorab generieren, die beim Erstellen oder Kopieren von Dateien und Ordnern in Drive verwendet werden können. Das kann nützlich sein, wenn Sie die Datei-IDs über Ihre App steuern möchten, anstatt sie automatisch von Drive zuweisen zu lassen.

Mit dem count Abfrageparameter können Sie die Anzahl der generierten IDs festlegen. Wenn count nicht festgelegt ist, werden standardmäßig 10 zurückgegeben. Die maximale Anzahl der IDs, die Sie anfordern können, ist auf 1.000 begrenzt.

Sie können auch den space angeben, in dem die IDs verwendet werden können, und den type der Elemente, für die die IDs verwendet werden können.

Sobald eine ID generiert wurde, kann sie über das Feld id an die Methode create oder copy übergeben werden. So wird sichergestellt, dass die erstellte oder kopierte Datei die vorgegebene ID verwendet.

Wenn die Datei erfolgreich erstellt oder kopiert wurde, geben nachfolgende Wiederholungen den HTTP-Statuscode 409 Conflict zurück und es werden keine doppelten Dateien erstellt.

Vorab generierte IDs werden für die Erstellung von Google Workspace-Dateien nicht unterstützt, mit Ausnahme der application/vnd.google-apps.drive-sdk und application/vnd.google-apps.folder MIME Typen. Ebenso werden Uploads, die auf eine Konvertierung in ein Google Workspace-Dateiformat verweisen, nicht unterstützt.

In den folgenden Codebeispielen wird gezeigt, wie Sie eindeutige Datei-IDs vorab generieren:

Node.js

/**
 * Pre-generate unique file IDs.
 */
async function generateFileIds() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.generateIds({
      count: 10,
      space: 'drive'
    });
    const ids = response.data.ids;
    console.log('Generated IDs:');
    for (const id of ids) {
      console.log(id);
    }
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl 'https://www.googleapis.com/drive/v3/files/generateIds?count=10&space=drive' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

Ersetzen Sie Folgendes:

  • ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Dateien nur mit Metadaten erstellen

Dateien nur mit Metadaten enthalten keinen Inhalt. Metadaten sind Daten (z. B. name, mimeType und createdTime), die die Datei beschreiben. Felder wie name sind nutzerunabhängig und für alle Nutzer gleich, während Felder wie viewedByMeTime nutzerspezifische Werte enthalten.

Ein Beispiel für eine Datei nur mit Metadaten ist ein Ordner mit dem MIME-Typ application/vnd.google-apps.folder. Weitere Informationen finden Sie unter Ordner erstellen und füllen. Ein weiteres Beispiel ist eine Verknüpfung zu einer anderen Datei in Drive mit dem MIME-Typ application/vnd.google-apps.shortcut. Weitere Informationen finden Sie unter Verknüpfung zu einer Drive-Datei erstellen.

Thumbnails verwalten

Thumbnails helfen Nutzern, Drive-Dateien zu identifizieren. Drive kann automatisch Thumbnails für gängige Dateitypen generieren. Sie können aber auch ein von Ihrer App generiertes Thumbnail bereitstellen. Weitere Informationen finden Sie unter Thumbnails hochladen.

Vorhandene Datei kopieren

Wenn Sie eine Datei kopieren und alle angeforderten Aktualisierungen anwenden möchten, verwenden Sie die copy Methode für die files Ressource. Verwenden Sie die list Methode, um die zu kopierende fileId zu finden.

Sie können Aktualisierungen mit Patch-Semantik anwenden. Das bedeutet, dass Sie teilweise Änderungen an einer Ressource vornehmen können. Sie müssen die Felder, die Sie ändern möchten, explizit in Ihrer Anfrage festlegen. Alle Felder, die nicht in der Anfrage enthalten sind, behalten ihre vorhandenen Werte bei. Weitere Informationen finden Sie unter Mit Teilressourcen arbeiten.

Sie können die Datei-ID der kopierten Datei mit der generateIds Methode voreinstellen. Weitere Informationen finden Sie unter IDs für Ihre Dateien generieren.

Sie müssen einen geeigneten Drive API Bereich verwenden, um den Aufruf zu autorisieren. Weitere Informationen zu Drive-Bereichen finden Sie unter Google Drive API-Bereiche auswählen.

In den folgenden Codebeispielen wird gezeigt, wie Sie eine Datei kopieren und ihren Namen aktualisieren:

Node.js

/**
 * Copy an existing file.
 * @return {string} The copied file's ID.
 */
async function copyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.copy({
      fileId: 'FILE_ID',
      requestBody: {
        name: 'FILE_COPY_NAME'
      }
    });
    console.log('Copied file ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

Ersetzen Sie Folgendes:

  • FILE_ID: Die ID der zu kopierenden Datei.
  • FILE_COPY_NAME: Der Name der neuen Datei.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/copy' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "name": "FILE_COPY_NAME"
 }'

Ersetzen Sie Folgendes:

  • FILE_ID: Die ID der zu kopierenden Datei.
  • ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.
  • FILE_COPY_NAME: Der Name der neuen Datei.

Kommentare kopieren

Wenn Sie Kommentare und Vorschläge kopieren möchten, wenn Sie eine Google Docs-, Google Sheets- oder Google Präsentationen-Datei kopieren, legen Sie den copyComments Abfrage parameter auf true fest. Drive kopiert nur offene Kommentare (nicht gelöste Kommentare). Bei anderen Dateitypen ignoriert Drive diesen Parameter.

Weitere Informationen zu Berechtigungen, Kommentarzuschreibung und Zugriffs überlegungen finden Sie unter Einschränkungen und Überlegungen.

Einschränkungen und Überlegungen

Beachten Sie beim Kopieren von Dateien die folgenden Einschränkungen und Überlegungen:

  • Berechtigungen:

    • Das DownloadRestrictionsMetadata Objekt der files Ressource bestimmt wer die Datei kopieren kann. Weitere Informationen finden Sie unter Verhindern, dass Nutzer Ihre Datei herunterladen, drucken oder kopieren.
    • Das capabilities.canCopy Feld der Ressource bestimmt, ob der Nutzer eine Datei kopieren kann. Weitere Informationen finden Sie unter Informationen zu Dateifunktionen.
    • Wenn Sie Kommentare kopieren möchten, müssen Sie die Berechtigung haben, Kommentare in der Quelldatei zu lesen. Wenn Sie keine Berechtigung zum Lesen von Kommentaren haben und copyComments auf true setzen, wird der Kopiervorgang trotzdem ausgeführt, aber Kommentare werden nicht kopiert.
    • Durch das Kopieren von Kommentaren erhalten die ursprünglichen Kommentatoren keinen Zugriff auf die neue Datei. Die Access Control Lists (ACLs) der neuen Datei sind unabhängig von den ACLs der Quelldatei.
    • Der Nutzer, der die Kopie erstellt hat, ist Eigentümer der kopierten Datei. Keine anderen Freigabeeinstellungen aus der Quelldatei werden repliziert. Wenn die Kopie in einem freigegebenen Ordner erstellt wird, übernimmt sie die Berechtigungen dieses Ordners.
    • Die Eigentümerschaft einer kopierten Datei kann sich ändern und die Kopie übernimmt möglicherweise nicht die Freigabeeinstellungen der Originaldatei. Diese Einstellungen müssen möglicherweise zurückgesetzt werden.

  • Dateiverwaltung:

    • Einige Dateien, z. B. Verknüpfungen von Drittanbietern, können nie kopiert werden.
    • Sie können eine Datei nur in einen übergeordneten Ordner kopieren. Die Angabe mehrerer übergeordneter Ordner wird nicht unterstützt. Wenn das parents Feld nicht angegeben ist, übernimmt die Datei alle erkennbaren übergeordneten Ordner aus der Quelldatei.
    • Obwohl ein Ordner ein Dateityp ist, können Sie keinen Ordner kopieren. Erstellen Sie stattdessen einen Zielordner und legen Sie das Feld parents der vorhandenen Dateien auf den Zielordner fest. Anschließend können Sie den ursprünglichen Quellordner löschen.
    • Wenn kein neuer Dateiname angegeben wird, erstellt die Methode copy eine Datei mit demselben Namen wie das Original.
    • Eine übermäßige Verwendung von copy kann dazu führen, dass die Kontingentlimits der Drive API überschritten werden. Weitere Informationen finden Sie unter Nutzungs limits.

Hier sind einige nächste Schritte, die Sie ausprobieren können: