หน้านี้ได้รับการแปลโดย Cloud Translation API

ย้ายข้อมูลจาก Sheets API v3

หากมีแอปที่ใช้ Google Sheets API v3 อยู่แล้ว คุณจะย้ายข้อมูลไปยัง Google Sheets API v4 ได้ เวอร์ชัน v4 เป็นแบบ JSON มีอินเทอร์เฟซที่ใช้งานง่ายขึ้น และเพิ่มฟังก์ชันการทำงานจำนวนมากที่เวอร์ชัน v3 ไม่มี

หน้านี้แสดงการแมประหว่างคำสั่ง Sheets API v3 เวอร์ชันเก่ากับการดำเนินการที่เทียบเท่าใน Sheets API v4 การแมปส่วนใหญ่จะมุ่งเน้นที่คอลเล็กชัน spreadsheets.values ซึ่งมีฟังก์ชันการอ่านและเขียนเซลล์โดยตรง ส่วนแง่มุมอื่นๆ เช่น การเพิ่มชีตหรืออัปเดตพร็อพเพอร์ตี้ชีตจะจัดการโดยคอลเล็กชันสเปรดชีต โปรดทราบว่าโครงสร้าง JSON ของ v4 API ใช้งานร่วมกับโครงสร้าง XML ที่ใช้กับ v3 ไม่ได้

ดูข้อมูลเพิ่มเติมเกี่ยวกับแหล่งข้อมูลที่มีอยู่ใน Sheets v4 API ได้ที่เอกสารอ้างอิง API

สัญกรณ์และข้อกำหนด

API เวอร์ชัน 3 จะเรียกชีตภายในสเปรดชีตหนึ่งๆ ว่า "เวิร์กชีต" ซึ่งตรงกับคําว่า "ชีต" ที่ v4 API ใช้

API มักกำหนดให้คุณระบุรหัสสเปรดชีตของสเปรดชีตที่คุณกำลังทำงานอยู่ นอกจากนี้ ผู้ใช้ยังต้องระบุรหัสของชีตที่จะดัดแปลงด้วย ค่าเหล่านี้จะปรากฏเป็นส่วนหนึ่งของ URL ปลายทางของ API, พารามิเตอร์การค้นหา หรือเป็นส่วนหนึ่งของเนื้อหาคำขอ ในหน้านี้ เป็นตัวยึดตําแหน่ง spreadsheetId และ sheetId ซึ่งหมายถึงรหัสสเปรดชีตและรหัสชีตตามลําดับ เมื่อใช้วิธีการที่อธิบายไว้ในหน้านี้ ให้แทนที่รหัสจริงในตำแหน่งเหล่านี้

นอกจากนี้ v3 API จะกำหนดรหัสให้กับแถวที่ดึงข้อมูลโดยใช้ฟีดรายการด้วย ซึ่งจะแสดงในหน้านี้ด้วยตัวยึดตําแหน่ง rowId

ให้สิทธิ์คำขอ

เมื่อแอปทำงาน แอปจะขอให้ผู้ใช้ให้สิทธิ์บางอย่าง โดยขอบเขตที่คุณระบุในแอปพลิเคชันจะเป็นตัวกำหนดสิทธิ์ที่แอปขอ

v3 API

Sheets API v3 ทำงานด้วยขอบเขตการให้สิทธิ์เดียว ดังนี้

https://spreadsheets.google.com/feeds

ซึ่งเป็นชื่อแทนของ

https://www.googleapis.com/auth/spreadsheets

คุณจะใช้รูปแบบขอบเขตใดก็ได้

v4 API

ชีต API v4 ใช้ชุดขอบเขตต่อไปนี้อย่างน้อย 1 รายการ

https://www.googleapis.com/auth/spreadsheets.readonly
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive

ใช้ขอบเขตที่อ่านอย่างเดียวหากแอปพลิเคชันของคุณไม่จําเป็นต้องแก้ไขชีตหรือพร็อพเพอร์ตี้ชีตของผู้ใช้ ใช้ขอบเขตสเปรดชีตแทนขอบเขตไดรฟ์หากแอปพลิเคชันไม่จำเป็นต้องเข้าถึงไดรฟ์ทั่วไป

ระดับการแชร์

ใน API เวอร์ชันเก่า คำว่าระดับการเข้าถึงใช้เพื่อบ่งบอกความพร้อมใช้งานของสเปรดชีตหนึ่งๆ

v3 API

ชีต API v3 แสดงระดับการเข้าถึงในปลายทางโดยตรง สเปรดชีต public ได้ "เผยแพร่ไปยังเว็บ" แล้ว ดังนั้น API จึงเข้าถึงได้โดยไม่ต้องมีสิทธิ์เข้าถึง ส่วนสเปรดชีต private จำเป็นต้องมีการตรวจสอบสิทธิ์ ระดับการแชร์จะระบุไว้ในปลายทางหลังรหัสสเปรดชีต ดังนี้

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

v4 API

ในชีต API v4 เวอร์ชันใหม่ ไม่มีการประกาศระดับการเข้าถึงอย่างชัดเจน การเรียก API จะใช้รหัสสเปรดชีต หากแอปพลิเคชันไม่มีสิทธิ์เข้าถึงสเปรดชีตที่ระบุ ระบบจะแสดงข้อผิดพลาด ไม่เช่นนั้น ระบบจะโทรต่อ

