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, 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ć parametr fields systemowy za pomocą dowolnej metody 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 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 zostały 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 należał do 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ą parametru zapytania count. 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 zduplikowane pliki 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łane pliki, które mają zostać przekonwertowane 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, który wskazuje 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ć wszystkie żą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 nieuwzglę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.

Limity i kwestie do rozważenia

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

  • Uprawnienia:

  • 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ć: