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

واجهة برمجة التطبيقات v3

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

https://spreadsheets.google.com/feeds

وهو عنوان بديل لـ

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

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

واجهة برمجة التطبيقات v4

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

واجهة برمجة التطبيقات v3

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

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

واجهة برمجة التطبيقات v4

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

واجهة برمجة التطبيقات v3

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

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

إنّ المجموعة الفرعية الأصغر من البيانات التي يوفّرها إسقاط basic قيّمة لتحسين كفاءة الرمز، ولكن لا يمكن تخصيصها.

واجهة برمجة التطبيقات v4

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

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

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

واجهة برمجة التطبيقات v3

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

واجهة برمجة التطبيقات v4

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

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

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

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

واجهة برمجة التطبيقات v3

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

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

واجهة برمجة التطبيقات v4

لا توفّر واجهة برمجة التطبيقات 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'

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

واجهة برمجة التطبيقات v3

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

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

يتضمّن الردّ على هذا الطلب بنية مشابهة لهذه، مع تضمين data لكل ورقة في <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

يمكن استخدام الطريقة 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
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

واجهة برمجة التطبيقات v3

يمكن لواجهة 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

يمكنك إضافة جداول جديدة من خلال تقديم طلب AddSheet في الطريقة spreadsheets.batchUpdate. كجزء من محتوى الطلب، يمكنك تحديد سمات جدول بيانات الجداول الجديدة، وجميع السمات اختيارية. يُعدّ تقديم عنوان يُستخدَم لجدول بيانات حالي خطأ.

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

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

واجهة برمجة التطبيقات v3

لتغيير عنوان ورقة البيانات أو حجمها، ابدأ باسترداد خلاصة ورقة البيانات و العثور على إدخال ورقة البيانات المطلوب الذي يحتوي على عنوان 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

لتعديل المقاس والعنوان وغيرها من سمات ورقة البيانات، قدِّم طلبًا لسمة 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.

واجهة برمجة التطبيقات v3

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

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

واجهة برمجة التطبيقات v4

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

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

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

لاسترداد sheetId لصفحة فردية، استخدِم الإجراء spreadsheets.get لجدول البيانات.

واجهة برمجة التطبيقات v3

لتحديد عنوان 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

واجهة برمجة التطبيقات v4

باستخدام الإصدار 4 من واجهة برمجة التطبيقات Sheets API، يمكن استرداد الصفوف حسب النطاق باستخدام الطريقتَين spreadsheets.values.get أو spreadsheets.values.batchGet. على سبيل المثال، يعرض الإجراء التالي جميع الصفوف في "الجدول1":

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

واجهة برمجة التطبيقات v3

لتحديد عنوان 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

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

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

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

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

واجهة برمجة التطبيقات v3

لتعديل صف من البيانات، راجِع خلاصة القائمة لتحديد موقع الإدخال للصف الذي تريد تعديله. عدِّل محتويات هذه الإدخالات حسب الحاجة. تأكَّد من أنّ قيمة المعرّف في الإدخال الذي تستخدمه تتماثل تمامًا مع معرّف الإدخال الحالي.

بعد تعديل الإدخال، أرسِل طلبًا إلى 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

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

في المثال التالي للطلب ونص الطلب، تتم إضافة بيانات إلى الصف الرابع من "الجدول1":

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.

واجهة برمجة التطبيقات v3

لحذف صف، عليك أولاً استرداد الصف المراد حذفه من خلاصة القائمة، ثم إرسال طلب 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

يتم حذف الصفوف باستخدام 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.

واجهة برمجة التطبيقات v3

لتحديد عنوان URL لخلاصة مستندة إلى خلية لجدول بيانات معيّن، راجِع خلاصة جدول البيانات وابحث عن عنوان URL لخلاصة الخلية في إدخال جدول البيانات الذي يهمّك.

لاسترداد خلاصة مستندة إلى خلية، أرسِل طلب GET إلى عنوان URL لخلاصة الخلايا، باستخدام رأس تفويض مناسب. على سبيل المثال:

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

تتم الإشارة إلى الخلايا باستخدام رقم الصف والعمود. يمكن جلب قياس واحد محدّد باستخدام مَعلمات طلب البحث max-row وmin-row وmax-col وmin-col. على سبيل المثال، يسترجع ما يلي جميع الخلايا في العمود 4 (د)، بدءًا من الصف 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>

واجهة برمجة التطبيقات v4

استرداد بيانات الخلايا من خلال استدعاء spreadsheets.values.get أو spreadsheets.values.batchGet للنطاق أو النطاقات التي تهمّك، على التوالي على سبيل المثال، يعرض الإجراء التالي الخلايا في العمود D من "الجدول2"، بدءًا من الصف 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.

واجهة برمجة التطبيقات v3

لتعديل محتوى خلية واحدة، ابحث أولاً عن إدخال الخلية في خلاصة الخلايا. يحتوي الإدخال على عنوان 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>

واجهة برمجة التطبيقات v4

يمكن إجراء تعديل خلية واحدة في Sheets API v4 باستخدام الأسلوب 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 لإصدارها في طلب واحد.

واجهة برمجة التطبيقات v3

لتعديل عدة خلايا، استرد أولاً خلاصة خلية لجدول البيانات. يحتوي الإدخال على عنوان 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

توفّر واجهة برمجة التطبيقات 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"]]
       }
  ]
}

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