การฉายภาพ

Sheets API v3 ใช้คำว่าการฉายภาพเพื่ออ้างอิงชุดข้อมูลที่แสดงผลจากการเรียก API หนึ่งๆ ไม่ว่าจะเป็นทั้งหมดหรือชุดย่อยแบบคงที่ที่กําหนดไว้ใน API ชีต API v4 ไม่ได้ใช้การโปรเจ็กต์ แต่จะช่วยให้คุณควบคุมข้อมูลที่แสดงผลได้มากขึ้น

v3 API

การตั้งค่าการโปรเจ็กต์ที่เป็นไปได้ใน Sheets API v3 มีเพียง 2 แบบเท่านั้น full การคาดการณ์จะแสดงข้อมูลที่พร้อมใช้งานทั้งหมด ส่วน basic จะแสดงข้อมูลชุดย่อยที่เล็กลงและคงที่ (สำหรับฟีดเวิร์กชีต รายการ และเซลล์) เช่นเดียวกับระดับการเข้าถึง คุณต้องระบุโปรเจ็กชันในปลายทาง API (หลังจากการตั้งค่าระดับการเข้าถึง) ดังนี้

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic

ชุดข้อมูลย่อยขนาดเล็กที่โปรเจ็กชัน basic ให้ไว้มีประโยชน์ในการทําให้โค้ดมีประสิทธิภาพมากขึ้น แต่ปรับแต่งไม่ได้

v4 API

แม้ว่า Sheets API v4 จะแสดงชุดข้อมูลทั้งหมดได้ แต่ก็ไม่ได้กำหนดชุดย่อยแบบคงที่ซึ่งคล้ายกับการตั้งค่าระดับการแชร์ basic ของ Sheets API v3 เมธอดในคอลเล็กชันสเปรดชีตจะจํากัดจํานวนข้อมูลที่แสดงผลผ่านการใช้พารามิเตอร์การค้นหาฟิลด์

เช่น การค้นหาต่อไปนี้จะแสดงเฉพาะชื่อชีตทั้งหมดในสเปรดชีตหนึ่งๆ

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title

สร้างสเปรดชีต

v3 API

ชีต API v3 ไม่มีวิธีสร้างสเปรดชีตใหม่ แต่จะใช้เมธอด Drive API Files.create เพื่อสร้างไฟล์สเปรดชีตใหม่ได้ ซึ่งกำหนดให้แอปพลิเคชันประกาศขอบเขต https://www.googleapis.com/auth/drive

v4 API

นอกจากนี้ คุณยังใช้เมธอด Drive API Files.create กับ Sheets API v4 ได้ด้วย แต่แอปพลิเคชันต้องระบุขอบเขต https://www.googleapis.com/auth/drive

Sheets API v4 มีเมธอด spreadsheets.create ที่เป็นทางเลือกเทียบเท่า ซึ่งสามารถเพิ่มชีต ตั้งค่าสเปรดชีตและชีต รวมถึงเพิ่มช่วงที่มีชื่อได้ (ไม่บังคับ) ตัวอย่างเช่น คำสั่งต่อไปนี้จะสร้างสเปรดชีตใหม่และตั้งชื่อเป็น "NewTitle"

POST https://sheets.googleapis.com/v4/spreadsheets

{
 "properties": {"title": "NewTitle"}
}

แสดงรายการสเปรดชีตของผู้ใช้ที่ได้รับการตรวจสอบแล้ว

v3 API

ฟีด Sheets API v3 ช่วยให้แอปพลิเคชันเรียกข้อมูลรายการสเปรดชีตทั้งหมดที่ผู้ใช้ที่ผ่านการตรวจสอบสิทธิ์เข้าถึงได้ ปลายทางของฟีดสเปรดชีตมีดังนี้

GET https://spreadsheets.google.com/feeds/spreadsheets/private/full

v4 API

Sheets API v4 ไม่มีการดำเนินการที่เฉพาะเจาะจงนี้ เราขอแนะนําให้ย้ายข้อมูลแอปของคุณเพื่อใช้ขอบเขต drive.file ร่วมกับเครื่องมือเลือกของ Google สําหรับการเลือกสเปรดชีต

ในกรณีที่จำเป็นต้องแสดงรายการสเปรดชีต คุณสามารถจำลองรายการได้ผ่านเมธอด Drive API Files.list โดยใช้การค้นหา mimeType ดังนี้

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

การใช้เมธอด files.list ของ Drive API เพื่อแสดงรายการสเปรดชีตทั้งหมดของผู้ใช้ต้องใช้ขอบเขตที่จํากัด

ดึงข้อมูลเมตาของชีต

ชีต API v3 มีฟีดสําหรับเข้าถึงข้อมูลเมตาของชีตที่อยู่ในสเปรดชีตหนึ่งๆ (เข้าถึงข้อมูลแถวและเซลล์ผ่านฟีดแยกต่างหาก) ข้อมูลเมตาประกอบด้วยข้อมูลต่างๆ เช่น ชื่อชีตและข้อมูลขนาด

เมธอด spreadsheets.get ของ Sheets API v4 จะให้สิทธิ์เข้าถึงข้อมูลนี้และอีกมากมาย

v3 API

ฟีดเวิร์กชีตเข้าถึงได้จากปลายทาง API นี้ (โดยใช้ส่วนหัวการให้สิทธิ์ที่เหมาะสม)

GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

การตอบกลับคําขอนี้มีโครงสร้างคล้ายกับตัวอย่างนี้ โดยมีข้อมูลของชีตแต่ละชีตอยู่ใน <entry> แยกต่างหาก

<feed xmlns="http://www.w3.org/2005/Atom"
    xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006"
    xmlns:gd="http://schemas.google.com/g/2005"
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <title type="text">Groceries R Us</title>
  <link rel="alternate" type="text/html"
      href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
  <link rel="http://schemas.google.com/g/2005#feed"
      type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <link rel="self" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>fitz@example.com</email>
  </author>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1</openSearch:itemsPerPage>
  <entry gd:etag='"YDwqeyI."'>
    <id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
    <updated>2006-11-17T18:23:45.173Z</updated>
    <title type="text">Sheet1</title>
    <content type="text">Sheet1</content>
    <link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
        type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
    <link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
        type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
    <link rel="self" type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
    <link rel="edit" type="application/atom+xml"
        href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
    <gs:rowCount>100</gs:rowCount>
    <gs:colCount>20</gs:colCount>
  </entry>
</feed>

v4 API

คุณสามารถใช้เมธอด spreadsheets.get เพื่อรับพร็อพเพอร์ตี้ชีตและข้อมูลเมตาอื่นๆ ได้ ซึ่งมากกว่าสิ่งที่มีให้โดยใช้ Sheets API v3 หากต้องการอ่านเฉพาะพร็อพเพอร์ตี้ชีต ให้ตั้งค่าพารามิเตอร์การค้นหา includeGridData เป็น false เพื่อป้องกันไม่ให้รวมข้อมูลเซลล์สเปรดชีต

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false

การตอบกลับ Spreadsheet จะมีอาร์เรย์ออบเจ็กต์ Sheet โดยคุณจะเห็นชื่อชีตและข้อมูลขนาดโดยเฉพาะในส่วนองค์ประกอบ SheetProperties ของออบเจ็กต์เหล่านี้ เช่น

{
  "spreadsheetId": spreadsheetId,
  "sheets": [
      {"properties": {
          "sheetId": sheetId,
          "title": "Sheet1",
          "index": 0,
          "gridProperties": {
              "rowCount": 100,
              "columnCount": 20,
              "frozenRowCount": 1,
              "frozenColumnCount": 0,
              "hideGridlines": false
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

เพิ่มชีตลงในสเปรดชีต

ทั้ง 2 API ให้คุณเพิ่มชีตใหม่ลงในสเปรดชีตที่มีอยู่ได้

v3 API

Sheets API v3 สามารถเพิ่มเวิร์กชีตใหม่ลงในสเปรดชีตได้โดยส่งคำขอ POST (ที่ตรวจสอบสิทธิ์แล้ว) ต่อไปนี้ คุณระบุขนาดของชีตใหม่ได้ดังนี้

POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <title>Expenses</title>
  <gs:rowCount>50</gs:rowCount>
  <gs:colCount>10</gs:colCount>
</entry>

v4 API

คุณเพิ่มชีตใหม่ได้โดยส่งคำขอAddSheet ในเมธอด spreadsheets.batchUpdate คุณสามารถระบุพร็อพเพอร์ตี้ชีตสำหรับชีตใหม่ได้ในส่วนเนื้อหาคำขอ โดยพร็อพเพอร์ตี้ทั้งหมดเป็นตัวเลือก การให้ชื่อที่ใช้กับชีตที่มีอยู่จะเป็นข้อผิดพลาด

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [{
      "addSheet": {
          "properties": {
            "title": "Expenses",
            "sheetType": "GRID",
            "gridProperties": {
              "rowCount": 50,
              "columnCount": 10
            }
          }
      }
  }],
}

เปลี่ยนชื่อและขนาดชีต

Sheets API v3 ช่วยให้คุณอัปเดตชื่อและสภาพของชีตได้ ส่วน Sheets API v4 ก็ทำเช่นเดียวกัน แต่ยังสามารถใช้อัปเดตพร็อพเพอร์ตี้อื่นๆ ของสเปรดชีตได้ด้วย โปรดทราบว่าการลดขนาดชีตอาจทำให้ระบบลบข้อมูลในเซลล์ที่ครอบตัดออกโดยไม่มีการเตือน

v3 API

หากต้องการเปลี่ยนชื่อหรือขนาดของเวิร์กชีต ให้เริ่มด้วยการเรียกใช้ฟีดเวิร์กชีตและค้นหารายการเวิร์กชีตที่ต้องการซึ่งมี URL edit อัปเดตข้อมูลเมตาของเวิร์กชีตและส่งเป็นเนื้อหาของPUTคำขอ ไปยัง URL การแก้ไข เช่น

PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version

<entry>
  <id>
    https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
  </id>
  <updated>2007-07-30T18:51:30.666Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
  <title type="text">Expenses</title>
  <content type="text">Expenses</content>
  <link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
    type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
  <link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
    type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
  <gs:rowCount>45</gs:rowCount>
  <gs:colCount>15</gs:colCount>
</entry>

v4 API

หากต้องการอัปเดตขนาด ชื่อ และพร็อพเพอร์ตี้อื่นๆ ของชีต ให้ส่งคำขอupdateSheetProperties ในเมธอด spreadsheets.batchUpdate เนื้อหาของคำขอ POST ควรมีพร็อพเพอร์ตี้ที่จะเปลี่ยนแปลง และพารามิเตอร์ fields ควรแสดงรายการพร็อพเพอร์ตี้เหล่านั้นอย่างชัดเจน (หากต้องการอัปเดตพร็อพเพอร์ตี้ทั้งหมด ให้ใช้ fields:"*" เป็นทางลัดในการแสดงรายการทั้งหมด) ตัวอย่างเช่น คำสั่งต่อไปนี้จะระบุว่าควรอัปเดตพร็อพเพอร์ตี้ชื่อและสภาพของชีตที่มีรหัสที่ระบุ

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [
    {
      "updateSheetProperties": {
          "properties": {
            "sheetId": sheetId,
            "title": "Expenses",
            "gridProperties": {
              "rowCount": 45,
              "columnCount": 15,
            }
          },
          "fields": "title,gridProperties(rowCount,columnCount)"
     }
   }
  ],
}

หากต้องการเรียกข้อมูล sheetId ของชีต ให้ใช้เมธอดสเปรดชีต spreadsheets.get

ลบชีต

API ทั้ง 2 รายการสามารถนำชีตออกจากสเปรดชีตหนึ่งๆ ได้

v3 API

หากต้องการลบเวิร์กชีต ให้เริ่มด้วยการเรียกข้อมูลฟีดเวิร์กชีต จากนั้นส่งคำขอ DELETE ใน URL edit ของรายการเวิร์กชีตเป้าหมาย

DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version

v4 API

หากต้องการลบชีต ให้ส่งคำขอDeleteSheet ในเมธอด spreadsheets.batchUpdate เนื้อความของคำขอ POST ควรมีเฉพาะ sheetId สำหรับชีตที่จะลบ เช่น

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": sheetId
      }
    }
  ],
}

หากต้องการเรียกข้อมูล sheetId ของชีตแต่ละชีต ให้ใช้เมธอด spreadsheets.get ของสเปรดชีต

ดึงข้อมูลแถว

ฟีดแถวรายการเป็นหนึ่งใน 2 วิธีของ Sheets API v3 ในการเข้าถึงข้อมูลภายในเซลล์ของสเปรดชีต (อีกวิธีหนึ่งคือฟีดเซลล์) ฟีดแถวมีไว้เพื่อรองรับการดำเนินการทั่วไปของสเปรดชีต (การอ่านทีละแถว การเพิ่มแถวท้าย การเรียงลำดับ) แต่มีการคาดเดาบางอย่างที่ทำให้ไม่เหมาะกับงานบางอย่าง กล่าวโดยละเอียดคือ ฟีดรายการจะถือว่าแถวว่างเป็นจุดสิ้นสุดของฟีด และส่วนหัวที่ต้องระบุจะอยู่ในแถวแรกของชีต

ในทางตรงกันข้าม Sheets API v4 ไม่ได้ใช้วิธีการเข้าถึงที่เจาะจงแถว แต่ระบบจะเข้าถึงข้อมูลเซลล์ชีตโดยการอ้างอิงช่วงที่ต้องการโดยใช้การเขียน A1 ซึ่งอาจเป็นกลุ่มเซลล์ แถวทั้งแถว คอลัมน์ทั้งคอลัมน์ หรือทั้งชีต นอกจากนี้ API ยังเข้าถึงชุดเซลล์ที่ไม่ต่อเนื่องกันได้อีกด้วย

v3 API

หากต้องการระบุ URL ของฟีดตามรายการสําหรับเวิร์กชีตหนึ่งๆ ให้ดึงข้อมูลฟีดเวิร์กชีตและค้นหา URL ของฟีดรายการในรายการเวิร์กชีตที่ต้องการ

หากต้องการเรียกข้อมูลฟีดตามรายการ ให้ส่งคําขอ GET ไปยัง URL ของฟีดรายการโดยใช้ส่วนหัวการให้สิทธิ์ที่เหมาะสม เช่น

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

การตอบกลับคําขอนี้ประกอบด้วยรายการต่างๆ ซึ่งรวมถึงรายการที่สอดคล้องกับแถวที่เฉพาะเจาะจง ระบบจะอ้างอิงเซลล์แต่ละเซลล์ตามชื่อที่ระบุไว้ในแถวส่วนหัวของสเปรดชีต (ต้องระบุ) ตัวอย่างเช่น รายการแถวเดียวนี้

<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
  <id>rowId</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
      term="http://schemas.google.com/spreadsheets/2006#list"/>
  <title type="text">Bingley</title>
  <content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
  <link rel="self" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
  <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
  <gsx:name>Bingley</gsx:name>
  <gsx:hours>10</gsx:hours>
  <gsx:items>2</gsx:items>
  <gsx:ipm>0.0033</gsx:ipm>
