หน้านี้ได้รับการแปลโดย 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

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

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

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

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

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

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

API V3

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

https://spreadsheets.google.com/feeds

ซึ่งเป็นชื่อแทนสำหรับ

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

ใช้รูปแบบขอบเขตใดก็ได้

API v4

Sheets 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 เวอร์ชันเก่า คำว่าระดับการเข้าถึงจะใช้เพื่อหมายถึงความพร้อมใช้งานของสเปรดชีตที่ระบุ

API V3

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

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

API v4

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

การฉายภาพ

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

API V3

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

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

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

API v4

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

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

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

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

API V3

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

API v4

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

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

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

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

แสดงรายการสเปรดชีตสำหรับผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว

API V3

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

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

API v4

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

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

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

การใช้เมธอด files.list ของไดรฟ์เพื่อแสดงสเปรดชีตทั้งหมดของผู้ใช้จะต้องใช้ขอบเขตที่จำกัด

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

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

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

API V3

ฟีดเวิร์กชีตเข้าถึงได้จากปลายทาง 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>

API v4

สามารถใช้เมธอด 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 ช่วยให้คุณเพิ่มชีตใหม่ในสเปรดชีตที่มีอยู่แล้วได้

API V3

ชีต 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>

API v4

คุณเพิ่มชีตใหม่ได้โดยสร้างคำขอ 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 รองรับการอัปเดตนี้ และยังใช้เพื่ออัปเดตพร็อพเพอร์ตี้ของชีตอื่นๆ ได้อีกด้วย โปรดทราบว่าการลดขนาดชีตอาจทำให้ข้อมูลในเซลล์ที่ครอบตัดถูกลบโดยไม่มีการเตือน

API V3

หากต้องการเปลี่ยนชื่อหรือขนาดของเวิร์กชีต ให้เริ่มด้วยการเรียกข้อมูลฟีดเวิร์กชีตและค้นหารายการเวิร์กชีตที่ต้องการ ซึ่งมี 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>

API v4

หากต้องการอัปเดตขนาด ชื่อ และพร็อพเพอร์ตี้อื่นๆ ของชีต ให้ส่งคำขอ 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 จะนำชีตออกจากสเปรดชีตที่ระบุได้

API V3

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

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

API v4

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

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

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

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

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

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

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

API V3

หากต้องการระบุ 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

ชีต API v3 ยังอนุญาตให้กรองแถวที่ต้องการผ่านการค้นหาที่มีโครงสร้าง (อ้างอิงโดยส่วนหัวคอลัมน์) ด้วย

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

API v4

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

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"]]
}

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

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

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

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

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

API V3

หากต้องการระบุ 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>

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

API v4

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

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

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

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

แก้ไขแถวที่มีข้อมูลใหม่

API ทั้งสองช่วยให้อัปเดตข้อมูลแถวด้วยค่าใหม่ได้

API V3

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

เมื่ออัปเดตรายการแล้ว ให้ส่งคำขอ 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>

API v4

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

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

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

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

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

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

ลบแถว

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

API V3

หากต้องการลบแถว ให้ดึงข้อมูลแถวที่ต้องการลบออกจากฟีดข้อมูลก่อน แล้วส่งคำขอ 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 (ในกรณีนี้ คุณไม่จำเป็นต้องเรียกข้อมูลแถวก่อนที่จะลบ)

API v4

การลบแถวด้วย 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

ดึงข้อมูลเซลล์

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

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

API V3

หากต้องการระบุ 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

ชีต 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>

API v4

ดึงข้อมูลเซลล์โดยเรียกใช้เมธอด spreadsheets.values.get หรือ spreadsheets.values.batchGet สำหรับช่วงหรือช่วงที่สนใจตามลำดับ ตัวอย่างเช่น ฟังก์ชันต่อไปนี้จะแสดงผลเซลล์ในคอลัมน์ D ของ "Sheet2" ซึ่งเริ่มต้นด้วยแถว 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

แก้ไขเซลล์

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

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

API V3

หากต้องการแก้ไขเนื้อหาของเซลล์เดียว ขั้นแรกให้ค้นหารายการของเซลล์ในฟีดเซลล์ รายการนี้มี 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>

API v4

คุณแก้ไขเซลล์เดียวใน 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 เพื่อออกไว้ในคำขอเดียว

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

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

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

API V3

หากต้องการแก้ไขหลายเซลล์ ให้เรียกข้อมูลฟีดเซลล์ของเวิร์กชีตก่อน รายการนี้มี 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 ที่มีเส้นทางแบบเต็มไปยังรหัสของเซลล์ ต้องระบุข้อมูลในช่องเหล่านี้สำหรับแต่ละรายการ

API v4

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 จะแสดงข้อผิดพลาด