Żą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 powoduje pewne narzuty. 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 jedno żądanie zbiorcze. Żądanie zbiorcze może zwiększyć wydajność przez przez połączenie wielu żądań podrzędnych w jedno wywołanie do serwera, jedną odpowiedź.

Zachęcamy użytkowników, aby zawsze zbierali wiele żądań naraz. 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 prośbami podrzędnymi, na przykład o dodanie i sformatowanie prezentacji.

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 zawierają , a odpowiedź o tym indeksie tablicy jest pusta.

Przykład

Poniższy przykładowy kod pokazuje wykorzystanie grupowania za pomocą Interfejs API Prezentacji.

Żą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 każde podrzędne żądanie w ramach żądanie zbiorcze zostało zastosowane. Zwróć uwagę na InsertTextRequest nie zawiera odpowiedzi, więc wartość indeksu tablicy w [2] składa się z pustych nawiasów klamrowych. W żądaniu zbiorczym wyświetlane są WriteControl , która pokazuje, jak były wykonywane żądania zapisu.

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