</entry>

โดยค่าเริ่มต้น ระบบจะแสดงผลแถวที่แสดงในฟีดรายการตามลําดับแถว Sheets API v3 มีพารามิเตอร์การค้นหาสำหรับเปลี่ยนลําดับดังกล่าว

ลำดับย้อนกลับ

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true

เรียงลําดับตามคอลัมน์ที่เฉพาะเจาะจง

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?orderby=column:lastname

Sheets API v3 ยังอนุญาตให้กรองแถวที่เฉพาะเจาะจงผ่าน Structured Query (อ้างอิงตามส่วนหัวของคอลัมน์) ได้ด้วย

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?sq=age>25%20and%20height<175

v4 API

เมื่อใช้ Sheets API v4 คุณจะเรียกข้อมูลแถวตามช่วงได้โดยใช้เมธอด spreadsheets.values.get หรือ spreadsheets.values.batchGet ตัวอย่างเช่น คำสั่งต่อไปนี้จะแสดงผลทุกแถวใน "ชีต 1"

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1

การตอบกลับคําขอนี้มีโครงสร้างคล้ายกับตัวอย่างต่อไปนี้

{
  "range": "Sheet1",
  "majorDimension": "ROWS",
  "values": [["Name", "Hours", "Items", "IPM"],
             ["Bingley", "10", "2", "0.0033"],
             ["Darcy", "14", "6", "0.0071"]]
}

เซลล์ว่างที่อยู่ท้ายจะไม่รวมอยู่ในคำตอบเมื่อดึงข้อมูลทั้งแถว คอลัมน์ หรือชีต

Sheets API v4 ไม่มีพารามิเตอร์การค้นหาตามลําดับแถวที่ Sheets API v3 มี การเปลี่ยนลำดับกลับนั้นง่ายมาก เพียงประมวลผลอาร์เรย์ values ที่แสดงผลตามลำดับย้อนกลับ ระบบไม่รองรับการอ่านตามคอลัมน์ แต่สามารถจัดเรียงข้อมูลในสเปรดชีต (โดยใช้คําขอ SortRange) แล้วอ่านได้

ปัจจุบัน Sheets API v4 ไม่มีคำค้นหาที่มีโครงสร้างเทียบเท่าโดยตรงกับ Sheets API v3 อย่างไรก็ตาม คุณสามารถเรียกข้อมูลที่เกี่ยวข้องและจัดเรียงข้อมูลได้ตามต้องการในแอปพลิเคชัน

เพิ่มแถวข้อมูลใหม่

คุณเพิ่มแถวข้อมูลใหม่ลงในชีตได้โดยใช้ API ใดก็ได้

v3 API

หากต้องการระบุ URL ของฟีดตามรายการสําหรับเวิร์กชีตหนึ่งๆ ให้ดึงข้อมูลฟีดเวิร์กชีต แล้วค้นหา URL ของโพสต์ในรายการเวิร์กชีตที่สนใจ

หากต้องการเพิ่มแถวข้อมูล ให้ส่งคําขอ POST ไปยัง URL ของโพสต์โดยใช้ส่วนหัวการให้สิทธิ์ที่เหมาะสม เช่น

POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

เนื้อหาของคําขอ POST ควรมีรายการสําหรับข้อมูลแถวที่จะเพิ่ม โดยมีเซลล์แต่ละเซลล์ที่อ้างอิงโดยส่วนหัวของคอลัมน์ ดังนี้

<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
  <gsx:hours>2</gsx:hours>
  <gsx:ipm>0.5</gsx:ipm>
  <gsx:items>60</gsx:items>
  <gsx:name>Elizabeth</gsx:name>
</entry>

ระบบจะเพิ่มแถวใหม่ต่อท้ายชีตที่ระบุ

v4 API

เมื่อใช้ Sheets API v4 คุณสามารถเพิ่มแถวต่อท้ายได้โดยใช้เมธอด spreadsheets.values.append ตัวอย่างต่อไปนี้จะเขียนข้อมูลแถวใหม่ใต้ตารางสุดท้ายใน "ชีต 1" ของสเปรดชีต

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

นอกจากนี้ ชีต API v4 ยังให้คุณเพิ่มเซลล์ที่มีพร็อพเพอร์ตี้และการจัดรูปแบบที่เฉพาะเจาะจงได้โดยใช้คำขอ AppendCells ใน spreadsheets.batchUpdate

แก้ไขแถวด้วยข้อมูลใหม่

ทั้ง 2 API อนุญาตให้อัปเดตข้อมูลแถวด้วยค่าใหม่

v3 API

หากต้องการแก้ไขแถวข้อมูล ให้ตรวจสอบฟีดรายการเพื่อค้นหารายการของแถวที่ต้องการอัปเดต อัปเดตเนื้อหาของรายการนั้นตามต้องการ ตรวจสอบว่าค่ารหัสในรายการที่คุณใช้ตรงกับรหัสของรายการที่มีอยู่ทุกประการ

