الترحيل من الإصدار الثالث من واجهة برمجة تطبيقات جداول البيانات

الإصدار 3 من واجهة برمجة التطبيقات

يعمل الإصدار 3 من Sheets API باستخدام نطاق تفويض واحد:

https://spreadsheets.google.com/feeds

وهو اسم مستعار

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

يمكن استخدام تنسيق أي نطاق.

الإصدار 4 من واجهة برمجة التطبيقات

يستخدم الإصدار 4 من 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

استخدِم نطاقات للقراءة فقط إذا كان تطبيقك لا يحتاج إلى إجراء تعديلات على أوراق بيانات المستخدم أو خصائص جداول البيانات. يمكنك استخدام نطاقات جداول البيانات بدلاً من نطاقات Drive إذا كان التطبيق لا يحتاج إلى إذن عام للوصول إلى Drive.

الإصدار 3 من واجهة برمجة التطبيقات

يعبّر الإصدار الثالث من Sheets API عن إذن الوصول مباشرةً في نقاط النهاية. تم "نشر جدول بيانات public على الويب" وبالتالي يمكن الوصول إليه من خلال واجهة برمجة التطبيقات بدون إذن، في حين أن جدول بيانات private يتطلب المصادقة. يتم تحديد مستوى الرؤية في نقطة النهاية بعد رقم تعريف جدول البيانات:

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

الإصدار 4 من واجهة برمجة التطبيقات

في الإصدار 4 من Sheets API الجديد، لم يتم تقديم بيان صريح بشأن إذن الوصول. يتم إجراء طلبات البيانات من واجهة برمجة التطبيقات باستخدام معرّفات جداول البيانات. إذا لم يكن لدى التطبيق إذن للوصول إلى جدول بيانات محدد، فسيتم عرض خطأ. بخلاف ذلك، تستمر المكالمة.

الإصدار 3 من واجهة برمجة التطبيقات

لا يوجد سوى إعدادين محتملين للعرض في الإصدار 3 من Sheets API. تعرض إسقاط full جميع المعلومات المتاحة، بينما تعرض basic مجموعة فرعية أصغر وثابتة من البيانات (لخلاصات أوراق العمل والقوائم والخلايا). كما هو الحال في مستوى الرؤية، يجب تحديد الإسقاط في نقطة نهاية واجهة برمجة التطبيقات (بعد إعداد مستوى الرؤية):

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

وتفيد المجموعة الفرعية الأصغر من البيانات التي يوفرها توقع basic في جعل الرمز أكثر كفاءة، ولكن لا يمكن تخصيصها.

الإصدار 4 من واجهة برمجة التطبيقات

على الرغم من أنّ الإصدار 4 من Sheets API يمكنه عرض مجموعة بيانات كاملة، فإنّه لا يحدّد مجموعات فرعية ثابتة مماثلة لمستوى رؤية basic في الإصدار 3 من Sheets API. تقيّد الطرق المتوفرة في جمع جدول البيانات كمية البيانات التي يتم عرضها من خلال استخدام معلمة طلب بحث الحقول.

على سبيل المثال، يعرض الاستعلام التالي فقط عناوين جميع الأوراق في جدول بيانات معين:

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

الإصدار 3 من واجهة برمجة التطبيقات

لا يوفّر الإصدار 3 من Sheets API وسيلة لإنشاء جداول بيانات جديدة. بدلاً من ذلك، يمكن استخدام الطريقة Drive API Files.create لإنشاء ملفات جداول بيانات جديدة. ويتطلّب ذلك من التطبيق تقديم بيان عن نطاق https://www.googleapis.com/auth/drive.

الإصدار 4 من واجهة برمجة التطبيقات

يمكن أيضًا استخدام الإجراء Drive API Files.create مع الإصدار 4 من Sheets API، ولكنّه يتطلّب من التطبيق تقديم نطاق https://www.googleapis.com/auth/drive.

وكبديل مكافئ، يوفّر الإصدار 4 من Sheets API طريقة spreadsheets.create، والتي يمكنها أيضًا اختياريًا إضافة أوراق، وضبط خصائص جداول البيانات والأوراق، وإضافة نطاقات مُعنوَنة. على سبيل المثال، يؤدي ما يلي إلى إنشاء جدول بيانات جديد ومنحه الاسم "NewTitle":

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

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

