หน้านี้ได้รับการแปลโดย 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 v3 จะอ้างอิงชีตในสเปรดชีตหนึ่งๆ ว่า "เวิร์กชีต" ความหมายเดียวกับคำว่า "ชีต" ที่ API v4 ใช้

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

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

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

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

API เวอร์ชัน 3

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

https://spreadsheets.google.com/feeds

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

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

ใช้รูปแบบขอบเขตได้ทั้ง 2 แบบ

API เวอร์ชัน 4

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 เวอร์ชัน 3

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

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

API เวอร์ชัน 4

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

การฉายภาพ

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

API เวอร์ชัน 3

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

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

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

API เวอร์ชัน 4

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

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

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

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

API เวอร์ชัน 3

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

API เวอร์ชัน 4

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

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

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

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

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

API เวอร์ชัน 3

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

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

API เวอร์ชัน 4

ชีต 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 ของ Drive API เพื่อแสดงสเปรดชีตทั้งหมดของผู้ใช้ ต้องมีขอบเขตที่จำกัด

เรียกข้อมูลข้อมูลเมตาของชีต

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

ชีต API v4 spreadsheets.get ให้การเข้าถึงข้อมูลนี้ และอื่นๆ อีกมากมาย

API เวอร์ชัน 3

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

ไฟล์ 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
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

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

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

API เวอร์ชัน 3

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>

API เวอร์ชัน 4

คุณสามารถเพิ่มชีตใหม่ได้โดยทำ 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 เวอร์ชัน 3

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

หากต้องการอัปเดตขนาด ชื่อ และคุณสมบัติอื่นๆ ของชีต ให้สร้าง 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 เวอร์ชัน 3

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

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

API เวอร์ชัน 4

หากต้องการลบชีต ให้สร้าง 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 ยังเข้าถึงชุดเซลล์ที่ไม่ต่อเนื่องได้ด้วย

API เวอร์ชัน 3

หากต้องการระบุ 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 ยังอนุญาตให้กรองแถวเฉพาะผ่าน ข้อความค้นหา (อ้างอิงตามส่วนหัวคอลัมน์):

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

API เวอร์ชัน 4

เมื่อใช้ 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"]]
}

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

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

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

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

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

API เวอร์ชัน 3

หากต้องการระบุ 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 เวอร์ชัน 4

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

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

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

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

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

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

API เวอร์ชัน 3

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

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

เมื่อใช้ 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 ทั้ง 2 รายการรองรับการลบแถว แถวที่ถูกลบจะถูกนำออกจาก และแถวด้านล่างสเปรดชีตจะเลื่อนขึ้น 1 แถว

API เวอร์ชัน 3

หากต้องการลบแถว ให้ดึงข้อมูลแถวที่ต้องการลบจาก ฟีดข้อมูล แล้วส่งคำขอ 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 เวอร์ชัน 4

การลบแถวด้วย Sheets API v4 จะจัดการโดย spreadsheet.batchUpdate โดยใช้ DeleteDimension อีกครั้ง คำขอนี้ยังใช้เพื่อนำคอลัมน์ออก และนักพัฒนาซอฟต์แวร์ และเลือกนำเฉพาะบางส่วนของแถวหรือคอลัมน์ออก ตัวอย่างเช่น พารามิเตอร์ ต่อไปนี้จะนําแถวที่ 6 ของชีตที่มีรหัสที่ระบุ (ดัชนีแถว) มีค่าเป็นศูนย์ (นับรวม 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 เวอร์ชัน 3

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

API เวอร์ชัน 4

เรียกดูข้อมูลเซลล์โดยการเรียก 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 เวอร์ชัน 3

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

การแก้ไขเซลล์เดี่ยวใน 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 เวอร์ชัน 3

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

API เวอร์ชัน 4

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