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

اگر برنامه‌های موجود بر اساس Google Sheets API v3 دارید، می‌توانید به Google Sheets API نسخه 4 مهاجرت کنید. نسخه v4 مبتنی بر JSON است، رابط کاربری ساده‌تری دارد و قابلیت‌های قابل توجهی را اضافه می‌کند که در نسخه v3 امکان‌پذیر نیست.

این صفحه یک نقشه بین دستورات Sheets API v3 قدیمی و عملیات معادل آنها در Sheets API v4 ارائه می دهد. نگاشت تا حد زیادی بر روی مجموعه spreadsheets.values ​​متمرکز است که عملکرد مستقیم خواندن و نوشتن سلول را فراهم می کند. سایر جنبه‌ها، مانند افزودن برگه‌ها یا به‌روزرسانی ویژگی‌های برگه توسط مجموعه صفحات گسترده مدیریت می‌شوند. توجه داشته باشید که ساختارهای JSON V4 API با ساختارهای XML استفاده شده در نسخه 3 سازگاری ندارند.

برای اطلاعات بیشتر در مورد منابع موجود در Sheets v4 API، به مرجع API مراجعه کنید.

علامت گذاری و اصطلاحات

v3 API به برگه‌های درون یک صفحه گسترده خاص به عنوان «کاربرگ» اشاره می‌کند. این مترادف با عبارت "sheets" است که API v4 استفاده می کند.

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

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

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

اگر برنامه شما نیازی به ویرایش برگه ها یا ویژگی های برگه کاربر ندارد، از دامنه های فقط خواندنی استفاده کنید. اگر برنامه به دسترسی عمومی به Drive نیاز ندارد، به جای استفاده از Drive scope از صفحات گسترده استفاده کنید.

دید

در نسخه‌های قدیمی‌تر API، از عبارت visibility برای اشاره به در دسترس بودن یک صفحه گسترده استفاده می‌شود.

v3 API

Sheets API v3 قابلیت مشاهده را مستقیماً در نقاط پایانی خود بیان می کند. یک صفحه گسترده public "منتشر شده در وب" است و بنابراین می تواند توسط API بدون مجوز قابل دسترسی باشد، در حالی که یک صفحه گسترده private نیاز به احراز هویت دارد. قابلیت مشاهده در نقطه پایانی پس از شناسه صفحه گسترده مشخص شده است:

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

v4 API

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

فرافکنی

اصطلاح projection توسط Sheets API v3 برای اشاره به مجموعه داده‌هایی که توسط یک فراخوانی API معین بازگردانده می‌شوند، استفاده می‌شود - همه آن‌ها یا یک زیرمجموعه ثابت تعریف شده در API. Sheets API v4 از طرح ریزی استفاده نمی کند. بلکه به شما اجازه می دهد تا کنترل بیشتری بر روی داده های بازگردانده شده داشته باشید.

v3 API

در Sheets API نسخه 3 فقط دو تنظیم ممکن برای نمایش وجود دارد. full projection تمام اطلاعات موجود را برمی گرداند، در حالی که 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

Sheets 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 Picker برای انتخاب صفحه‌گسترده مهاجرت کنید.

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

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

استفاده از روش Drive API files.list برای فهرست کردن همه صفحه‌گسترده‌های کاربر، به یک محدوده محدود نیاز دارد.

فراداده برگه را بازیابی کنید

Sheets API v3 یک خوراک برای دسترسی به ابرداده برگه موجود در یک صفحه گسترده ارائه می کند (داده های ردیف و سلول از طریق یک فید جداگانه قابل دسترسی هستند). فراداده شامل اطلاعاتی مانند عناوین برگه و اطلاعات اندازه است.

روش Sheets API v4 spreadsheets.get دسترسی به این اطلاعات و بسیاری موارد دیگر را فراهم می کند.

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
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

یک برگه به ​​صفحه گسترده اضافه کنید

هر دو 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 ها می توانند برگه ها را از یک صفحه گسترده حذف کنند.

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 صفحه گسترده استفاده کنید.

بازیابی داده های ردیف

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

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 بازیابی کرد. برای مثال، موارد زیر همه ردیف‌های "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 ها می توانید ردیف جدیدی از داده ها را به یک برگه اضافه کنید.

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 اضافه کنید. مثال زیر یک ردیف جدید از داده ها را در زیر آخرین جدول در "Sheet1" یک صفحه گسترده می نویسد.

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

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

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

یک ردیف با داده های جدید را ویرایش کنید

هر دو 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 یک خطا برمی گرداند.

نمونه درخواست و بدنه درخواست زیر داده ها را به ردیف چهارم "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 از حذف ردیف ها پشتیبانی می کنند. یک ردیف حذف شده از صفحه‌گسترده حذف می‌شود و ردیف‌های زیر آن یک به بالا می‌روند.

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 انجام می‌شود. این درخواست همچنین می تواند برای حذف ستون ها و توسعه دهندگان استفاده شود و فقط بخشی از یک سطر یا ستون را حذف کنند. به عنوان مثال، موارد زیر ردیف ششم یک برگه با شناسه داده شده را حذف می‌کند (شاخص‌های ردیف بر اساس صفر هستند، با 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 دسترسی کامل به مقادیر، فرمول‌ها، قالب‌بندی، پیوندها، اعتبارسنجی داده‌ها و سایر ویژگی‌ها را می‌دهد.

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 «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 را برای تغییر محتوای سلول ارائه می‌کند.

v3 API

برای ویرایش محتوای یک سلول، ابتدا ورودی سلول را در فید سلول پیدا کنید. ورودی حاوی یک URL ویرایش است. ورودی را به‌روزرسانی کنید تا محتویاتی را که می‌خواهید سلول داشته باشد منعکس کند، و سپس یک درخواست PUT به آدرس اینترنتی ویرایش با ورودی سلول به‌روزرسانی شده به عنوان متن درخواست صادر کنید. برای مثال، سلول 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 انجام داد. این روش به یک پارامتر Query 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 ابزاری را برای ایجاد تغییرات در محتوای سلول های متعدد با یک درخواست واحد (دسته ای) فراهم می کنند. سلول‌هایی که در یک درخواست دسته‌ای به آنها اشاره می‌شود، لازم نیست در یک محدوده پیوسته باشند.

در صورتی که یک یا چند ویرایش سلول در دسته با شکست مواجه شود، 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 یک خطا برمی گرداند.