Żądania zbiorcze

Ten dokument pokazuje, jak wsadowe wywołania interfejsu API zmniejszają liczbę połączeń, które musi nawiązać klient. Tworzenie wsadów może poprawić wydajność aplikacji, ponieważ zmniejszy liczbę przesyłanych danych w obie strony i zwiększy przepustowość.

Opis

Każde połączenie realizowane przez klienta wiąże się z określonym nakładem pracy. Interfejs API Prezentacji 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 jednym żądaniu zbiorczym. Żądanie zbiorcze może zwiększyć wydajność, łącząc wiele żądań podrzędnych w jedno wywołanie do serwera i pobierając jedną odpowiedź.

Zachęcamy użytkowników do grupowania wielu żądań. Oto kilka przykładów sytuacji, w których można użyć grupowania:

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

Ograniczenia, uprawnienia i zależności

Oto lista innych elementów, które warto wziąć pod uwagę przy 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 uwierzytelnianie pojedyncze 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. Późniejsze żą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 jednego wywołania metody batchUpdate z wieloma żądaniami podrzędnymi, np. dodanie i formatowanie prezentacji.

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

Niektóre żądania dostarczają odpowiedzi z informacjami o zastosowanych żądaniach. Na przykład wszystkie zbiorcze żądania dodania obiektów, które zwracają odpowiedzi, pozwalają 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ą 1 żądania zbiorczego aktualizacji 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 wymaganą właściwością: requests. Żądania są tworzone w tablicy pojedynczych żądań. Każde żądanie reprezentuje obiekt żądania i zawiera jego właściwości w formacie JSON.

Format odpowiedzi zbiorczej

Format odpowiedzi w przypadku żą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, a każda odpowiedź na 1 żądanie zajmuje tę samą kolejność indeksowania 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 Slides API.

Prośba

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

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

Odpowiedź

Ta przykładowa odpowiedź zbiorcza zawiera informacje o tym, jak zastosowano każde żądanie podrzędne w ramach żądania zbiorczego. Pamiętaj, że metoda InsertTextRequest nie zawiera odpowiedzi, więc wartość indeksu tablicy w punkcie [2] składa się z pustych nawiasów klamrowych. Żądanie zbiorcze wyświetla właściwość WriteControl, która pokazuje sposób wykonywania żądań zapisu.

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}