Pobieranie i eksportowanie plików

Interfejs Google Drive API obsługuje kilka rodzajów działań związanych z pobieraniem i eksportowaniem, które są wymienione w tabeli poniżej:

Działania związane z pobieraniem
Zawartość pliku binarnego za pomocą metody files.get z parametrem adresu URL alt=media.
Treść pliku blob w starszej wersji za pomocą metody revisions.get z parametrem adresu URL alt=media.
Zawartość pliku binarnego w przeglądarce za pomocą pola webContentLink.
Treść pliku blob za pomocą metody files.download podczas długotrwałych operacji. To jedyny sposób pobierania plików Google Vids.
Eksportowanie działań
treści dokumentu Google Workspace w formacie obsługiwanym przez aplikację, przy użyciu metody files.export;
treści dokumentu Google Workspace w przeglądarce za pomocą pola exportLinks;
treści dokumentu Google Workspace w starszej wersji w przeglądarce za pomocą pola exportLinks.
treści dokumentów Google Workspace przy użyciu metody files.download podczas długotrwałych operacji.

Zanim pobierzesz lub wyeksportujesz zawartość pliku, sprawdź, czy użytkownicy mogą pobrać plik za pomocą pola capabilities.canDownload w zasobie files.

Opisy wymienionych tutaj typów plików, w tym plików blob i plików Google Workspace, znajdziesz w artykule Typy plików.

W dalszej części tego przewodnika znajdziesz szczegółowe instrukcje wykonywania tych typów działań związanych z pobieraniem i eksportowaniem.

Pobieranie zawartości pliku binarnego

Aby pobrać plik binarny zapisany na Dysku, użyj metody files.get z identyfikatorem pliku do pobrania i parametrem adresu URL alt=media. Parametr adresu URL alt=media informuje serwer, że żądane jest pobranie treści jako alternatywnego formatu odpowiedzi.

Parametr adresu URL alt=media to parametr systemowy dostępny we wszystkich interfejsach API REST Google. Jeśli używasz biblioteki klienta interfejsu Drive API, nie musisz jawnie ustawiać tego parametru.

Poniższy przykładowy kod pokazuje, jak za pomocą metody files.get pobrać plik za pomocą bibliotek klienta interfejsu Drive API.

Java

drive/snippets/drive_v3/src/main/java/DownloadFile.java
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Arrays;

/* Class to demonstrate use-case of drive's download file. */
public class DownloadFile {

  /**
   * Download a Document file in PDF format.
   *
   * @param realFileId file ID of any workspace document format file.
   * @return byte array stream if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static ByteArrayOutputStream downloadFile(String realFileId) throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
          guides on implementing OAuth2 for your application.*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    try {
      OutputStream outputStream = new ByteArrayOutputStream();

      service.files().get(realFileId)
          .executeMediaAndDownloadTo(outputStream);

      return (ByteArrayOutputStream) outputStream;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to move file: " + e.getDetails());
      throw e;
    }
  }
}

Python

drive/snippets/drive-v3/file_snippet/download_file.py
import io

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from googleapiclient.http import MediaIoBaseDownload


def download_file(real_file_id):
  """Downloads a file
  Args:
      real_file_id: ID of the file to download
  Returns : IO object with location.

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create drive api client
    service = build("drive", "v3", credentials=creds)

    file_id = real_file_id

    # pylint: disable=maybe-no-member
    request = service.files().get_media(fileId=file_id)
    file = io.BytesIO()
    downloader = MediaIoBaseDownload(file, request)
    done = False
    while done is False:
      status, done = downloader.next_chunk()
      print(f"Download {int(status.progress() * 100)}.")

  except HttpError as error:
    print(f"An error occurred: {error}")
    file = None

  return file.getvalue()


if __name__ == "__main__":
  download_file(real_file_id="1KuPmvGq8yoYgbfW74OENMCB5H0n_2Jm9")

Node.js

drive/snippets/drive_v3/file_snippets/download_file.js
/**
 * Downloads a file
 * @param{string} realFileId file ID
 * @return{obj} file status
 * */
async function downloadFile(realFileId) {
  // 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});

  fileId = realFileId;
  try {
    const file = await service.files.get({
      fileId: fileId,
      alt: 'media',
    });
    console.log(file.status);
    return file.status;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveDownloadFile.php
<?php
use Google\Client;
use Google\Service\Drive;
function downloadFile()
 {
    try {

      $client = new Client();
      $client->useApplicationDefaultCredentials();
      $client->addScope(Drive::DRIVE);
      $driveService = new Drive($client);
      $realFileId = readline("Enter File Id: ");
      $fileId = '0BwwA4oUTeiV1UVNwOHItT0xfa2M';
      $fileId = $realFileId;
      $response = $driveService->files->get($fileId, array(
          'alt' => 'media'));
      $content = $response->getBody()->getContents();
      return $content;

    } catch(Exception $e) {
      echo "Error Message: ".$e;
    }

}

.NET

drive/snippets/drive_v3/DriveV3Snippets/DownloadFile.cs
using Google.Apis.Auth.OAuth2;
using Google.Apis.Download;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use-case of drive's download file.
    public class DownloadFile
    {
        /// <summary>
        /// Download a Document file in PDF format.
        /// </summary>
        /// <param name="fileId">file ID of any workspace document format file.</param>
        /// <returns>byte array stream if successful, null otherwise.</returns>
        public static MemoryStream DriveDownloadFile(string fileId)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for 
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential
                    .GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                var request = service.Files.Get(fileId);
                var stream = new MemoryStream();

                // Add a handler which will be notified on progress changes.
                // It will notify on each chunk download and when the
                // download is completed or failed.
                request.MediaDownloader.ProgressChanged +=
                    progress =>
                    {
                        switch (progress.Status)
                        {
                            case DownloadStatus.Downloading:
                            {
                                Console.WriteLine(progress.BytesDownloaded);
                                break;
                            }
                            case DownloadStatus.Completed:
                            {
                                Console.WriteLine("Download complete.");
                                break;
                            }
                            case DownloadStatus.Failed:
                            {
                                Console.WriteLine("Download failed.");
                                break;
                            }
                        }
                    };
                request.Download(stream);

                return stream;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

Ta próbka kodu korzysta z metody biblioteki, która dodaje parametr adresu URL alt=media do podstawowego żądania HTTP.

Pobieranie plików rozpoczęte w aplikacji musi być autoryzowane za pomocą zakresu, który umożliwia dostęp do treści pliku w trybie odczytu. Na przykład aplikacja korzystająca z zakresu drive.readonly.metadata nie ma uprawnień do pobierania zawartości pliku. Ten przykładowy kod korzysta z ograniczonego zakresu plików „drive”, który umożliwia użytkownikom wyświetlanie wszystkich plików na Dysku i zarządzanie nimi. Więcej informacji o zakresach Dysku znajdziesz w artykule Wybieranie zakresów interfejsu Google Drive API.

Użytkownicy z uprawnieniami owner (w przypadku plików na Moim dysku) lub organizer (w przypadku plików na dysku współdzielonym) mogą ograniczyć pobieranie za pomocą obiektu DownloadRestrictionsMetadata. Więcej informacji znajdziesz w artykule Uniemożliwianie użytkownikom pobierania, drukowania i kopiowania pliku.

Pliki uznane za nadużycia (np. szkodliwe oprogramowanie) może pobrać tylko właściciel pliku. Dodatkowo należy uwzględnić parametr zapytania getacknowledgeAbuse=true, aby wskazać, że użytkownik zdaje sobie sprawę z ryzyka pobrania potencjalnie niechcianego oprogramowania lub innych szkodliwych plików. Przed użyciem tego parametru zapytania aplikacja powinna interaktywnie ostrzec użytkownika.

Częściowe pobieranie

Pobieranie częściowe polega na pobraniu tylko określonej części pliku. Możesz określić część pliku, którą chcesz pobrać, używając zakresu bajtów z nagłówkiem Range. Na przykład:

Range: bytes=500-999

Pobieranie zawartości pliku binarnego w starszej wersji

Możesz pobrać tylko te wersje plików binarnych, które są oznaczone jako „Zachowaj na zawsze”. Jeśli chcesz pobrać wersję, najpierw ustaw ją na „Zachowaj na zawsze”. Więcej informacji znajdziesz w artykule Określanie wersji, które mają być zapisywane przed automatycznym usunięciem.

Aby pobrać zawartość plików binarnych w starszej wersji, użyj metody revisions.get z identyfikatorem pliku do pobrania, identyfikatorem wersji i parametrem adresu URL alt=media. Parametr URL alt=media informuje serwer, że żądane jest pobranie treści jako alternatywnego formatu odpowiedzi. Podobnie jak w przypadku metody files.get, metoda revisions.get też akceptuje opcjonalny parametr zapytania acknowledgeAbuse i nagłówek Range. Więcej informacji znajdziesz w artykule Zarządzanie długotrwałymi operacjami.

Protokół żądania jest widoczny tutaj.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Pobieranie zawartości pliku binarnego w przeglądarce

Aby pobrać zawartość plików binarnych przechowywanych na Dysku w przeglądarce zamiast za pomocą interfejsu API, użyj pola webContentLink zasobu files. Jeśli użytkownik ma dostęp do pobierania pliku, zwracany jest link do pobrania pliku i jego zawartości. Możesz przekierować użytkownika na ten adres URL lub udostępnić go jako link, który można kliknąć.

Pobieranie zawartości pliku binarnego podczas długotrwałych operacji

Aby pobrać zawartość plików blob podczas długotrwałych operacji, użyj metody files.download z identyfikatorem pliku do pobrania. Opcjonalnie możesz ustawić identyfikator wersji. Jest to jedyny sposób pobierania plików Google Vids. Więcej informacji znajdziesz w artykule Zarządzanie długotrwałymi operacjami.

Eksportowanie treści dokumentu Google Workspace

Aby wyeksportować zawartość bajtową dokumentu Google Workspace, użyj metody files.export z identyfikatorem pliku do wyeksportowania i prawidłowym typem MIME. Eksportowane treści są ograniczone do 10 MB.

Poniższy przykład kodu pokazuje, jak za pomocą metody files.export wyeksportować dokument Google Workspace w formacie PDF przy użyciu bibliotek klienta Drive API:

Java

drive/snippets/drive_v3/src/main/java/ExportPdf.java
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Arrays;

/* Class to demonstrate use-case of drive's export pdf. */
public class ExportPdf {

  /**
   * Download a Document file in PDF format.
   *
   * @param realFileId file ID of any workspace document format file.
   * @return byte array stream if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static ByteArrayOutputStream exportPdf(String realFileId) throws IOException {
    // Load pre-authorized user credentials from the environment.
    // TODO(developer) - See https://developers.google.com/identity for
    // guides on implementing OAuth2 for your application.
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    OutputStream outputStream = new ByteArrayOutputStream();
    try {
      service.files().export(realFileId, "application/pdf")
          .executeMediaAndDownloadTo(outputStream);

      return (ByteArrayOutputStream) outputStream;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to export file: " + e.getDetails());
      throw e;
    }
  }
}

Python

drive/snippets/drive-v3/file_snippet/export_pdf.py
import io

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from googleapiclient.http import MediaIoBaseDownload


def export_pdf(real_file_id):
  """Download a Document file in PDF format.
  Args:
      real_file_id : file ID of any workspace document format file
  Returns : IO object with location

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create drive api client
    service = build("drive", "v3", credentials=creds)

    file_id = real_file_id

    # pylint: disable=maybe-no-member
    request = service.files().export_media(
        fileId=file_id, mimeType="application/pdf"
    )
    file = io.BytesIO()
    downloader = MediaIoBaseDownload(file, request)
    done = False
    while done is False:
      status, done = downloader.next_chunk()
      print(f"Download {int(status.progress() * 100)}.")

  except HttpError as error:
    print(f"An error occurred: {error}")
    file = None

  return file.getvalue()


if __name__ == "__main__":
  export_pdf(real_file_id="1zbp8wAyuImX91Jt9mI-CAX_1TqkBLDEDcr2WeXBbKUY")

Node.js

drive/snippets/drive_v3/file_snippets/export_pdf.js
/**
 * Download a Document file in PDF format
 * @param{string} fileId file ID
 * @return{obj} file status
 * */
async function exportPdf(fileId) {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});

  try {
    const result = await service.files.export({
      fileId: fileId,
      mimeType: 'application/pdf',
    });
    console.log(result.status);
    return result;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveExportPdf.php
<?php
use Google\Client;
use Google\Service\Drive;
function exportPdf()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $realFileId = readline("Enter File Id: ");
        $fileId = '1ZdR3L3qP4Bkq8noWLJHSr_iBau0DNT4Kli4SxNc2YEo';
        $fileId = $realFileId;
        $response = $driveService->files->export($fileId, 'application/pdf', array(
            'alt' => 'media'));
        $content = $response->getBody()->getContents();
        return $content;

    }  catch(Exception $e) {
         echo "Error Message: ".$e;
    }

}

.NET

drive/snippets/drive_v3/DriveV3Snippets/ExportPdf.cs
using Google.Apis.Auth.OAuth2;
using Google.Apis.Download;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use of Drive export pdf
    public class ExportPdf
    {
        /// <summary>
        /// Download a Document file in PDF format.
        /// </summary>
        /// <param name="fileId">Id of the file.</param>
        /// <returns>Byte array stream if successful, null otherwise</returns>
        public static MemoryStream DriveExportPdf(string fileId)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for 
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                var request = service.Files.Export(fileId, "application/pdf");
                var stream = new MemoryStream();
                // Add a handler which will be notified on progress changes.
                // It will notify on each chunk download and when the
                // download is completed or failed.
                request.MediaDownloader.ProgressChanged +=
                    progress =>
                    {
                        switch (progress.Status)
                        {
                            case DownloadStatus.Downloading:
                            {
                                Console.WriteLine(progress.BytesDownloaded);
                                break;
                            }
                            case DownloadStatus.Completed:
                            {
                                Console.WriteLine("Download complete.");
                                break;
                            }
                            case DownloadStatus.Failed:
                            {
                                Console.WriteLine("Download failed.");
                                break;
                            }
                        }
                    };
                request.Download(stream);
                return stream;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

Ten przykładowy kod korzysta z ograniczonego zakresu drive, który umożliwia użytkownikom wyświetlanie wszystkich plików na Dysku i zarządzanie nimi. Więcej informacji o zakresach Dysku znajdziesz w artykule Wybieranie zakresów interfejsu Google Drive API.

Przykładowy kod deklaruje też typ MIME eksportu jako application/pdf. Pełną listę wszystkich typów MIME eksportu obsługiwanych w przypadku poszczególnych dokumentów Google Workspace znajdziesz w artykule Typy MIME eksportu w przypadku dokumentów Google Workspace.

Eksportowanie zawartości dokumentu Google Workspace w przeglądarce

Aby wyeksportować zawartość dokumentu Google Workspace w przeglądarce, użyj pola exportLinks zasobu files. W zależności od typu dokumentu zwracany jest link do pobrania pliku i jego zawartości dla każdego dostępnego typu MIME. Możesz przekierować użytkownika na adres URL lub zaoferować go jako klikalny link.

Eksportowanie treści dokumentu Google Workspace w starszej wersji w przeglądarce

Aby wyeksportować zawartość dokumentu Google Workspace w starszej wersji w przeglądarce, użyj metody revisions.get z identyfikatorem pliku do pobrania i identyfikatorem wersji, aby wygenerować link do eksportu, z którego możesz pobrać plik. Jeśli użytkownik ma dostęp do pobierania pliku, zwracany jest link do pobrania pliku i jego zawartości. Możesz przekierować użytkownika na ten adres URL lub udostępnić go jako link, który można kliknąć.

Eksportowanie treści dokumentów Google Workspace podczas długotrwałych operacji

Aby wyeksportować zawartość dokumentu Google Workspace podczas długotrwałych operacji, użyj metody files.download z identyfikatorem pliku do pobrania i identyfikatorem wersji. Więcej informacji znajdziesz w artykule Zarządzanie długotrwałymi operacjami.

Ograniczanie możliwości udostępniania plików