الإصدار 3 من واجهة برمجة التطبيقات

تسمح خلاصة الإصدار 3 من Sheets API للتطبيق باسترداد قائمة بجميع جداول البيانات التي يمكن للمستخدم الذي تمت مصادقته الوصول إليها. نقطة نهاية خلاصة جدول البيانات هي:

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

الإصدار 4 من واجهة برمجة التطبيقات

لا يوفّر الإصدار 4 من Sheets API هذه العملية المحدّدة. نقترح عليك نقل تطبيقك لاستخدام نطاق drive.file مع "أداة اختيار Google" لاختيار جداول البيانات.

في الحالات التي تكون فيها جداول البيانات مطلوبة، يمكن نسخها عبر الطريقة Drive API Files.list، باستخدام طلب البحث mimeType:

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

إنّ استخدام طريقة file.list في Drive API لإدراج جميع جداول بيانات المستخدم يتطلّب نطاقًا محدودًا.

الإصدار 3 من واجهة برمجة التطبيقات

يمكن الوصول إلى خلاصة ورقة العمل من نقطة نهاية واجهة برمجة التطبيقات هذه (باستخدام عنوان تفويض مناسب):

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>

الإصدار 4 من واجهة برمجة التطبيقات

يمكن استخدام الطريقة spreadsheets.get للحصول على خصائص الورقة والبيانات الوصفية الأخرى، وذلك أكثر بكثير مما هو متاح عند استخدام الإصدار 3 من Sheets API. إذا كنت تريد قراءة سمات ورقة البيانات فقط، اضبط معلَمة طلب البحث 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
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

الإصدار 3 من واجهة برمجة التطبيقات

يمكن للإصدار الثالث من Google 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>

الإصدار 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
            }
          }
      }
  }],
}

الإصدار 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>

الإصدار 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 لجدول البيانات.

الإصدار 3 من واجهة برمجة التطبيقات

لحذف ورقة بيانات، ابدأ باسترداد خلاصة ورقة البيانات، ثم أرسِل طلب DELETE على عنوان URL edit لإدخال ورقة البيانات المستهدف.

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

الإصدار 4 من واجهة برمجة التطبيقات

لحذف ورقة، عليك إجراء طلب DeleteSheet في طريقة spreadsheets.batchUpdate. يجب أن يحتوي نص طلب POST فقط على sheetId لحذف الورقة. مثلاً:

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

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

لاسترداد sheetId لجدول بيانات فردي، استخدِم طريقة جدول البيانات spreadsheets.get.

الإصدار 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>

يتم تلقائيًا عرض الصفوف المعروضة في خلاصة القائمة بترتيب الصفوف. يوفّر الإصدار 3 من 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

يسمح الإصدار 3 من Sheets API أيضًا بتصفية صفوف معينة عبر طلب بحث منظم (يشار إليه بعناوين الأعمدة):

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

الإصدار 4 من واجهة برمجة التطبيقات

باستخدام الإصدار 4 من 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"]]
}

لا يتم تضمين الخلايا الفارغة اللاحقة في الرد عند استرداد الصفوف أو الأعمدة أو الأوراق بأكملها.

لا يحتوي الإصدار 4 من Sheets API على مكافئات لمَعلمات طلب البحث لترتيب الصفوف التي يوفّرها الإصدار 3 من Sheets API. الترتيب العكسي بسيط، ما عليك سوى معالجة صفيفة values المعروضة بترتيب عكسي. لا يتوفر الترتيب حسب العمود للقراءات، ولكن من الممكن ترتيب البيانات في ورقة البيانات (باستخدام طلب SortRange) ثم قراءته.

لا يتوفّر حاليًا الإصدار 4 من Sheets API مكافئ مباشر لطلبات البحث المنظَّمة للإصدار الثالث من Sheets 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>

يتم إلحاق الصفوف الجديدة بنهاية الورقة المحددة.

الإصدار 4 من واجهة برمجة التطبيقات

