مهاجرت از Sheets API نسخه 3

رابط برنامه‌نویسی کاربردی نسخه ۳

Sheets API نسخه ۳ با یک محدوده مجوز واحد عمل می‌کند:

https://spreadsheets.google.com/feeds

که نام مستعاری برای

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

هر دو قالب دامنه می‌توانند مورد استفاده قرار گیرند.

رابط برنامه‌نویسی کاربردی نسخه ۴

Sheets API نسخه ۴ از یک یا چند مورد از مجموعه دامنه‌های زیر استفاده می‌کند:

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 نسخه ۳ صفحات گسترده (Sheets API) قابلیت مشاهده را مستقیماً در نقاط پایانی خود بیان می‌کند. یک صفحه گسترده public "در وب منتشر شده است" و بنابراین API می‌تواند بدون مجوز به آن دسترسی داشته باشد، در حالی که یک صفحه گسترده private نیاز به احراز هویت دارد. قابلیت مشاهده در نقطه پایانی پس از شناسه صفحه گسترده مشخص می‌شود:

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

رابط برنامه‌نویسی کاربردی نسخه ۴

در API جدید Sheets نسخه ۴، هیچ اعلان صریحی از قابلیت مشاهده وجود ندارد. فراخوانی‌های API با استفاده از شناسه‌های صفحه‌گسترده انجام می‌شوند. اگر برنامه اجازه دسترسی به صفحه‌گسترده مشخص شده را نداشته باشد، خطایی برگردانده می‌شود. در غیر این صورت، فراخوانی ادامه می‌یابد.

رابط برنامه‌نویسی کاربردی نسخه ۳

فقط دو تنظیم تصویرسازی ممکن در Sheets API نسخه ۳ وجود دارد. تصویرسازی full تمام اطلاعات موجود را برمی‌گرداند، در حالی که تصویرسازی basic زیرمجموعه‌ای کوچک‌تر و ثابت از داده‌ها (برای صفحات کار، لیست و فیدهای سلول‌ها) را برمی‌گرداند. مانند قابلیت مشاهده، تصویرسازی باید در نقطه پایانی API (بعد از تنظیم قابلیت مشاهده) مشخص شود:

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

زیرمجموعه کوچک‌تر داده‌های ارائه شده توسط تصویر basic برای کارآمدتر کردن کد ارزشمند است، اما قابل سفارشی‌سازی نیست.

رابط برنامه‌نویسی کاربردی نسخه ۴

اگرچه Sheets API نسخه ۴ می‌تواند یک مجموعه داده کامل را برگرداند، اما زیرمجموعه‌های ثابتی مشابه تنظیمات basic قابلیت مشاهده در Sheets API نسخه ۳ تعریف نمی‌کند. متدهای موجود در مجموعه صفحه گسترده، میزان داده‌هایی را که از طریق استفاده از پارامتر جستجوی فیلدها برمی‌گردانند، محدود می‌کنند.

برای مثال، کوئری زیر فقط عناوین تمام برگه‌های یک صفحه گسترده خاص را برمی‌گرداند:

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

رابط برنامه‌نویسی کاربردی نسخه ۳

Sheets API نسخه ۳ ابزاری برای ایجاد صفحات گسترده جدید ارائه نمی‌دهد؛ در عوض، می‌توان از متد Files.create در Drive API برای ایجاد فایل‌های صفحه گسترده جدید استفاده کرد. این امر مستلزم آن است که برنامه، محدوده https://www.googleapis.com/auth/drive را اعلام کند.

رابط برنامه‌نویسی کاربردی نسخه ۴

متد Files.create از API درایو می‌تواند با Sheets API نسخه ۴ نیز استفاده شود، اما مستلزم آن است که برنامه، محدوده https://www.googleapis.com/auth/drive ارائه دهد.

به عنوان یک جایگزین معادل، Sheets API نسخه ۴ متد spreadsheets.create را ارائه می‌دهد که می‌تواند به صورت اختیاری صفحات را اضافه کند، ویژگی‌های صفحه گسترده و صفحه را تنظیم کند و محدوده‌های نامگذاری شده را اضافه کند. برای مثال، کد زیر یک صفحه گسترده جدید ایجاد می‌کند و نام آن را "NewTitle" می‌گذارد:

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

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

رابط برنامه‌نویسی کاربردی نسخه ۳

فید Sheets API نسخه ۳ به یک برنامه اجازه می‌دهد تا لیستی از تمام صفحات گسترده قابل دسترسی توسط کاربر احراز هویت شده را بازیابی کند. نقطه پایانی فید صفحه گسترده عبارت است از:

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

رابط برنامه‌نویسی کاربردی نسخه ۴

Sheets API نسخه ۴ این عملیات خاص را ارائه نمی‌دهد. توصیه می‌کنیم برنامه خود را به گونه‌ای تغییر دهید که از دامنه drive.file در ترکیب با Google Picker برای انتخاب صفحه گسترده استفاده کند.

در مواردی که فهرست کردن صفحات گسترده مورد نیاز است، می‌توان آن را از طریق متد Files.list از API درایو ، با استفاده از یک کوئری mimeType ، تکثیر کرد:

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

استفاده از متد files.list از 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>

رابط برنامه‌نویسی کاربردی نسخه ۴

متد spreadsheets.get می‌تواند برای دریافت ویژگی‌های صفحه و سایر فراداده‌ها استفاده شود - بسیار بیشتر از آنچه که با استفاده از Sheets API نسخه ۳ در دسترس است. اگر فقط می‌خواهید ویژگی‌های صفحه را بخوانید، پارامتر query 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
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

رابط برنامه‌نویسی کاربردی نسخه ۳

Sheets API نسخه ۳ می‌تواند با ارسال درخواست 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>

رابط برنامه‌نویسی کاربردی نسخه ۴

شما می‌توانید با ایجاد یک درخواست AddSheet در متد spreadsheets.batchUpdate ، برگه‌های جدید اضافه کنید. به عنوان بخشی از بدنه درخواست، می‌توانید ویژگی‌های برگه را برای برگه جدید مشخص کنید؛ همه ویژگی‌ها اختیاری هستند. ارائه عنوانی که برای یک برگه موجود استفاده می‌شود، خطا محسوب می‌شود.

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

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

رابط برنامه‌نویسی کاربردی نسخه ۳

برای تغییر عنوان یا اندازه یک برگه کار، با بازیابی فید برگه کار و یافتن ورودی برگه کار مورد نظر که حاوی یک 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>

رابط برنامه‌نویسی کاربردی نسخه ۴

برای به‌روزرسانی اندازه، عنوان و سایر ویژگی‌های برگه، یک درخواست 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 صفحه گسترده استفاده کنید.

رابط برنامه‌نویسی کاربردی نسخه ۳

برای حذف یک کاربرگ، با بازیابی فید کاربرگ شروع کنید، سپس یک درخواست DELETE به آدرس اینترنتی edit ورودی کاربرگ هدف ارسال کنید.

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

رابط برنامه‌نویسی کاربردی نسخه ۴

برای حذف یک برگه، یک درخواست DeleteSheet در متد spreadsheets.batchUpdate ایجاد کنید. بدنه درخواست POST فقط باید شامل sheetId برای برگه‌ای باشد که قرار است حذف شود. برای مثال:

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

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

برای بازیابی sheetId یک شیت، از متد spreadsheets.get صفحه گسترده استفاده کنید.

رابط برنامه‌نویسی کاربردی نسخه ۳

برای تعیین 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 نسخه ۳ پارامترهای پرس‌وجو را برای تغییر این ترتیب ارائه می‌دهد.

ترتیب معکوس:

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 نسخه ۳ همچنین امکان فیلتر کردن ردیف‌های خاص را از طریق یک پرس‌وجوی ساختاریافته (که توسط سرستون‌ها ارجاع داده می‌شوند) فراهم می‌کند:

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

رابط برنامه‌نویسی کاربردی نسخه ۴

با استفاده از Sheets API نسخه ۴، ردیف‌ها را می‌توان با استفاده از متدهای 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 نسخه ۴ معادلی برای پارامترهای پرس‌وجوی ردیفی ارائه شده توسط Sheets API نسخه ۳ ندارد. ترتیب معکوس ساده است؛ به سادگی آرایه values برگشتی را به ترتیب معکوس پردازش کنید. ترتیب بر اساس ستون برای خواندن پشتیبانی نمی‌شود، اما می‌توان داده‌ها را در برگه (با استفاده از درخواست SortRange ) مرتب کرد و سپس آن را خواند.

Sheets API نسخه ۴ در حال حاضر معادل مستقیمی برای کوئری‌های ساختاریافته Sheets API نسخه ۳ ندارد. با این حال، می‌توانید داده‌های مربوطه را بازیابی کرده و در صورت نیاز در برنامه خود مرتب‌سازی کنید.

رابط برنامه‌نویسی کاربردی نسخه ۳

برای تعیین URL یک فید مبتنی بر لیست برای یک برگه کاری مشخص، فید برگه کاری را بازیابی کنید و URL پست را در ورودی برگه کاری مورد نظر پیدا کنید.

برای افزودن یک ردیف داده، یک درخواست POST به آدرس پست (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>

ردیف‌های جدید به انتهای برگه مشخص شده اضافه می‌شوند.

رابط برنامه‌نویسی کاربردی نسخه ۴

با استفاده از Sheets API نسخه ۴، می‌توانید ردیف‌ها را با استفاده از متد spreadsheets.values.append اضافه کنید. مثال زیر یک ردیف جدید از داده‌ها را زیر آخرین جدول در "Sheet1" یک صفحه گسترده می‌نویسد.

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

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

علاوه بر این، Sheets API نسخه ۴ به شما امکان می‌دهد سلول‌هایی با ویژگی‌ها و قالب‌بندی خاص را با استفاده از درخواست‌های AppendCells در spreadsheets.batchUpdate اضافه کنید.

رابط برنامه‌نویسی کاربردی نسخه ۳

برای ویرایش یک ردیف از داده‌ها، فید لیست را بررسی کنید تا ورودی ردیفی را که می‌خواهید به‌روزرسانی کنید، پیدا کنید. در صورت نیاز، محتوای آن ورودی را به‌روزرسانی کنید. مطمئن شوید که مقدار شناسه (ID) در ورودی مورد استفاده دقیقاً با شناسه ورودی موجود مطابقت دارد.

پس از به‌روزرسانی ورودی، یک درخواست PUT با ورودی به عنوان بدنه درخواست، با استفاده از یک هدر مجوز مناسب، به آدرس اینترنتی 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>

رابط برنامه‌نویسی کاربردی نسخه ۴

با Sheets API نسخه ۴، می‌توانید یک ردیف را با استفاده از نمادگذاری A1 ردیفی که می‌خواهید ویرایش کنید ویرایش کنید و یک درخواست spreadsheets.values.update برای بازنویسی آن ردیف صادر کنید. محدوده مشخص شده فقط باید به اولین سلول در ردیف اشاره کند؛ API بر اساس مقادیر ارائه شده با درخواست، سلول‌ها را برای به‌روزرسانی استنباط می‌کند. اگر به جای آن یک محدوده چند سلولی مشخص کنید، مقادیری که ارائه می‌دهید باید در آن محدوده قرار بگیرند. در غیر این صورت، API خطا برمی‌گرداند.

مثال زیر درخواست و بدنه درخواست، داده‌ها را به ردیف چهارم "Sheet1" اضافه می‌کند:

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

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

همچنین می‌توانید داده‌های ردیف را از متد spreadsheet.values.batchUpdate به‌روزرسانی کنید؛ اگر به‌روزرسانی‌های متعددی در چندین ردیف یا سلول انجام می‌دهید، استفاده از این متد کارآمدتر است.

علاوه بر این، Sheets API نسخه ۴ به شما امکان می‌دهد تا با استفاده از درخواست‌های UpdateCells یا RepeatCell در فایل spreadsheets.batchUpdate ، ویژگی‌های سلول و قالب‌بندی سلول‌ها را ویرایش کنید.

رابط برنامه‌نویسی کاربردی نسخه ۳

برای حذف یک ردیف، ابتدا ردیف مورد نظر برای حذف را از فید لیست بازیابی کنید، سپس یک درخواست DELETE به آدرس اینترنتی edit ارائه شده در ورودی ردیف ارسال کنید. این همان آدرس اینترنتی است که برای به‌روزرسانی ردیف استفاده می‌شود.

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

اگر می‌خواهید مطمئن شوید که سطری را که از زمان بازیابی توسط کلاینت دیگری تغییر یافته است، حذف نمی‌کنید، یک هدر HTTP If-Match که حاوی مقدار ETag سطر اصلی است را اضافه کنید. می‌توانید مقدار ETag سطر اصلی را با بررسی ویژگی gd:etag عنصر ورودی تعیین کنید.

اگر می‌خواهید ردیف را صرف نظر از اینکه شخص دیگری از زمان بازیابی آن، آن را به‌روزرسانی کرده است یا خیر، حذف کنید، از If-Match: * استفاده کنید و ETag را وارد نکنید. (در این حالت، نیازی به بازیابی ردیف قبل از حذف آن ندارید.)

رابط برنامه‌نویسی کاربردی نسخه ۴

حذف ردیف‌ها با استفاده از Sheets API نسخه ۴ توسط فراخوانی متد spreadsheet.batchUpdate و با استفاده از درخواست DeleteDimension انجام می‌شود. این درخواست همچنین می‌تواند برای حذف ستون‌ها استفاده شود و توسعه‌دهندگان می‌توانند انتخاب کنند که فقط بخشی از یک ردیف یا ستون حذف شود. برای مثال، کد زیر ردیف ششم یک برگه با شناسه داده شده را حذف می‌کند (شاخص‌های ردیف مبتنی بر صفر هستند، با startIndex شامل و endIndex منحصر به فرد):

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

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

sheetId برگه (sheetId) یک برگه را می‌توان با استفاده از متد spreadsheet.get بازیابی کرد.

رابط برنامه‌نویسی کاربردی نسخه ۳

برای تعیین URL یک فید مبتنی بر سلول برای یک برگه داده شده، فید برگه را بررسی کنید و URL فید سلول را در ورودی برگه مورد نظر پیدا کنید.

برای بازیابی یک فید مبتنی بر سلول، یک درخواست GET به آدرس اینترنتی فید سلول ارسال کنید و از یک هدر مجوز مناسب استفاده کنید. برای مثال:

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

سلول‌ها با استفاده از شماره ردیف و ستون ارجاع داده می‌شوند. واکشی یک محدوده خاص می‌تواند با استفاده از پارامترهای پرس‌وجوی max-row ، min-row ، max-col و min-col انجام شود. برای مثال، دستور زیر تمام سلول‌های ستون ۴ (D) را با شروع از ردیف ۲ بازیابی می‌کند:

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

API نسخه ۳ صفحات، inputValue سلول‌های بازیابی شده را برمی‌گرداند - مقداری که کاربر در غیر این صورت برای دستکاری سلول در رابط کاربری Google Sheets تایپ می‌کرد. 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>

رابط برنامه‌نویسی کاربردی نسخه ۴

داده‌های سلول را با فراخوانی متد 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 مورد نیاز است.

رابط برنامه‌نویسی کاربردی نسخه ۳

برای ویرایش محتوای یک سلول، ابتدا ورودی سلول را در cell feed پیدا کنید. ورودی شامل یک edit URL است. ورودی را به‌روزرسانی کنید تا محتوایی را که می‌خواهید سلول داشته باشد، منعکس کند و سپس یک درخواست PUT به edit 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>

رابط برنامه‌نویسی کاربردی نسخه ۴

ویرایش تک سلول در Sheets API نسخه ۴ را می‌توان با متد spreadsheets.values.update انجام داد. این متد به یک پارامتر کوئری ValueInputOption نیاز دارد که مشخص می‌کند آیا داده‌های ورودی طوری رفتار شوند که انگار وارد رابط کاربری Sheets شده‌اند ( USER_ENTERED ) یا بدون تجزیه و تحلیل رها شوند و همانطور که هستند ( RAW ) در نظر گرفته شوند. به عنوان مثال، سلول D2 زیر با یک فرمول به‌روزرسانی می‌شود:

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

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

اگر چندین سلول را ویرایش می‌کنید، از متد spreadsheets.values.batchUpdate برای ارسال آنها در یک درخواست استفاده کنید.

رابط برنامه‌نویسی کاربردی نسخه ۳

برای ویرایش چندین سلول، ابتدا یک فید سلولی برای برگه کار بازیابی کنید. ورودی شامل یک 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 را مشخص کند. فیلد batch:operation باید برای ویرایش سلول‌ها update باشد. gs:cell سلول را بر اساس شماره ردیف و ستون شناسایی می‌کند و داده‌های جدید را برای درج در آنجا ارائه می‌دهد. id شامل URL کامل سلولی است که باید به‌روزرسانی شود. link باید دارای یک ویژگی href باشد که شامل مسیر کامل شناسه سلول است. همه این فیلدها برای هر ورودی الزامی هستند.

رابط برنامه‌نویسی کاربردی نسخه ۴

Sheets API نسخه ۴ امکان ویرایش دسته‌ای مقادیر سلول‌ها را از طریق متد 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 خطا برمی‌گرداند.