Tworzenie plików i zarządzanie nimi

Z tego przewodnika dowiesz się, jak tworzyć pliki na Dysku Google i nimi zarządzać za pomocą interfejsu Google Drive API.

Utwórz plik

Aby utworzyć na Dysku plik zawierający treści (multimedia), musisz przesłać dane pliku. Możesz przesłać metadane i zawartość pliku razem w jednym żądaniu (przesyłanie wieloczęściowe) lub przesłać tylko multimedia (proste przesyłanie). Więcej informacji znajdziesz w artykule Przesyłanie danych pliku.

Aby utworzyć plik, który nie zawiera metadanych ani treści, użyj metody create w zasobie files bez parametrów.

Gdy utworzysz plik, metoda zwróci zasób files. Plik otrzyma kind o wartości drive.file, id, name o wartości „Bez tytułu” i mimeType o wartości application/octet-stream. uploadType jest oznaczone jako wymagane, ale domyślnie ma wartość media, więc nie musisz go podawać.

Więcej informacji o limitach plików na Dysku znajdziesz w artykule Limity plików i folderów.

Poniższe przykłady kodu pokazują, jak utworzyć plik bez metadanych i treści:

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'

Zastąp te elementy:

  • ACCESS_TOKEN: token OAuth 2.0 Twojej aplikacji.

Używanie parametru fields

Jeśli chcesz określić pola, które mają być zwracane w odpowiedzi, możesz ustawić fields parametr systemowy w dowolnej metodzie zasobu files. Jeśli pominiesz parametr fields, serwer zwróci domyślny zestaw pól właściwy dla danej metody. Na przykład metoda list zwraca tylko pola kind, id, name, mimeType i resourceKey dla każdego pliku. Aby zwrócić inne pola, zobacz Zwracanie określonych pól.

Własność pliku

Gdy plik jest tworzony za pomocą interfejsu Drive API, własność zależy od danych logowania używanych przez aplikację w następujący sposób:

  • Konto użytkownika (OAuth 2.0): jeśli aplikacja uwierzytelnia się w imieniu użytkownika, staje się on właścicielem pliku. Plik znajduje się wtedy w folderze Mój dysk lub w określonym folderze. Zużywa on limit miejsca na dane użytkownika.

  • Konto usługi: jeśli aplikacja uwierzytelnia się za pomocą konta usługi, to konto usługi jest właścicielem pliku. Plik znajduje się wtedy w dedykowanym miejscu na Dysku konta usługi. Pliki nie są widoczne na innych kontach miejsca na Dysku, chyba że zostaną udostępnione. Jeśli konto usługi zostanie usunięte, wszystkie pliki, których jest właścicielem, zostaną natychmiast usunięte.

    Jeśli używasz konta usługi, ale chcesz, aby plik był własnością konkretnego konta użytkownika, użyj przekazywania dostępu w całej domenie. Umożliwia to kontu usługi podszywanie się pod użytkownika i tworzenie plików w jego imieniu. Więcej informacji znajdziesz w artykule Przekazywanie kontu usługi uprawnień do całej domeny.

Więcej informacji o uprawnieniach do plików znajdziesz w artykule Udostępnianie plików, folderów i dysków.

Generowanie identyfikatorów do użycia z plikami

Metoda generateIds w zasobie files umożliwia wstępne wygenerowanie unikalnych identyfikatorów plików , których można używać podczas tworzenia lub kopiowania plików i folderów na Dysku. Może to być przydatne, gdy chcesz kontrolować identyfikatory plików z poziomu aplikacji, zamiast pozwalać Dyskowi na automatyczne przypisywanie ich.

Liczbę generowanych identyfikatorów możesz ustawić za pomocą count parametru zapytania. Jeśli parametr count nie jest ustawiony, domyślnie zwracanych jest 10 identyfikatorów. Maksymalna liczba identyfikatorów, o które możesz poprosić, to 1000.

Możesz też określić space w którym można używać identyfikatorów, oraz type elementów, do których można ich używać.

Po wygenerowaniu identyfikatora można go przekazać do metody create lub copy za pomocą pola id. Dzięki temu utworzony lub skopiowany plik będzie używać wcześniej określonego identyfikatora.

Jeśli plik zostanie utworzony lub skopiowany, kolejne próby zwrócą kod stanu HTTP 409 Conflict, a duplikaty plików nie zostaną utworzone.

Pamiętaj, że wstępnie wygenerowane identyfikatory nie są obsługiwane w przypadku tworzenia plików Google Workspace, z wyjątkiem typówapplication/vnd.google-apps.drive-sdk i application/vnd.google-apps.folder MIME. Podobnie nie są obsługiwane przesyłania odwołujące się do konwersji na format pliku Google Workspace.

Poniższe przykłady kodu pokazują, jak wstępnie wygenerować unikalne identyfikatory plików:

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'

Zastąp te elementy:

  • ACCESS_TOKEN: token OAuth 2.0 Twojej aplikacji.

Tworzenie plików zawierających tylko metadane

Pliki zawierające tylko metadane nie zawierają treści. Metadane to dane (np. name, mimeType i createdTime) opisujące plik. Pola takie jak name są niezależne od użytkownika i wyglądają tak samo dla każdego użytkownika, natomiast pola takie jak viewedByMeTime zawierają wartości specyficzne dla użytkownika.

