Żądania zbiorcze

Z tego dokumentu dowiesz się, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę połączeń, które musi nawiązać klient. Przetwarzanie w grupach może zwiększyć wydajność aplikacji przez zmniejszenie liczby połączeń z siecią i zwiększenie przepustowości.

Przegląd

Każde połączenie powoduje pewne narzuty. Interfejs Google Docs API obsługuje grupowanie, aby umożliwić klientowi umieszczanie wielu obiektów żądań, z których każdy określa jeden typ żądania do wykonania, w jednym żądaniu zbiorczym. Żądanie zbiorcze może zwiększyć wydajność przez połączenie wielu żądań podrzędnych w jedno wywołanie do serwera i pobranie jednej odpowiedzi.

Zachęcamy użytkowników, aby zawsze zbierali wiele żądań naraz. Oto kilka przykładów sytuacji, w których można używać grupowania:

  • dopiero zaczynasz korzystać z interfejsu API i masz dużo danych do przesłania.
  • Musisz zaktualizować metadane lub właściwości wielu obiektów, takie jak formatowanie.
  • Musisz usunąć wiele obiektów.

Ograniczenia, autoryzacja i zależności

Oto lista innych kwestii, które warto wziąć pod uwagę podczas aktualizacji zbiorczej:

  • Każde żądanie zbiorcze, w tym wszystkie żądania podrzędne, jest liczone jako 1 żądanie interfejsu API w ramach limitu użycia.
  • Prośba zbiorcza jest uwierzytelniana tylko raz. To jedno uwierzytelnianie dotyczy wszystkich obiektów w prośbie o zbiorcze.
  • Serwer przetwarza żądania podrzędne w tej samej kolejności, w jakiej występują w żądaniu zbiorczym. Kolejne żądania podrzędne mogą zależeć od działań wykonanych podczas wcześniejszych żądań podrzędnych. Na przykład w ramach tego samego zbiorczego żądania użytkownicy mogą wstawić tekst do istniejącego dokumentu, a następnie nadać mu styl.

Szczegóły wsadu

Zbiorcze żądanie składa się z jednego wywołania metody batchUpdate z wieloma podrzędnymi żądaniami, które na przykład dodają i formatują dokument.

Każde żądanie jest weryfikowane przed zastosowaniem. Wszystkie podzapytania w ramach aktualizacji zbiorczej są stosowane jako całość. Oznacza to, że jeśli żądanie jest nieprawidłowe, cała aktualizacja kończy się niepowodzeniem i żadne z (potencjalnie zależnych) zmian nie zostaną zastosowane.

Niektóre odpowiedzi zawierają informacje o zgłoszonych żądaniach. Na przykład wszystkie żądania zbiorczego aktualizowania służące do dodawania obiektów zwracają odpowiedzi, dzięki którym możesz uzyskać dostęp do metadanych nowo dodanego obiektu, takich jak identyfikator lub tytuł.

W ten sposób możesz utworzyć cały dokument Google za pomocą jednego żądania aktualizacji zbiorczej interfejsu API z wieloma żądaniami podrzędnymi.

Format żądania zbiorczego

Żądanie to pojedyncze żądanie JSON zawierające wiele zagnieżdżonych żądań podrzędnych z 1 wymaganym atrybutem: requests. Zapytania są tworzone w tablicy pojedynczych zapytań. Każde żądanie używa JSON do reprezentowania obiektu żądania i zawierania jego właściwości.

Format odpowiedzi zbiorczej

Format odpowiedzi na żądanie zbiorcze jest podobny do formatu żądania. Odpowiedź serwera zawiera pełną odpowiedź pojedynczego obiektu odpowiedzi.

Właściwość głównego obiektu JSON ma nazwę replies. Odpowiedzi są zwracane w tablicy, a każda odpowiedź na jedno z żądań zajmuje to samo miejsce w indeksie co odpowiadające mu żądanie. Niektóre żądania nie mają odpowiedzi, a odpowiedź w tym indeksie tablicy jest pusta.

Przykład

Poniższy przykładowy kod pokazuje, jak można korzystać z grupowania za pomocą interfejsu API Dokumentów.

Żądanie

To przykładowe żądanie zbiorcze pokazuje, jak:

  • Wstaw tekst „Hello World” na początku istniejącego dokumentu z indeksem location w dokumentie 1, używając polecenia InsertTextRequest.

  • Zaktualizuj słowo „Cześć” za pomocą UpdateTextStyleRequest. Wartości startIndex i endIndex określają range sformatowanego tekstu w danym segmencie.

  • Za pomocą textStyle ustaw czcionkę na pogrubioną, a kolor na niebieski tylko dla słowa „Cześć”.

  • Za pomocą pola WriteControl możesz kontrolować sposób wykonywania żądań zapisu. Więcej informacji znajdziesz w artykule Utrzymywanie spójności stanu za pomocą 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"
  }
}

Zastąp TAB_ID i REQUIRED_REVISION_ID odpowiednio identyfikatorem karty i identyfikatorem wersji dokumentu, do którego zastosowano żądanie zapisu.

Odpowiedź

Ta przykładowa odpowiedź zbiorcza zawiera informacje o tym, jak zastosowano poszczególne żądania podrzędne w żądaniu zbiorczym. Ani InsertTextRequest, ani UpdateTextStyleRequestnie zawierają odpowiedzi, więc wartości indeksu tablicy w miejscach [0] i [1] składają się z pustych nawiasów klamrowych. Żądanie zbiorcze zawiera obiekt WriteControl, który pokazuje, jak były wykonywane żądania.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}