باستخدام الإصدار 4 من Sheets API، يمكنك إلحاق الصفوف باستخدام الطريقة spreadsheets.values.append. يكتب المثال التالي صفًا جديدًا من البيانات أسفل الجدول الأخير في "Sheet1" من جدول بيانات.

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

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

بالإضافة إلى ذلك، يتيح الإصدار 4 من Sheets API أيضًا إلحاق خلايا بخصائص وتنسيق معيّنَين باستخدام طلبات AppendCells في spreadsheets.batchUpdate.

الإصدار 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>

الإصدار 4 من واجهة برمجة التطبيقات

باستخدام الإصدار 4 من Sheets API، يمكنك تعديل صف باستخدام علامة A1 للصف الذي تريد تعديله وإصدار طلب spreadsheets.values.update لاستبدال هذا الصف. يشير النطاق المحدد إلى الخلية الأولى فقط في الصف، وتستنتج واجهة برمجة التطبيقات الخلايا المطلوب تحديثها بناءً على القيم المقدمة مع الطلب. إذا حددت بدلاً من ذلك نطاقًا متعدد الخلايا، فإن القيم التي تقدمها يجب أن تندرج ضمن هذا النطاق؛ وإذا لم تعرض واجهة برمجة التطبيقات خطأ.

يضيف المثال التالي لنص الطلب والطلب بيانات إلى الصف الرابع من "Sheet1":

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

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

يمكنك أيضًا تعديل بيانات الصفوف من الطريقة spreadsheet.values.batchUpdate؛ ويكون استخدام هذه الطريقة أكثر فعالية إذا كنت تجري تعديلات متعددة للصفوف أو الخلايا.

بالإضافة إلى ذلك، يتيح لك الإصدار 4 من Sheets API أيضًا تعديل خصائص الخلايا وتنسيق الخلايا باستخدام طلبات UpdateCells أو RepeatCell في spreadsheets.batchUpdate.

الإصدار 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. (في هذه الحالة، لا تحتاج إلى استرداد الصف قبل حذفه.)

الإصدار 4 من واجهة برمجة التطبيقات

تتم معالجة حذف الصفوف التي تتضمّن الإصدار 4 من 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 للورقة باستخدام طريقة spreadsheet.get.

الإصدار 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

يعرض الإصدار 3 من Sheets API inputValue للخلايا المستردة، وهي القيمة التي قد يكتبها المستخدم في واجهة مستخدم "جداول بيانات Google" لمعالجة الخلية. يمكن أن تكون inputValue قيمة حرفية أو معادلة. تعرض واجهة برمجة التطبيقات أحيانًا 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>

الإصدار 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.

الإصدار 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>

الإصدار 4 من واجهة برمجة التطبيقات

يمكن تعديل خلية واحدة في الإصدار 4 من Sheets API باستخدام الطريقة spreadsheets.values.update. تتطلب هذه الطريقة معلمة طلب البحث ValueInputOption، والتي تحدد ما إذا كان يتم التعامل مع بيانات الإدخال كما لو تم إدخالها في واجهة مستخدم جداول البيانات (USER_ENTERED)، أو تُركت بدون تحليل وآخذة كما هي (RAW). على سبيل المثال، يتم تعديل الخلية التالية D2 باستخدام صيغة:

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

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

إذا كنت تجري تعديلات متعددة في الخلايا، استخدِم الطريقة spreadsheets.values.batchUpdate لإصدارها في طلب واحد.

الإصدار 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 التي تحتوي على المسار الكامل لمعرّف الخلية. جميع هذه الحقول مطلوبة لكل إدخال.

الإصدار 4 من واجهة برمجة التطبيقات

يوفر الإصدار 4 من 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"]]
       }
  ]
}

إذا حددت خلية واحدة كنطاق، فستتم كتابة جميع القيم المقدمة إلى الورقة بدءًا من تلك الخلية كالإحداثي العلوي الأيسر. إذا حددت بدلاً من ذلك نطاقًا متعدد الخلايا، يجب أن تتناسب القيم التي تقدمها مع هذا النطاق تمامًا؛ وإذا لم تكن واجهة برمجة التطبيقات تعرض خطأً.