Method: documents.batchUpdate

Menerapkan satu atau beberapa pembaruan pada dokumen.

Setiap request divalidasi sebelum diterapkan. Jika ada permintaan yang tidak valid, seluruh permintaan akan gagal dan tidak ada yang akan diterapkan.

Beberapa permintaan memiliki replies untuk memberi Anda beberapa informasi tentang cara penerapannya. Permintaan lainnya tidak perlu menampilkan informasi; setiap permintaan ini menampilkan respons kosong. Urutan balasan sesuai dengan urutan permintaan.

Misalnya, Anda memanggil batchUpdate dengan empat pembaruan, dan hanya pembaruan ketiga yang menampilkan informasi. Respons akan memiliki dua balasan kosong, balasan untuk permintaan ketiga, dan balasan kosong lainnya, dalam urutan tersebut.

Karena pengguna lain mungkin sedang mengedit dokumen, dokumen mungkin tidak mencerminkan perubahan Anda secara persis: perubahan Anda mungkin diubah sehubungan dengan perubahan kolaborator. Jika tidak ada kolaborator, dokumen akan mencerminkan perubahan Anda. Bagaimanapun juga, pembaruan dalam permintaan Anda dijamin akan diterapkan bersama secara atomik.

Permintaan HTTP

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

URL ini menggunakan sintaksis gRPC Transcoding.

Parameter jalur

Parameter
documentId

string

ID dokumen yang akan diperbarui.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi JSON 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Kolom
requests[]

object (Request)

Daftar pembaruan yang akan diterapkan pada dokumen.
writeControl

object (WriteControl)

Memberikan kontrol atas cara eksekusi permintaan tulis.

Isi respons

Pesan respons dari permintaan documents.batchUpdate.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi JSON 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
Kolom
documentId

string

ID dokumen tempat pembaruan diterapkan.
replies[]

object (Response)

Balasan pembaruan. Hal ini dipetakan 1:1 dengan pembaruan, meskipun balasan untuk beberapa permintaan mungkin kosong.
writeControl

object (WriteControl)

Kontrol penulisan yang diperbarui setelah menerapkan permintaan.
suggestionResponses[]

object (SuggestionResponse)

Saran yang terpengaruh oleh setiap update. Hal ini dipetakan 1:1 dengan pembaruan.

commentUpdateState

enum (CommentUpdateState)

Apakah pembaruan komentar diterapkan dalam permintaan batch.

Cakupan otorisasi

Memerlukan salah satu cakupan OAuth berikut:

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

Untuk mengetahui informasi selengkapnya, lihat Panduan otorisasi.

WriteControl

Memberikan kontrol atas cara eksekusi permintaan tulis.

Representasi JSON 
{
  "writeMode": enum (WriteMode),

  "requiredRevisionId": string,
  "targetRevisionId": string
}
Kolom
writeMode

enum (WriteMode)

Cara pembaruan permintaan harus diterapkan ke dokumen.

Jika tidak ditentukan, pembaruan permintaan akan diterapkan sebagai pengeditan normal.

Kolom union control. Menentukan revisi dokumen yang akan ditulis dan cara permintaan harus berperilaku jika revisi tersebut bukan revisi dokumen saat ini. Jika kedua kolom tidak ditentukan, pembaruan akan diterapkan pada revisi terbaru. control hanya dapat berupa salah satu dari berikut:
requiredRevisionId

string

revision ID opsional dokumen yang diterapkan permintaan penulisan. Jika ini bukan revisi terbaru dokumen, permintaan tidak diproses dan menampilkan error permintaan buruk 400.

Jika ID revisi yang diperlukan ditampilkan dalam respons, ID tersebut menunjukkan ID revisi dokumen setelah permintaan diterapkan.
targetRevisionId

string

Target revision ID opsional dari dokumen yang diterapkan permintaan penulisan.

Jika perubahan kolaborator terjadi setelah dokumen dibaca menggunakan API, perubahan yang dihasilkan oleh permintaan penulisan ini diterapkan terhadap perubahan kolaborator. Hal ini akan menghasilkan revisi baru dokumen yang menggabungkan perubahan kolaborator dan perubahan dalam permintaan, dengan server Dokumen menyelesaikan perubahan yang bertentangan. Saat menggunakan ID revisi target, klien API dapat dianggap sebagai kolaborator lain dalam dokumen.

ID revisi target hanya dapat digunakan untuk menulis ke versi terbaru dokumen. Jika revisi target terlalu jauh di belakang revisi terbaru, permintaan tidak akan diproses dan akan menampilkan error 400 bad request. Permintaan harus dicoba lagi setelah mengambil versi terbaru dokumen. Biasanya, ID revisi tetap valid untuk digunakan sebagai revisi target selama beberapa menit setelah dibaca, tetapi untuk dokumen yang sering diedit, periode ini mungkin lebih singkat.

WriteMode

Menentukan cara pembaruan permintaan diterapkan ke dokumen.

Enum
WRITE_MODE_UNSPECIFIED Mode penulisan tidak ditentukan. Default-nya adalah perilaku EDIT.
EDIT Terapkan semua update sebagai pengeditan normal.
SUGGEST Terapkan semua pembaruan sebagai saran.

SuggestionResponse

Saran yang terpengaruh oleh update tertentu.

Representasi JSON 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
Kolom
createdSuggestionIds[]

string

ID saran yang dibuat selama pembaruan.
updatedSummarySuggestionIds[]

string

ID saran yang ringkasannya diperbarui selama pembaruan.
deletedSuggestionIds[]

string

ID saran yang dihapus selama update.
acceptedSuggestionIds[]

string

ID saran yang diterima selama pembaruan.
rejectedSuggestionIds[]

string

ID saran yang ditolak selama pembaruan.

CommentUpdateState

Status pembaruan komentar dalam permintaan batch.

Enum
COMMENT_UPDATE_STATE_UNSPECIFIED Status pembaruan komentar tidak ditentukan.
NO_UPDATES_REQUESTED Tidak ada pembaruan komentar yang diminta dalam permintaan batch.
ALL_SAVED Semua pembaruan komentar yang diminta telah diterapkan dalam permintaan batch.
ALL_FAILED_UNKNOWN_REASON Semua pembaruan komentar yang diminta gagal.