Żądania zbiorcze

W tym dokumencie opisujemy, jak zbiorczo połączyć wywołania interfejsu API, aby zmniejszyć liczbę połączeń, które musi nawiązać klient. Grupowanie wsadowe może poprawić wydajność aplikacji dzięki zmniejszeniu przesyłania danych w obie strony i zwiększeniu przepustowości.

Przegląd

Każde połączenie, które wykonuje Twój klient, wiąże się z określonym nakładem pracy. 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 pojedynczy typ żądania do wykonania, w jednym żądaniu zbiorczym. Żądanie zbiorcze może zwiększyć wydajność, łącząc wiele żądań podrzędnych w jedno wywołanie do serwera, pobierając z powrotem jedną odpowiedź.

Zachęcamy użytkowników, aby zawsze zgrupowali wiele żądań razem. Oto kilka przykładów sytuacji, w których można 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.

Ograniczenia, autoryzację i zależności

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

  • Każde żądanie zbiorcze, w tym wszystkie żądania podrzędne, jest liczone jako 1 żądanie do interfejsu API w ramach limitu wykorzystania.
  • Żądanie zbiorcze jest uwierzytelniane raz. To pojedyncze uwierzytelnianie ma zastosowanie do wszystkich obiektów aktualizacji zbiorczej w żądaniu.
  • Serwer przetwarza żądania podrzędne w tej samej kolejności, w jakiej występują w żądaniu zbiorczym. Ostatnie żądania podrzędne mogą zależeć od działań wykonanych podczas wcześniejszych żądań podrzędnych. Na przykład w tym samym żądaniu zbiorczym użytkownicy mogą wstawić tekst do istniejącego dokumentu, a następnie zmienić jego styl.

Szczegóły wsadu

Żądanie zbiorcze składa się z 1 wywołania metody batchUpdate z wieloma żądaniami podrzędnymi, na przykład w celu dodania i sformatowania dokumentu.

Każde żądanie jest sprawdzane przed zastosowaniem. Wszystkie żądania podrzędne w aktualizacji zbiorczej są stosowane atomowo. Oznacza to, że jeśli którekolwiek żądanie jest nieprawidłowe, cała aktualizacja kończy się niepowodzeniem i nie są stosowane żadne (potencjalnie zależne) zmiany.

Niektóre żądania zawierają w odpowiedzi informacje o zastosowanych żądaniach. Na przykład wszystkie zbiorcze żądania aktualizacji obiektów zwracają odpowiedzi, dzięki czemu można uzyskać dostęp do metadanych nowo dodanego obiektu, takich jak identyfikator lub tytuł.

Dzięki temu 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 jedną wymaganą właściwością: requests. Żądania mają postać tablicy pojedynczych żądań. Każde żądanie używa formatu JSON do reprezentowania obiektu żądania i przechowywania jego właściwości.

Format odpowiedzi zbiorczej

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

Właściwość głównego obiektu JSON to replies. Odpowiedzi są zwracane w tablicy, przy czym każda odpowiedź na 1 żądanie zajmuje tę samą kolejność indeksu co odpowiednie żądanie. Niektóre żądania nie mają odpowiedzi, a odpowiedź w tym indeksie tablicy jest pusta.

Przykład

Poniższy przykładowy kod ilustruje sposób użycia grupowania za pomocą interfejsu API Dokumentów.

Prośba

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

  • Wstaw tekst „Hello World” na początku istniejącego dokumentu z indeksem location wynoszącym 1, korzystając z InsertTextRequest.

  • Zaktualizuj słowo „Hello” za pomocą UpdateTextStyleRequest. startIndex i endIndex określają range sformatowanego tekstu w segmencie.

  • Używając textStyle, ustaw styl czcionki na pogrubienie i kolor na niebieski dla słowa „Cześć”.

  • Za pomocą pola WriteControl możesz kontrolować sposób wykonywania żądań zapisu. Więcej informacji znajdziesz w artykule o utrzymywaniu spójności stanu za pomocą parametru WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "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 REQUIRED_REVISION_ID identyfikatorem wersji dokumentu, do którego zastosowano żądanie zapisu.

Odpowiedź

Ta przykładowa odpowiedź zbiorcza zawiera informacje o tym, jak zastosowano każde żądanie zbiorcze w ramach żądania zbiorczego. Ani InsertTextRequest, ani UpdateTextStyleRequest nie zawierają odpowiedzi, więc wartości indeksu tablicy w postaci [0] i [1] zawierają puste nawiasy klamrowe. Żądanie zbiorcze wyświetla obiekt WriteControl, który pokazuje, jak zostały wykonane żądania.

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