Żądania zbiorcze

W tym dokumencie pokazujemy, jak łączyć wywołania interfejsu API w żądania wsadowe, aby zmniejszyć liczbę połączeń, które musi nawiązać klient. Grupowanie może zwiększyć wydajność aplikacji, ponieważ zmniejsza liczbę podróży w sieci i zwiększa przepustowość.

Przegląd

Każde połączenie nawiązywane przez klienta powoduje określony narzut. Interfejs Google Slides API obsługuje żądania zbiorcze, dzięki czemu klient może umieścić w jednym żądaniu zbiorczym wiele obiektów żądań, z których każdy określa jeden typ żądania do wykonania. Żądanie zbiorcze może zwiększyć wydajność, ponieważ łączy wiele żądań podrzędnych w jedno wywołanie serwera i pobiera jedną odpowiedź.

Zachęcamy użytkowników do łączenia wielu żądań w pakiety. Oto kilka przykładów sytuacji, w których możesz użyć przetwarzania zbiorczego:

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

Limity, autoryzacja i zależności

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

  • Każde żądanie zbiorcze, w tym wszystkie podżądania, jest liczone jako 1 żądanie interfejsu API w ramach limitu wykorzystania.
  • Żądanie wsadowe jest uwierzytelniane tylko raz. To pojedyncze uwierzytelnianie dotyczy wszystkich obiektów aktualizacji zbiorczej w żądaniu.
  • Serwer przetwarza żądania podrzędne w kolejności, w jakiej występują w żądaniu zbiorczym. Późniejsze podżądania mogą zależeć od działań podjętych podczas wcześniejszych podżądań. Na przykład w tym samym żądaniu zbiorczym użytkownicy mogą wstawić tekst do istniejącego dokumentu, a następnie go sformatować.

Szczegóły wsadu

Żądanie zbiorcze składa się z 1 wywołania metody batchUpdate z wieloma podrzędnymi żądaniami, np. dodania, a potem sformatowania prezentacji.

Każda prośba jest weryfikowana przed zastosowaniem. Wszystkie żądania podrzędne w aktualizacji zbiorczej są stosowane niepodzielnie. Oznacza to, że jeśli którekolwiek żądanie jest nieprawidłowe, cała aktualizacja się nie powiedzie i żadne zmiany (potencjalnie zależne) nie zostaną zastosowane.

W przypadku niektórych żądań otrzymasz odpowiedzi zawierające informacje o zastosowanych żądaniach. Na przykład wszystkie żądania aktualizacji zbiorczej dotyczące dodawania obiektów zwracają odpowiedzi, dzięki czemu 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 za pomocą jednego żądania zbiorczej aktualizacji interfejsu API zawierającego wiele podrzędnych żądań.

Format żądania zbiorczego

Żądanie to pojedyncze żądanie JSON zawierające wiele zagnieżdżonych podrzędnych żądań z jedną wymaganą właściwością: requests. Żądania są tworzone w postaci tablicy poszczególnych żądań. Każde żądanie używa formatu 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ź w postaci pojedynczego obiektu odpowiedzi.

Właściwość głównego obiektu JSON ma nazwę replies. Odpowiedzi są zwracane w tablicy, a każda z nich zajmuje ten sam indeks co odpowiednie żą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 przetwarzania wsadowego w interfejsie Slides API.

Żądanie

Ten przykładowy pakiet żądań 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ź

Ten przykładowy pakiet odpowiedzi zawiera informacje o tym, jak zastosowano poszczególne żądania w żądaniu zbiorczym. Zwróć uwagę, że metoda InsertTextRequest nie zawiera odpowiedzi, więc wartość indeksu tablicy w pozycji [2] składa się z pustych nawiasów klamrowych. Żądanie wsadowe wyświetla właściwość WriteControl , która pokazuje, jak zostały wykonane żądania zapisu.

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