Żądania zbiorcze

Ten dokument pokazuje, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę połączeń, które musi nawiązać klient. Przetwarzanie w grupach może zwiększyć wydajność aplikacji przez zmniejszenie liczby połączeń z siecią i zwiększenie przepustowości.

Omówienie

Każde połączenie utworzone przez klienta powoduje pewien narzut. Interfejs Sheets API obsługuje grupowanie, aby umożliwić klientowi umieszczanie wielu 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 jedną prośbę do serwera i otrzymywanie jednej odpowiedzi.

Zachęcamy użytkowników, aby zawsze wysyłali wiele żądań w ramach jednego zbiorczego żądania. Oto kilka przykładów sytuacji, w których możesz użyć grupowania:

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

Limity, autoryzacja i zależności

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

• Każde żądanie zbiorcze, w tym wszystkie żądania podrzędne, jest liczone jako 1 żądanie interfejsu API w ramach limitu użycia.
• Prośba zbiorcza jest uwierzytelniana tylko raz. To jedno uwierzytelnianie dotyczy wszystkich obiektów w prośbie o zbiorcze aktualizacji.
• Serwer przetwarza żądania podrzędne w tej samej kolejności, w jakiej występują w żądaniu zbiorczym. Kolejne podzapytania mogą zależeć od działań podjętych podczas wcześniejszych podzapytań. Na przykład w ramach tego samego zbiorczego żądania użytkownicy mogą wstawić tekst do istniejącego dokumentu, a następnie nadać mu styl.

Szczegóły wsadu

Zbiorcze żądanie składa się z jednego wywołania metody batchUpdate z wieloma podrzędnymi żądaniami, które na przykład dodają i formatują arkusz kalkulacyjny.

Każde żądanie jest weryfikowane przed zastosowaniem. Wszystkie podzapytania w ramach aktualizacji zbiorczej są stosowane w sposób atomowy. Oznacza to, że jeśli żądanie jest nieprawidłowe, cała aktualizacja kończy się niepowodzeniem i żadne z (potencjalnie zależnych) zmian nie zostaną zastosowane.

Niektóre odpowiedzi zawierają informacje o zgłoszonych żądaniach. Na przykład wszystkie żądania zbiorczego aktualizowania służące do dodawania obiektów zwracają odpowiedzi, dzięki którym możesz uzyskać dostęp do metadanych nowo dodanego obiektu, takich jak identyfikator lub tytuł.

Dzięki temu podejściu możesz utworzyć cały dokument Google za pomocą jednego interfejsu API, wysyłając prośbę o zbiorczą aktualizację z wieloma podzapytaniami.

Format żądania zbiorczego

Żądanie to pojedyncze żądanie JSON zawierające wiele zagnieżdżonych żądań podrzędnych z 1 wymaganym atrybutem: requests. Zapytania są tworzone w tablicy pojedynczych zapytań. Każde żądanie używa 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ź pojedynczego obiektu odpowiedzi.

Właściwość głównego obiektu JSON ma nazwę replies. Odpowiedzi są zwracane w tablicy, a każda odpowiedź na jedno z żądań zajmuje to samo miejsce w indeksie co odpowiadające mu żądanie. Niektóre żądania nie mają odpowiedzi, a odpowiedź w tym indeksie tablicy jest pusta.

Przykład

Ten przykład pokazuje użycie grupowania w interfejsie Sheets API.

Żądanie

Ten przykładowy pakiet żądań pokazuje, jak:

• Dodaj arkusz do dotychczasowego arkusza kalkulacyjnego, przypisując mu wartość sheetId 12345, za pomocą elementu AddSheetRequest.
• Dodaj dane do nowego arkusza, zaczynając od komórki A1, za pomocą funkcji UpdateCellsRequest.
• Dodaj do nowego arkusza namedRange lub widok filtra.

Dodanie identyfikatora arkusza w żądaniu umożliwia użytkownikom użycie tego identyfikatora w innych podzapytaniach w tym samym wywołaniu interfejsu API. Zwiększa to wydajność, ponieważ nie trzeba wykonywać cyklu zapisu-odczytu-zapisu.

Listę typów żądań zbiorczego uporządkowanych w różne kategorie znajdziesz w tabeli w sekcji Operacje zbiorczego aktualizowania.

{
   "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 zostały zastosowane poszczególne żądania podrzędne w ramach żądania zbiorczego. Zwróć uwagę, że UpdateCellsRequest nie zawiera odpowiedzi, więc wartość indeksu tablicy w [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
            }
         }
      }
   }
]