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

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

استخدام الطريقة Files.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 من واجهة برمجة التطبيقات

يمكن للإصدار 3 من 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، وهي ما إذا كان سيتم التعامل مع بيانات الإدخال كما لو تم إدخالها في واجهة المستخدم في "جداول بيانات Google" (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"]]
       }
  ]
}

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