เมื่ออัปเดตรายการแล้ว ให้ส่งคำขอ PUT พร้อมข้อมูลรายการเป็นเนื้อหาคำขอไปยัง URL edit ที่ระบุไว้ในรายการแถวนั้น โดยใช้ส่วนหัวการให้สิทธิ์ที่เหมาะสม เช่น

PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version

<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
  <id>rowId</id>
  <updated>2006-11-17T18:23:45.173Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#list"/>
  <title type="text">Bingley</title>
  <content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
  <gsx:name>Bingley</gsx:name>
  <gsx:hours>20</gsx:hours>
  <gsx:items>4</gsx:items>
  <gsx:ipm>0.0033</gsx:ipm>
</entry>

v4 API

เมื่อใช้ Sheets API v4 คุณจะแก้ไขแถวได้โดยใช้การเขียน A1 ของแถวที่ต้องการแก้ไข และส่งคำขอ spreadsheets.values.update เพื่อเขียนทับแถวนั้น ช่วงที่คุณระบุจะต้องอ้างอิงถึงเซลล์แรกในแถวเท่านั้น โดย API จะอนุมานเซลล์ที่จะอัปเดตตามค่าที่ระบุมาพร้อมกับคำขอ หากคุณระบุช่วงหลายเซลล์แทน ค่าที่คุณระบุต้องอยู่ภายในช่วงดังกล่าว มิเช่นนั้น API จะแสดงข้อผิดพลาด

ตัวอย่างคำขอและเนื้อหาคำขอต่อไปนี้จะเพิ่มข้อมูลลงในแถวที่ 4 ของ "ชีต 1"

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

นอกจากนี้ คุณยังอัปเดตข้อมูลแถวจากเมธอด spreadsheet.values.batchUpdate ได้ด้วย ซึ่งการใช้เมธอดนี้จะมีประสิทธิภาพมากกว่าหากคุณต้องการอัปเดตแถวหรือเซลล์หลายรายการ

นอกจากนี้ ชีต API v4 ยังให้คุณแก้ไขพร็อพเพอร์ตี้ของเซลล์และการจัดรูปแบบของเซลล์ได้โดยใช้คำขอ UpdateCells หรือ RepeatCell ใน spreadsheets.batchUpdate

ลบแถว

ทั้ง 2 API รองรับการลบแถว ระบบจะนำแถวที่ลบออกจากสเปรดชีต และเลื่อนแถวที่อยู่ด้านล่างขึ้น 1 แถว

v3 API

หากต้องการลบแถว ให้ดึงข้อมูลแถวที่จะลบจากฟีดรายการก่อน จากนั้นส่งคําขอ DELETE ไปยัง URL edit ที่ระบุไว้ในรายการของแถว ซึ่งเป็น URL เดียวกับที่ใช้อัปเดตแถว

DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version

หากไม่ต้องการให้ลบแถวที่มีการเปลี่ยนแปลงโดยไคลเอ็นต์รายอื่นนับตั้งแต่ที่คุณดึงข้อมูล ให้ใส่ส่วนหัว HTTP If-Match ซึ่งมีค่า ETag ของแถวเดิม คุณระบุค่า ETag ของแถวเดิมได้โดยตรวจสอบแอตทริบิวต์ gd:etag ขององค์ประกอบรายการ

หากต้องการลบแถว ไม่ว่าผู้ใช้รายอื่นจะอัปเดตแถวนั้นนับตั้งแต่ที่คุณดึงข้อมูลหรือไม่ก็ตาม ให้ใช้ If-Match: * และไม่ใส่ ETag (ในกรณีนี้ คุณไม่จําเป็นต้องดึงข้อมูลแถวก่อนที่จะลบ)

v4 API

การลบแถวด้วย Sheets API v4 จะจัดการโดยการเรียกใช้เมธอด spreadsheet.batchUpdate ใช้คําขอ DeleteDimension คำขอนี้ยังใช้เพื่อนำคอลัมน์ออกได้ด้วย และนักพัฒนาแอปสามารถเลือกนำเฉพาะบางส่วนของแถวหรือคอลัมน์ออกได้ ตัวอย่างเช่น คำสั่งต่อไปนี้จะนำแถวที่ 6 ของชีตที่มีรหัสที่ระบุออก (ดัชนีแถวจะเริ่มต้นที่ 0 โดยที่ startIndex จะรวม endIndex จะไม่รวม)

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": sheetId,
          "dimension": "ROWS",
          "startIndex": 5,
          "endIndex": 6
        }
      }
    }
  ],
}

คุณสามารถเรียกข้อมูล sheetId ของชีตได้โดยใช้เมธอด spreadsheet.get

ดึงข้อมูลเครือข่ายมือถือ

ชีต API v3 มีฟีดเซลล์สําหรับการเข้าถึงพื้นฐานของข้อมูลทั้งหมดที่จัดเก็บในสเปรดชีต สําหรับสิทธิ์การอ่าน ฟีดเซลล์สามารถแสดงเนื้อหาทั้งชีตหรือช่วงของเซลล์ในชีตที่กําหนดโดยชุดพารามิเตอร์การค้นหาได้ แต่จะแสดงเป็นบล็อกเดียวเท่านั้น และต้องดึงข้อมูลช่วงที่ไม่ต่อเนื่องแยกกันโดยใช้คําขอ GET เพิ่มเติม

