W tym dokumencie opisujemy techniki, które mogą poprawić wydajność Twojej aplikacji. Aby przedstawić niektóre rozwiązania, użyliśmy przykładów z innych interfejsów API lub ogólnych interfejsów API. Jednak te same pojęcia są używane w interfejsie Google Drive API.
Kompresja za pomocą gzip
Kompresja gzip pozwala łatwo i wygodnie zmniejszyć przepustowość potrzebną do obsługi żądań. Dekompresja wyników wymaga dodatkowego czasu pracy procesora, jednak w zestawieniu z kosztami związanymi z siecią to rozwiązanie wypada bardzo korzystnie.
Aby odebrać odpowiedź zakodowaną w formacie gzip, ustaw nagłówek Accept-Encoding i dodaj do klienta użytkownika tekst gzip. Oto przykład poprawnych nagłówków HTTP, za pomocą których włączysz kompresję gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Praca z częściowymi zasobami
Innym sposobem na poprawę wydajności wywołań interfejsu API jest wysyłanie i odbieranie tylko części danych, które Cię interesują. Dzięki temu aplikacja nie musi przesyłać, analizować i zapisywać niepotrzebnych pól, co pozwala wydajniej wykorzystywać zasoby, w tym sieć, procesor i pamięć.
Istnieją 2 typy częściowych żądań:
- Odpowiedź częściowa: w tym żądaniu wybierasz, które pola mają znajdować się w odpowiedzi (użyj parametru żądania
fields). - Poprawka: w tym żądaniu aktualizacji wysyłasz tylko te pola, które chcesz zmienić (użyj czasownika HTTP
PATCH).
Więcej informacji na temat tworzenia żądań częściowych znajdziesz w sekcjach poniżej.
Odpowiedź częściowa
Po przetworzeniu żądań serwer domyślnie odsyła pełną reprezentację zasobu. Aby uzyskać lepsze wyniki, możesz wysłać do serwera żądanie o odpowiedź częściową, czyli dostarczenie tylko tych pól, których potrzebujesz.
Aby wysłać takie żądanie, użyj parametru żądania fields, określając w nim pola, które chcesz odebrać w odpowiedzi. Tego parametru możesz użyć w każdym żądaniu, które zwraca dane odpowiedzi.
Parametr fields wpływa tylko na dane odpowiedzi. Nie ma wpływu na dane, które chcesz wysłać. Aby zmniejszyć ilość danych wysyłanych po zmianie zasobów, użyj żądania poprawki.
Przykład
Poprawka (częściowa aktualizacja)
Po zmianie zasobów nie musisz wysyłać niepotrzebnych danych. Aby wysłać tylko zaktualizowane dane pól, które zmieniasz, użyj czasownika HTTP PATCH. Opisana w tym dokumencie semantyka poprawki jest inna (i prostsza) niż w implementacji interfejsu GData częściowej aktualizacji.
Krótki przykład podany poniżej pokazuje, jak dzięki poprawce można zminimalizować ilość wysyłanych danych i zmniejszyć rozmiar aktualizacji.
Przykład
Obsługa odpowiedzi na poprawkę
Po przetworzeniu prawidłowego żądania poprawki interfejs API zwraca kod stanu HTTP 200 OK i pełną reprezentację zmienionego zasobu. Jeśli interfejs API używa znaczników ETag, serwer aktualizuje wartości ETag po przetworzeniu żądania poprawki, tak jak w przypadku PUT.
Żądanie poprawki zwraca reprezentację całego zasobu, o ile nie użyto parametru fields, aby zmniejszyć ilość zwracanych danych.
Jeśli żądanie poprawki powoduje ustawienie nowego stanu żądania, który jest składniowo lub semantycznie nieprawidłowy, serwer zwraca kod stanu HTTP 400 Bad Request lub 422 Unprocessable Entity, a stan zasobu pozostaje bez zmian. Jeśli na przykład spróbujesz usunąć wartość pola wymaganego, serwer zwróci błąd.
Inny zapis w sytuacji, gdy czasownik HTTP PATCH nie jest obsługiwany
Jeśli zapora sieciowa nie zezwala na żądania HTTP PATCH, wykonaj żądanie HTTP POST i ustaw nagłówek zastąpienia na PATCH, jak pokazujemy poniżej:
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
Różnica między poprawką a aktualizacją
Kiedy wysyłasz dane żądania aktualizacji, które używa czasownika HTTP PUT, musisz wysłać tylko pola wymagane lub opcjonalne. Jeśli wyślesz wartości pól ustawionych przez serwer, zostaną one zignorowane. Może to wyglądać jak inna metoda wykonania częściowej aktualizacji, jednak ma to swoje ograniczenia. W przypadku aktualizacji, które używają czasownika HTTP PUT, żądanie nie uda się, jeśli nie podasz wymaganych parametrów, oraz wyczyści wcześniej ustawione dane, jeśli nie podasz parametrów opcjonalnych.
Z tego względu dużo bezpieczniejsze jest użycie poprawki. Podajesz tylko dane pól, które chcesz zmienić. Pominięte pola nie są opróżniane. Jedynym wyjątkiem od tej reguły są powtarzające się elementy lub tablice. Jeśli pominiesz je wszystkie, pozostaną bez zmian. Jeśli podasz którekolwiek z nich, cały zbiór zostanie zastąpiony zbiorem, który podasz.
Żądania zbiorcze
W tym dokumencie pokazujemy, jak łączyć wywołania interfejsu API w żądania wsadowe, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.
Ten dokument dotyczy konkretnie wysyłania żądania zbiorczego za pomocą żądania HTTP. Jeśli do wysyłania żądań zbiorczych używasz biblioteki klienta Google, zapoznaj się z dokumentacją biblioteki klienta.
Przegląd
Każde połączenie HTTP nawiązywane przez klienta wiąże się z określonym narzutem. Interfejs Google Drive API obsługuje tworzenie żądań wsadowych, dzięki czemu klient może umieścić kilka wywołań interfejsu API w jednym żądaniu HTTP.
Przykłady sytuacji, w których warto używać przetwarzania wsadowego:
- pobieranie metadanych dużej liczby plików;
- zbiorcze aktualizowanie metadanych lub właściwości;
- zmiana uprawnień do dużej liczby plików, np. dodanie nowego użytkownika lub grupy;
- Synchronizowanie danych klienta lokalnego po raz pierwszy lub po dłuższym okresie braku połączenia.
W każdym z tych przypadków zamiast wysyłać każde wywołanie osobno możesz zgrupować je w jednym żądaniu HTTP. Wszystkie żądania wewnętrzne muszą być kierowane do tego samego interfejsu API Google.
W jednym żądaniu zbiorczym możesz wykonać maksymalnie 100 wywołań. Jeśli musisz wykonać więcej wywołań, użyj kilku żądań zbiorczych.
Uwaga: system przetwarzania zbiorczego interfejsu Google Drive API używa tej samej składni co system przetwarzania zbiorczego OData, ale różni się od niego semantyką.
Dodatkowe ograniczenia:
- Żądania zbiorcze zawierające więcej niż 100 wywołań mogą powodować błędy.
- Długość adresu URL każdego żądania wewnętrznego jest ograniczona do 8000 znaków.
- Dysk Google nie obsługuje operacji wsadowych w przypadku multimediów, zarówno podczas przesyłania, jak i pobierania, ani podczas eksportowania plików.
Szczegóły wsadu
Żądanie zbiorcze składa się z kilku wywołań interfejsu API połączonych w jedno żądanie HTTP, które można wysłać do batchPath określonego w dokumencie wykrywania interfejsu API. Ścieżka domyślna to /batch/api_name/api_version. W tej sekcji szczegółowo opisujemy składnię plików wsadowych. Przykład znajdziesz w dalszej części artykułu.
Uwaga: zestaw n żądań połączonych w pakiet jest liczony do limitu wykorzystania jako n żądania, a nie jako 1 żądanie. Przed przetworzeniem żądanie zbiorcze jest dzielone na zestaw żądań.
Format żądania zbiorczego
Żądanie zbiorcze to jedno standardowe żądanie HTTP zawierające wiele wywołań interfejsu Google Drive API, które korzysta z typu treści multipart/mixed. W tym głównym żądaniu HTTP każda z części zawiera zagnieżdżone żądanie HTTP.
Każda część zaczyna się od własnego Content-Type: application/http nagłówka HTTP. Może też zawierać opcjonalny Content-ID nagłówek. Nagłówki części służą jednak tylko do oznaczania początku części i są oddzielone od zagnieżdżonego żądania. Gdy serwer rozpakuje żądanie zbiorcze na osobne żądania, nagłówki części są ignorowane.
Treść każdej części to kompletne żądanie HTTP z własnym czasownikiem, adresem URL, nagłówkami i treścią. Żądanie HTTP musi zawierać tylko ścieżkę adresu URL. W żądaniach zbiorczych nie są dozwolone pełne adresy URL.
Nagłówki HTTP zewnętrznego żądania zbiorczego, z wyjątkiem nagłówków Content-, takich jak Content-Type, mają zastosowanie do każdego żądania w partii. Jeśli podasz dany nagłówek HTTP zarówno w żądaniu zewnętrznym, jak i w pojedynczym wywołaniu, wartość nagłówka pojedynczego wywołania zastąpi wartość nagłówka zewnętrznego żądania zbiorczego. Nagłówki pojedynczego połączenia dotyczą tylko tego połączenia.
Jeśli na przykład podasz nagłówek Authorization dla konkretnego wywołania, będzie on dotyczył tylko tego wywołania. Jeśli podasz nagłówek autoryzacji dla żądania zewnętrznego, będzie on obowiązywać we wszystkich poszczególnych wywołaniach, chyba że zastąpią go własne nagłówki autoryzacji.
Gdy serwer otrzyma żądanie zbiorcze, zastosuje do każdej jego części parametry zapytania i nagłówki żądania zewnętrznego (w odpowiedni sposób), a następnie potraktuje każdą część tak, jakby była osobnym żądaniem HTTP.
Odpowiedź na żądanie zbiorcze
Odpowiedź serwera to pojedyncza standardowa odpowiedź HTTP o multipart/mixed typie treści. Każda jej część jest odpowiedzią na jedno z żądań w żądaniu zbiorczym, w tej samej kolejności co żądania.
Podobnie jak części żądania, każda część odpowiedzi zawiera kompletną odpowiedź HTTP, w tym kod stanu, nagłówki i treść. Podobnie jak w przypadku części żądania, każda część odpowiedzi jest poprzedzona nagłówkiem Content-Type, który oznacza początek tej części.
Jeśli dana część żądania zawierała nagłówek Content-ID, odpowiednia część odpowiedzi zawiera pasujący nagłówek Content-ID, w którym przed pierwotną wartością znajduje się ciąg znaków response-, jak pokazano w przykładzie poniżej.
Uwaga: serwer może wykonywać wywołania w dowolnej kolejności. Nie zakładaj, że zostaną one wykonane w kolejności, w jakiej zostały określone. Jeśli chcesz mieć pewność, że 2 wywołania nastąpią w określonej kolejności, nie możesz wysłać ich w jednym żądaniu. Zamiast tego wyślij najpierw pierwsze wywołanie, a potem poczekaj na odpowiedź, zanim wyślesz drugie.
Przykład
Ten przykład pokazuje użycie przetwarzania wsadowego w Google Drive API.
Przykładowe żądanie zbiorcze
POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8
{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8
{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--
Przykładowa odpowiedź zbiorcza
To jest odpowiedź na przykładowe żądanie z poprzedniej sekcji.
HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "12218244892818058021i" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "04109509152946699072k" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk--
Zwracanie określonych pól z żądania
Jeśli nie określisz parametru fields, serwer zwróci domyślny zestaw pól specyficznych dla danej metody. Na przykład metoda files.list zwraca tylko pola kind, id, name i mimeType.
Domyślne pola zwracane mogą nie być tym, czego potrzebujesz. Jeśli chcesz określić, które pola mają być zwracane w odpowiedzi, użyj parametru fields system.
Więcej informacji znajdziesz w sekcji Zwracanie określonych pól.
W przypadku wszystkich metod zasobów about, comments (z wyjątkiem delete) i replies (z wyjątkiem delete) musisz ustawić parametr fields. Te metody nie zwracają domyślnego zestawu pól.