Żądania zbiorcze

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 utworzone przez klienta powoduje pewien narzut. 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ść, łącząc wiele żądań podrzędnych w jedną prośbę do serwera i osiągając jedną odpowiedź.

Zachęcamy użytkowników, aby zawsze wysyłali wiele żądań w ramach jednego zbiorczego żądania. 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 sformatowania 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 mają odpowiedzi, a odpowiedź w 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 z 1, przy użyciu funkcji InsertTextRequest.

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

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

  • Korzystanie z narzędzia WriteControl możesz kontrolować sposób wykonywania żądań zapisu. Więcej informacje na ten temat zawiera artykuł 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 plik, ani 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`
}