ชีต API v4 สามารถดึงข้อมูลเซลล์ชุดใดก็ได้จากชีต (รวมถึงช่วงที่ไม่ต่อเนื่องหลายช่วง) ชีต API เวอร์ชัน 3 จะแสดงผลเนื้อหาเซลล์เป็นค่าอินพุต (ตามที่ผู้ใช้ป้อนจากแป้นพิมพ์) และ/หรือเอาต์พุตของสูตร (หากเป็นตัวเลข) เท่านั้น ส่วนชีต API เวอร์ชัน 4 จะมอบสิทธิ์เข้าถึงค่า สูตร การจัดรูปแบบ ไฮเปอร์ลิงก์ การตรวจสอบข้อมูล และพร็อพเพอร์ตี้อื่นๆ อย่างเต็มรูปแบบ

v3 API

หากต้องการระบุ URL ของฟีดตามเซลล์สําหรับเวิร์กชีตหนึ่งๆ ให้ตรวจสอบฟีดเวิร์กชีตและค้นหา URL ของฟีดเซลล์ในรายการเวิร์กชีตที่ต้องการ

หากต้องการเรียกข้อมูลฟีดตามเซลล์ ให้ส่งคําขอ GET ไปยัง URL ของฟีดเซลล์โดยใช้ส่วนหัวการให้สิทธิ์ที่เหมาะสม เช่น

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full

ระบบจะอ้างอิงเซลล์โดยใช้หมายเลขแถวและคอลัมน์ การดึงข้อมูลช่วงเดียวที่เฉพาะเจาะจงทำได้โดยใช้พารามิเตอร์การค้นหา max-row, min-row, max-col และ min-col ตัวอย่างเช่น คำสั่งต่อไปนี้จะดึงข้อมูลเซลล์ทั้งหมดในคอลัมน์ 4 (D) โดยเริ่มจากแถวที่ 2

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
             ?min-row=2&min-col=4&max-col=4

Sheets API v3 จะแสดงผล inputValue ของเซลล์ที่ดึงข้อมูล ซึ่งก็คือค่าที่ผู้ใช้จะพิมพ์ลงในอินเทอร์เฟซผู้ใช้ของ Google ชีตเพื่อดําเนินการกับเซลล์ โดย inputValue อาจเป็นค่าลิเทอรัลหรือสูตรก็ได้ นอกจากนี้ API ยังแสดงผล numericValue ในบางครั้งด้วย เช่น เมื่อสูตรแสดงผลเป็นตัวเลข เช่น การตอบกลับอาจมีรายการเซลล์ที่มีโครงสร้างคล้ายกับตัวอย่างต่อไปนี้

<entry gd:etag='"ImB5CBYSRCp7"'>
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
  <updated>2006-11-17T18:27:32.543Z</updated>
  <category scheme="http://schemas.google.com/spreadsheets/2006"
    term="http://schemas.google.com/spreadsheets/2006#cell"/>
  <title type="text">D4</title>
  <content type="text">5</content>
  <link rel="self" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
  <gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
    numericValue="5.0">5</gs:cell>
</entry>

v4 API

เรียกข้อมูลเซลล์โดยเรียกใช้เมธอด spreadsheets.values.get หรือ spreadsheets.values.batchGet สำหรับช่วงหรือช่วงที่ต้องการตามลำดับ ตัวอย่างเช่น สูตรต่อไปนี้จะแสดงผลเซลล์ในคอลัมน์ D ของ "ชีต 2" โดยเริ่มจากแถวที่ 2 ตามลําดับคอลัมน์หลักและแสดงสูตรตามที่ป้อน (ไม่แสดงเซลล์ว่างต่อท้าย)

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA

การตอบกลับคําขอนี้มีโครงสร้างคล้ายกับ

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
      {"range": "Sheet2!D2:D",
       "majorDimension": "COLUMNS",
       "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
      }]
}

คุณควรใช้ spreadsheet.values.batchGet หากต้องการดึงข้อมูลเซลล์หลายช่วง เนื่องจากจะมีประสิทธิภาพมากกว่า หากต้องการเข้าถึงพร็อพเพอร์ตี้ของเซลล์ เช่น การจัดรูปแบบ คุณต้องใช้เมธอด spreadsheet.get

แก้ไขเซลล์

ชีต API v3 ช่วยให้คุณแก้ไขเนื้อหาของเซลล์ได้โดยออกคำสั่ง PUT ไปยังฟีดเซลล์ที่มีรายการเซลล์ที่แก้ไขแล้วเป็นส่วนเนื้อหาของคำขอ

ในทางตรงกันข้าม Sheets API v4 มีเมธอด spreadsheets.values.update และ spreadsheets.values.batchUpdate สำหรับการเปลี่ยนแปลงเนื้อหาเซลล์

v3 API

