Żądania zbiorcze

Z tego dokumentu dowiesz się, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę połączeń, które musi nawiązać klient. Grupowanie wsadowe może zwiększyć wydajność aplikacji przez zmniejszenie liczby transferów w obie strony sieci i zwiększenie przepustowości.

Przegląd

Każde połączenie powoduje pewne narzuty. Interfejs API Prezentacji Google obsługuje grupowanie, dzięki czemu klient może umieścić w jednym żądaniu zbiorczym wiele obiektów żądań, z których każdy określa pojedynczy typ żądania do wykonania. Żądanie zbiorcze może zwiększyć wydajność przez połączenie wielu żądań podrzędnych w jedno wywołanie do serwera i pobranie jednej odpowiedzi.

Zachęcamy użytkowników, aby zawsze zbierali wiele żądań naraz. Oto kilka przykładów 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 wielu obiektów, takie jak formatowanie.
  • Musisz usunąć wiele obiektów.

Ograniczenia, autoryzacja i 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 żądanie interfejsu API w ramach limitu wykorzystania.
  • Żądanie zbiorcze jest uwierzytelniane raz. To pojedyncze uwierzytelnianie dotyczy wszystkich obiektów aktualizacji wsadowej w żądaniu.
  • Serwer przetwarza żądania podrzędne w tej samej kolejności, w jakiej występują w żądaniu zbiorczym. Kolejne żądania podrzędne mogą zależeć od działań wykonanych podczas wcześniejszych żądań podrzędnych. W ramach tego samego żądania zbiorczego użytkownicy mogą na przykład wstawić tekst do istniejącego dokumentu i nadać mu styl.

Szczegóły wsadu

Żądanie zbiorcze składa się z 1 wywołania metody batchUpdate z wieloma żądaniami podrzędnymi, aby na przykład dodać i sformatować prezentację.

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

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

W ten sposób 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 1 wymaganą właściwością: requests. Żądania są tworzone w tablicy indywidualnych żądań. Każde żądanie wykorzystuje kod JSON do reprezentowania obiektu żądania i przechowywania jego właściwości.

Format odpowiedzi zbiorczej

Format odpowiedzi na żądanie zbiorcze jest podobny do formatu żądania. Odpowiedź serwera zawiera pełną odpowiedź obiektu pojedynczej odpowiedzi.

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

Przykład

Poniższy przykładowy kod pokazuje, jak można grupować dane za pomocą interfejsu Slides API.

Żądanie

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 poszczególne żądania podrzędne w żądaniu zbiorczym. Pamiętaj, że metoda InsertTextRequest nie zawiera odpowiedzi, więc wartość indeksu tablicy w [2] składa się z pustych nawiasów klamrowych. W żądaniu zbiorczym wyświetla się 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
   }
}