Żądania zbiorcze

Ten dokument pokazuje, 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.

Omówienie

Każde połączenie utworzone przez klienta powoduje pewien narzut. 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ść, łącząc wiele żądań podrzędnych w jedną prośbę do serwera i otrzymywanie jednej odpowiedzi.

Zachęcamy użytkowników, aby zawsze wysyłali wiele żądań w ramach jednego zbiorczego żądania. Oto kilka przykładów sytuacji, w których możesz użyć grupowania:

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

Limity, 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 aktualizacji.
  • Serwer przetwarza żądania podrzędne w tej samej kolejności, w jakiej występują w żądaniu zbiorczym. Kolejne podzapytania mogą zależeć od działań podjętych podczas wcześniejszych podzapytań. 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 w sposób atomowy. 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ł.

Dzięki temu podejściu możesz utworzyć cały dokument Google za pomocą jednego interfejsu API, wysyłając prośbę o zbiorczą aktualizację z wieloma podzapytaniami.

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 użycie grupowania w interfejsie Docs API.

Żądanie

Ten przykładowy pakiet żądań 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 ma zastosowanie żądanie zapisu.

Odpowiedź

Ta przykładowa odpowiedź zbiorcza zawiera informacje o tym, jak zostały zastosowane poszczególne żądania podrzędne w ramach żądania zbiorczego. 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`
}