Przykładem pliku zawierającego tylko metadane jest folder o typie MIME application/vnd.google-apps.folder. Więcej informacji znajdziesz w artykule Tworzenie i wypełnianie folderów. Innym przykładem jest skrót wskazujący inny plik na Dysku o typie MIME application/vnd.google-apps.shortcut. Więcej informacji znajdziesz w artykule Tworzenie skrótu do pliku na Dysku.

Zarządzanie miniaturami

Miniatury pomagają użytkownikom identyfikować pliki na Dysku. Dysk może automatycznie generować miniatury popularnych typów plików lub możesz podać miniaturę wygenerowaną przez aplikację. Więcej informacji znajdziesz w artykule Przesyłanie miniatur.

Kopiowanie istniejącego pliku

Aby skopiować plik i zastosować wszelkie żądane aktualizacje, użyj metody copy w zasobie files. Aby znaleźć fileId do skopiowania, użyj metody list.

Aktualizacje możesz stosować za pomocą semantyki poprawek, co oznacza, że możesz wprowadzać częściowe modyfikacje zasobu. W żądaniu musisz wyraźnie ustawić pola, które chcesz zmodyfikować. Wszystkie pola, które nie są uwzględnione w żądaniu, zachowują swoje dotychczasowe wartości. Więcej informacji znajdziesz w artykule Praca z częściowymi zasobami.

Identyfikator pliku skopiowanego możesz ustawić z wyprzedzeniem za pomocą metody generateIds. Więcej informacji znajdziesz w artykule Generowanie identyfikatorów do użycia z plikami.

Pamiętaj, że do autoryzacji wywołania musisz użyć odpowiedniego zakresu interfejsu Drive API. Więcej informacji o zakresach Dysku znajdziesz w artykule Wybieranie zakresów Google Drive API.

Poniższe przykłady kodu pokazują, jak skopiować plik i zaktualizować jego nazwę:

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);
  }
}

Zastąp te elementy:

  • FILE_ID: identyfikator pliku do skopiowania.
  • FILE_COPY_NAME: nazwa nowego pliku.

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

Zastąp te elementy:

  • FILE_ID: identyfikator pliku do skopiowania.
  • ACCESS_TOKEN: token OAuth 2.0 Twojej aplikacji.
  • FILE_COPY_NAME: nazwa nowego pliku.

Kopiuj komentarze

Aby skopiować komentarze i sugestie podczas kopiowania pliku Dokumentów Google, Arkuszów lub Prezentacji, ustaw parametr zapytania copyComments na true. Dysk kopiuje tylko otwarte komentarze (nierozwiązane). W przypadku innych typów plików Dysk ignoruje ten parametr.

Więcej informacji o uprawnieniach, atrybucji komentarzy i kwestiach związanych z dostępem znajdziesz w artykule Ograniczenia i kwestie do rozważenia.

Ograniczenia i kwestie do rozważenia

Podczas przygotowywania się do kopiowania plików zwróć uwagę na te ograniczenia i kwestie do rozważenia:

  • Uprawnienia:

    • Obiekt DownloadRestrictionsMetadata zasobu files określa kto może kopiować plik. Więcej informacji znajdziesz w artykule Uniemożliwianie innym osobom pobierania, drukowania i kopiowania Twojego pliku.
    • Zasób pola capabilities.canCopy określa, czy użytkownik może skopiować plik. Więcej informacji znajdziesz w artykule Omówienie możliwości plików.
    • Aby skopiować komentarze, musisz mieć uprawnienia do ich odczytu w pliku źródłowym. Jeśli nie masz uprawnień do odczytu komentarzy i ustawisz copyComments na true, operacja kopiowania zakończy się powodzeniem, ale komentarze nie zostaną skopiowane.
    • Kopiowanie komentarzy nie przyznaje autorom oryginalnych komentarzy dostępu do nowego pliku. Listy kontroli dostępu (ACL) nowego pliku są niezależne od list ACL pliku źródłowego.
    • Użytkownik, który utworzył kopię, jest właścicielem skopiowanego pliku. Żadne inne ustawienia udostępniania z pliku źródłowego nie są replikowane. Jeśli kopia zostanie utworzona w folderze udostępnionym, dziedziczy uprawnienia tego folderu.
    • Własność skopiowanego pliku może się zmienić, a kopia może nie dziedziczyć ustawień udostępniania oryginalnego pliku. Te ustawienia mogą wymagać zresetowania.

  • Zarządzanie plikami:

    • Niektórych plików, np. skrótów innych firm, nie można kopiować.
    • Plik można skopiować tylko do 1 folderu nadrzędnego. Określanie wielu folderów nadrzędnych nie jest obsługiwane. Jeśli pole parents nie jest określone, plik dziedziczy wszystkie wykrywalne foldery nadrzędne z pliku źródłowego.
    • Chociaż folder jest typem pliku, nie można go skopiować. Zamiast tego utwórz folder docelowy i ustaw pole parents istniejących plików na folder docelowy. Następnie możesz usunąć oryginalny folder źródłowy.
    • Jeśli nie określisz nowej nazwy pliku, metoda copy utworzy plik o takiej samej nazwie jak oryginał.
    • Nadmierne używanie metody copy może spowodować przekroczenie limitów interfejsu Drive API. Więcej informacji znajdziesz w artykule Limity użycia.

Oto kilka kolejnych kroków, które możesz wykonać: