Z tego dokumentu dowiesz się, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę które z nim musi nawiązać klient. Grupowanie wsadowe może poprawić efektywność dzięki zmniejszeniu przesyłania danych w obie strony i zwiększeniu przepustowości.
Omówienie
Każde połączenie powoduje pewne narzuty. Interfejs API Dokumentów Google obsługuje grupowanie, dzięki czemu klient może umieścić wiele obiektów żądań, z których każdy określa jeden typ żądania do wykonania, w jedno żądanie zbiorcze. Żądanie zbiorcze może zwiększyć wydajność przez przez połączenie wielu żądań podrzędnych w jedno wywołanie do serwera, jedną odpowiedź.
Zachęcamy użytkowników, aby zawsze zbierali wiele żądań naraz. Oto kilka Przykłady sytuacji, w których można używać grupowania:
- Od niedawna korzystasz z interfejsu API i masz dużo danych do przesłania.
- Musisz zaktualizować metadane lub właściwości, takie jak formatowanie, na wielu obiektów.
- Musisz usunąć wiele obiektów.
Ograniczenia, autoryzacja kwestie zależności
Oto lista innych kwestii, które warto wziąć pod uwagę podczas wdrażania aktualizacji zbiorczej:
- Każde żądanie zbiorcze, w tym wszystkie żądania podrzędne, jest liczone jako 1 interfejs API zbliża się do limitu wykorzystania.
- Żądanie zbiorcze jest uwierzytelniane raz. To pojedyncze uwierzytelnianie jest stosowane do wszystkich obiektów aktualizacji wsadowej w żądaniu.
- Serwer przetwarza żądania podrzędne w takiej samej kolejności, w jakiej występują w żądania zbiorczego. Kolejne żądania podrzędne mogą zależeć od działań wykonanych podczas we wcześniejszych żądaniach podrzędnych. Na przykład w tym samym żądaniu zbiorczym użytkownicy mogą wstawić tekst do istniejącego dokumentu i nadać mu styl.
Szczegóły wsadu
Żądanie zbiorcze składa się z jednego wywołania metody batchUpdate
z wieloma żądaniami podrzędnymi, na przykład dotyczącymi dodania i formatowania dokumentu.
Każda prośba jest weryfikowana przed zastosowaniem. Wszystkie żądania podrzędne w grupie są stosowane oddzielnie. Oznacza to, że jeśli któreś żądanie jest nieprawidłowe, cała aktualizacja kończy się niepowodzeniem i żaden (potencjalnie zależny) zmiany zostały zastosowane.
Niektóre żądania zawierają informacje o zastosowanych żądaniach. Na przykład wszystkie żądania aktualizacji zbiorczych o dodanie obiektów zwracają odpowiedzi, możesz uzyskać dostęp do metadanych nowo dodanego obiektu, takich jak identyfikator czy tytuł.
Dzięki temu możesz utworzyć cały dokument Google przy użyciu jednego interfejsu API zbiorczych żądań aktualizacji z wieloma żądaniami podrzędnymi.
Format żądania zbiorczego
Żądanie to pojedyncze żądanie JSON zawierające kilka,
zagnieżdżone żądania podrzędne z 1 wymaganą właściwością: requests
.
są tworzone w tablicy indywidualnych żądań. W każdym żądaniu jest wykorzystywane
JSON reprezentujący obiekt żądania i zawierający jego właściwości.
Format odpowiedzi zbiorczej
Format odpowiedzi na żądanie zbiorcze jest podobny do format żądania. Odpowiedź serwera zawiera pełną odpowiedź pojedynczego obiektu odpowiedzi.
Właściwość głównego obiektu JSON nazywa się replies
. Odpowiedzi
są zwracane w tablicy, a każda odpowiedź na jedno z żądań
w tej samej kolejności indeksu co w odpowiednim żądaniu. Niektóre żądania nie zawierają
, a odpowiedź o tym indeksie tablicy jest pusta.
Przykład
Poniższy przykładowy kod pokazuje, jak korzystać z grupowania za pomocą interfejsu API Dokumentów.
Żądanie
To przykładowe żądanie zbiorcze pokazuje, jak:
Wstaw „Hello World” na początku istniejącego dokumentu, ze znakiem
location
z1
, przy użyciu funkcjiInsertTextRequest
.Zaktualizuj słowo „Cześć” za pomocą
UpdateTextStyleRequest
ElementystartIndex
iendIndex
określająrange
sformatowanego tekstu w segmentem.Za pomocą
textStyle
ustaw styl czcionki na pogrubienie, a kolor na niebieski, słowo „Cześć”.Korzystanie z narzędzia
WriteControl
możesz kontrolować sposób wykonywania żądań zapisu. Więcej więcej informacji na ten temat można znaleźć w artykule o ustalaniu spójności stanów z WriteControl.
{ "requests":[ { "insertText":{ "location":{ "index":1, "tabId":TAB_ID }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
Zamień TAB_ID i REQUIRED_REVISION_ID na odpowiednio identyfikator karty i identyfikatora wersji dokumentu, którego dotyczy żądanie zapisu .
Odpowiedź
Ta przykładowa odpowiedź zbiorcza zawiera informacje o tym, jak każde podrzędne żądanie w ramach
żądanie zbiorcze zostało zastosowane. Ani żaden
InsertTextRequest
lub
UpdateTextStyleRequest
zawiera odpowiedź, więc wartości indeksu tablicy [0] i [1] składają się
pustych nawiasów klamrowych. W żądaniu zbiorczym wyświetli się obiekt WriteControl
,
który pokazuje, jak żądania zostały zrealizowane.
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }