Żą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 Arkuszy Google obsługuje grupowanie, dzięki czemu klient będzie mógł umieszczać 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 arkusza kalkulacyjnego.

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ład pokazuje wykorzystanie grupowania za pomocą interfejsu Arkuszy API.

Żądanie

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

• Dodaj arkusz do istniejącego arkusza kalkulacyjnego z wartością sheetId równą 12345, korzystając z AddSheetRequest.
• Dodaj dane do nowego arkusza, zaczynając od komórki A1, używając symbolu UpdateCellsRequest.
• Dodaj do nowego arkusza namedRange lub widok filtra.

Dodając identyfikator arkusza w żądaniu, użytkownicy mogą używać tego identyfikatora w innych żądaniach podrzędnych w ramach tego samego wywołania interfejsu API. Zwiększa to wydajność przez uniknięcie cyklu zapisu i odczytu.

Listę typów żądań aktualizacji zbiorczej, podzielonej na różne kategorie, znajdziesz w tabeli w sekcji Operacje aktualizacji zbiorczej.

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

Odpowiedź

Ta przykładowa odpowiedź zbiorcza zawiera informacje o tym, jak zastosowano poszczególne żądania podrzędne w żądaniu zbiorczym. Pamiętaj, że UpdateCellsRequest nie zawiera odpowiedzi, więc wartość indeksu tablicy [1] składa się z pustych nawiasów klamrowych.

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]