Żądania i odpowiedzi

Ten przewodnik przedstawia podstawowe metody żądania i odpowiedzi, które składają się na interfejs Google Docs API, oraz wyjaśnia, jak zaktualizować dokument zbiorczo.

Interfejs API Dokumentów Google możesz wywołać za pomocą żądania HTTP lub metody wywołania w bibliotece klienta w danym języku. Te dwa typy reklam są w dużej mierze równoważne.

Interfejs Google Docs API zwraca odpowiedź HTTP, która zwykle zawiera wynik wywołania żądania. Gdy używasz biblioteki klienta do wysyłania żądań, odpowiedzi są zwracane w sposób zależny od języka.

Metody żądania

Interfejs Docs API obsługuje te metody:

  • documents.create: utwórz pusty dokument w Dokumentach Google.
  • documents.get: zwraca pełną instancję wskazanego dokumentu. Możesz przeanalizować zwrócony obiekt JSON, aby wyodrębnić zawartość dokumentu, formatowanie i inne funkcje.
  • documents.batchUpdate: prześlij listę próśb o edycję, które mają być stosowane w dokumentach w postaci atomów, i zwróć listę wyników.

Metody documents.get i documents.batchUpdate wymagają parametru documentId, aby określić dokument docelowy. Metoda documents.create zwraca instancję utworzonego dokumentu, z którego możesz odczytać wartość documentId. Więcej informacji o documentId znajdziesz w artykule Identyfikator dokumentu.

Aktualizacje zbiorcze

Metoda documents.batchUpdate otrzymuje listę obiektów request, z których każdy określa jedno żądanie do wykonania. Możesz na przykład sformatować akapit, a następnie dodać obraz w tekście. Każde żądanie jest weryfikowane przed zastosowaniem, a żądania są przetwarzane zgodnie z kolejnością, w jakiej występują w prośbie zbiorczej.

Wszystkie żądania w ramach aktualizacji zbiorczej są stosowane w ciągu jednej operacji. Oznacza to, że jeśli żądanie nie jest prawidłowe, cała aktualizacja kończy się niepowodzeniem i żadne z (potencjalnie zależnych) zmian nie zostaną zastosowane.

Niektóre metody documents.batchUpdate zwracają informacje o zastosowanej prośbie. Te metody zwracają element odpowiedzi zawierający listę obiektów response. Inne żądania nie muszą zwracać informacji i wyświetlają pustą odpowiedź. Obiekty na liście odpowiedzi zajmują tę samą pozycję indeksu co odpowiednie żądanie.

Popularny wzorzec przesyłania żądań zbiorczych:

requests = []
requests.append(first request)
requests.append(second request)
...

body = ... & requests & ...

...batchUpdate(body)

Więcej informacji o tym, jak grupować wywołania interfejsu Docs API, znajdziesz w sprawdzonym sposobie wysyłania żądań zbiorczych. W documents.batchUpdate znajdziesz też dokumentację z informacjami o typach żądań i odpowiedzi.

Operacje zbiorczej aktualizacji

Istnieją różne typy próśb o aktualizację zbiorczą. Oto podział typów żądań na różne kategorie.

Obiekt DODAJ / WSTAW AKTUALIZACJA / ZASTĄPOWANIE USUŃ
Tekst InsertTextRequest ReplaceAllTextRequest
Style CreateParagraphBulletsRequest UpdateTextStyleRequest
UpdateParagraphStyleRequest
UpdateTableCellStyleRequest
UpdateTableRowStyleRequest
UpdateDocumentStyleRequest
UpdateSectionStyleRequest 		DeleteParagraphBulletsRequest
Zakresy nazwane CreateNamedRangeRequest ReplaceNamedRangeContentRequest DeleteNamedRangeRequest
DeleteContentRangeRequest
Obrazy InsertInlineImageRequest ReplaceImageRequest
Tabele InsertTableRequest
InsertTableRowRequest
InsertTableColumnRequest
 UpdateTableColumnPropertiesRequest
MergeTableCellsRequest
UnmergeTableCellsRequest
PinTableHeaderRowsRequest		 DeleteTableRowRequest
DeleteTableColumnRequest
Obiekty strony (w tym nagłówki i stopki) InsertPageBreakRequest
CreateHeaderRequest
CreateFooterRequest
CreateFootnoteRequest
InsertSectionBreakRequest		 DeletePositionedObjectRequest
DeleteHeaderRequest
DeleteFooterRequest