หากต้องการแก้ไขเนื้อหาของเซลล์เดียว ก่อนอื่นให้ค้นหารายการของเซลล์ในฟีดเซลล์ รายการมี URL การแก้ไข อัปเดตรายการให้ตรงกับเนื้อหาที่ต้องการให้เซลล์มี แล้วส่งPUTคําขอไปยัง URL การแก้ไข โดยให้รายการเซลล์ที่อัปเดตแล้วเป็นเนื้อหาของคําขอ ตัวอย่างเช่น สูตรต่อไปนี้จะอัปเดตเซลล์ D2 (R2C4) ให้มีค่าสูตร SUM

PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
  <link rel="edit" type="application/atom+xml"
    href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/>
  <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/>
</entry>

v4 API

การแก้ไขเซลล์เดียวใน Sheets API v4 ทำได้โดยใช้เมธอด spreadsheets.values.update วิธีนี้ต้องใช้พารามิเตอร์การค้นหา ValueInputOption ซึ่งจะระบุว่าจะถือว่าข้อมูลที่ป้อนเป็นข้อมูลใน UI ชีต (USER_ENTERED) หรือจะไม่มีการแยกวิเคราะห์และนำข้อมูลไปใช้ตามที่เป็นอยู่ (RAW) ตัวอย่างเช่น คำสั่งต่อไปนี้จะอัปเดตเซลล์ D2 ด้วยสูตร

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED

{"values": [["=SUM(A1:B6)"]]}

หากจะแก้ไขหลายเซลล์ ให้ใช้เมธอด spreadsheets.values.batchUpdate เพื่อแก้ไขในคําขอเดียว

แก้ไขหลายเซลล์ผ่านคําขอแบบกลุ่ม

ทั้ง 2 API มีวิธีเปลี่ยนแปลงเนื้อหาของหลายเซลล์ด้วยคําขอ (กลุ่ม) เดียว เซลล์ที่คำขอกลุ่มอ้างถึงไม่จำเป็นต้องอยู่ในช่วงต่อเนื่อง

ในกรณีที่การแก้ไขเซลล์อย่างน้อย 1 รายการในชุดดำเนินการไม่สำเร็จ Sheets API v3 จะอนุญาตให้การแก้ไขอื่นๆ ดำเนินการสำเร็จ อย่างไรก็ตาม Sheets API v4 จะแสดงข้อผิดพลาดหากการอัปเดตแบบเป็นกลุ่มไม่สำเร็จ และจะไม่ใช้การอัปเดตใดๆ ในกรณีดังกล่าว

v3 API

หากต้องการแก้ไขหลายเซลล์ ให้ดึงข้อมูลฟีดเซลล์สำหรับเวิร์กชีตก่อน รายการมี URL กลุ่ม ส่งPOSTคำขอไปยัง URL นี้ พร้อมกับเนื้อหาคำขอที่อธิบายเซลล์ที่ต้องการอัปเดตและเนื้อหาเซลล์ใหม่ คำขอ POST และเนื้อหาคำขอมีโครงสร้างคล้ายกับตัวอย่างต่อไปนี้

POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch

<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:batch="http://schemas.google.com/gdata/batch"
      xmlns:gs="http://schemas.google.com/spreadsheets/2006">
  <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
  <entry>
    <batch:id>request1</batch:id>
    <batch:operation type="update"/>
    <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
    <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
    <gs:cell row="2" col="4" inputValue="newData"/>
  </entry>
  ...
  <entry>
    <batch:id>request2</batch:id>
    <batch:operation type="update"/>
    <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
    <link rel="edit" type="application/atom+xml"
      href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
    <gs:cell row="5" col="2" inputValue="moreInfo"/>
  </entry>
</feed>

ช่อง batch:id ควรระบุคำขอภายในกลุ่มโดยไม่ซ้ำกัน ช่อง batch:operation ควรเป็น update สำหรับการแก้ไขเซลล์ gs:cell ระบุเซลล์ตามหมายเลขแถวและคอลัมน์ และระบุข้อมูลใหม่ที่จะแทรก id มี URL แบบเต็มของเซลล์ที่จะอัปเดต link ต้องมีแอตทริบิวต์ href ที่มีเส้นทางแบบเต็มไปยังรหัสของเซลล์ ต้องกรอกข้อมูลให้ครบทุกช่องสำหรับแต่ละรายการ

v4 API

Sheets API v4 ให้การแก้ไขค่าเซลล์แบบเป็นกลุ่มผ่านเมธอด spreadsheets.values.batchUpdate

คุณแก้ไขหลายเซลล์ได้โดยส่งPOSTคําขอที่มีการเปลี่ยนแปลงข้อมูลซึ่งระบุไว้ในเนื้อหาคําขอ เช่น

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate

{
  "valueInputOption": "USER_ENTERED"
  "data": [
       {"range": "D4",
        "majorDimension": "ROWS",
        "values": [["newData"]]
       },
       {"range": "B5",
        "majorDimension": "ROWS",
        "values": [["moreInfo"]]
       }
  ]
}

หากคุณระบุเซลล์เดียวเป็นช่วง ระบบจะเขียนค่าทั้งหมดที่ระบุลงในชีตโดยเริ่มจากเซลล์นั้นๆ เป็นพิกัดซ้ายบน หากคุณระบุช่วงหลายเซลล์แทน ค่าที่คุณระบุต้องตรงกับช่วงนั้นทุกประการ มิเช่นนั้น API จะแสดงข้อผิดพลาด