簡介

Google Slides API 可讓您建立及修改 Google 簡報檔案。

應用程式可與 Google Slides API 整合,以根據使用者和系統提供的資料,自動建立精美的簡報。例如,您可以使用資料庫中的客戶詳細資料,然後將這些詳細資料與預先設計的範本和選取的設定選項結合,以極快的時間手動建立完成的簡報。

API 總覽

「簡報」集合提供在簡報中取得和更新元素的方法。

您在使用 Slides API 的大部分工作,可能都會建立和更新簡報。方法是使用 batchUpdate 方法;此方法採用 Request 物件清單,讓您進行以下操作:

  • 建立簡報
  • 在投影片中加入元素,例如形狀或表格
  • 插入、變更及移除文字
  • 將轉換套用至元素
  • 變更投影片的順序

詳情請參閱批次更新一文。請參閱「入門指南」中的簡單範例,瞭解如何使用 API。

簡報結構

Slides API 的簡報是由含有頁面元素的頁面組成。

簡報編號可透過下列網址取得:

https://docs.google.com/presentation/d/presentationId/edit

簡報 ID 是包含字母、數字與某些特殊字元的字串。下列規則運算式可用來從 Google 試算表網址擷取簡報 ID:

/presentation/d/([a-zA-Z0-9-_]+)

如果您熟悉 Drive API,presentationId 會對應至檔案資源的 ID。

網頁和網頁元素會以物件 ID 來識別。

Pages

Google 簡報包含以下類型的網頁:

碩士 投影片主投影片會定義預設文字樣式、背景及網頁元素,顯示在所有使用這個主投影片的所有投影片中。所有投影片都必須出現的網頁元素都必須新增至主投影片。大部分簡報中都有一個主投影片,但有些簡報則可能有多個 (甚至沒有)。
版面配置 使用版面配置時,系統預設會在版面配置中以網頁元素排列網頁元素。每個版面配置都與一個主要執行個體相關聯。
簡報 這類頁面含有您要向觀眾分享的內容。 大部分投影片都是運用主投影片和版面配置來呈現。您可以指定每張投影片在建立時要使用的版面配置。
Notes 這些頁麵包含簡報內容,包括符合投影片演講者備忘稿的形狀。每張投影片都有一個對應的筆記頁面,您只能使用 Slides API 修改演講者備忘稿形狀的文字。
記事大師 Notes 主投影片會定義所有記事頁面的預設文字樣式和頁面元素。使用簡報 API 中的 Notes 主程式處於唯讀狀態。

網頁元素

網頁元素是指放在網頁上的視覺元件,API 提供幾種類型的網頁元素:

群組 系統會將一組網頁元素視為個別單元。可同時移動、縮放及旋轉。
形狀 純視覺物件,例如矩形、刪節號和文字方塊。 形狀可以包含文字,因此是製作投影片時最常使用的頁面元素。
圖片 將圖片匯入簡報。
影片 影片已匯入 Google 簡報。
折線圖 視覺線、曲線或連接線。
資料表 內容格線。
文字藝術 行為類似圖像的視覺文字元素。
試算表圖表 將 Google 試算表中的圖表匯入簡報。

批次更新

batchUpdate 方法可讓您更新簡報的許多層面。系統會將變更以批次方式分組,如果一個要求失敗,系統就不會編寫其他 (可能依附) 變更。

batchUpdate 方法的運作方式為取得一或多個 Request 物件,每個物件都指定要執行單一類型的要求。要求種類有很多,下面是按要求分類的各類型要求細目。

使用簡報: CreateSlideRequest
UpdateSlidesPositionRequest
重複的物件要求
UpdatePagePropertiesRequest
DeleteObjectRequest
使用網頁元素: CreateShapeRequest
CreateLineRequest
UpdatePageElementTransformRequest
UpdateShapePropertiesRequest
重複的物件要求
DeleteObjectRequest
使用資料表: CreateTableRequest
InsertTableRowsRequest
InsertTableColumnsRequest
DeleteTableRowRequest
DeleteTableColumnRequest
UpdateTableRowPropertiesRequest
UpdateTableColumnPropertiesRequest
UpdateTableBorderPropertiesRequest
UpdateTableCellPropertiesRequest
MergeTableCellsRequest
UnmergeTableCellsRequest
DeleteObjectRequest
使用圖表: CreateSheetsChartRequest
RefreshSheetsChartRequest
取代 AllShapesWithSheetsChartRequest
DeleteObjectRequest
使用圖片和影片: CreateImageRequest
CreateVideoRequest
UpdateImagePropertiesRequest
UpdateVideoPropertiesRequest
取代 AllShapesWithImageRequest
重複的物件要求
DeleteObjectRequest
使用文字: InsertTextRequest
DeleteTextRequest
取代 AllTextRequest
CreateParagraphBulletsRequest
DeleteParagraphBulletsRequest
UpdateTextStyleRequest
UpdateParagraphStyleRequest

batchUpdate 方法會傳回一個回應主體,其中包含每個要求的 Response。每個回應都會包含與對應要求相同的索引;如果要求沒有適用的回應,則該索引的回應將會是空白的。一般來說,各種 Create 要求都有回應,因此您知道新加入物件的 ID。

使用物件 ID

Slides 的簡報是由頁面頁面元素所組成。這些物件包含簡報中不重複的物件 ID 字串。

在建立時指定物件 ID

使用 batchUpdate 方法建立網頁或頁面元素時,您可以視需要為新物件指定物件 ID。如此一來,您就可以在同一個批次更新要求中建立物件並加以修改,以盡量減少對 Slides API 的呼叫次數,並降低配額用量

在多數情況下,我們會建議您產生隨機的物件 ID。例如,如果您使用 Java,則 java.util.UUID.randomUUID().toString() 可正常運作。

如果您的應用程式想要追蹤較長時間的物件,請不要依賴物件 ID,因為可能會變更。詳情請參閱以下章節。

不使用物件 ID 來追蹤物件

當您提出 Slides API 要求時,系統通常會保留物件 ID。(方法的參考說明文件中會包含任何例外狀況)。使用 Drive API 建立整個簡報的副本時,也會保留物件 ID。

但是,在簡報 UI 中變更簡報後,您就無法再依附於物件 ID。舉例來說,如果有人使用簡報 UI 複製頁面元素,然後刪除原始元素,該頁面元素現在會有新的專屬 ID,而先前透過 API 提供的 ID 將會遺失。因此,建議您不要將物件 ID 儲存在應用程式的儲存空間中。您應改為根據文字內容或替代文字在簡報中尋找物件。

新建的簡報通常會使用一組一致的 ID,適用於預設投影片、主投影片和文字方塊。這些 ID 可能隨時會有變動,因此我們不建議您使用這項功能。請改用呼叫 create()get() 傳回的簡報物件,找出您想要修改的元素。