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

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

توفّر هذه الصفحة ربطًا بين الأوامر القديمة في الإصدار 3 من Sheets API والعمليات المكافئة لها في الإصدار 4 من Sheets API. يركّز الربط بشكل كبير على مجموعة spreadsheets.values التي توفّر وظائف قراءة الخلايا وكتابتها مباشرةً. تتولّى مجموعة جداول البيانات معالجة الجوانب الأخرى، مثل إضافة أوراق أو تعديل خصائص الأوراق. يُرجى العلم أنّ بنى JSON في الإصدار 4 من واجهة برمجة التطبيقات غير متوافقة مع بنى XML المستخدَمة في الإصدار 3.

للمزيد من المعلومات حول المراجع المتاحة في Sheets API الإصدار 4، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

الرموز والمصطلحات

تشير واجهة برمجة التطبيقات الإصدار 3 إلى الأوراق ضِمن جدول بيانات معيّن باسم "أوراق العمل". وهي مرادفة لمصطلح "الجداول" الذي تستخدمه واجهة برمجة التطبيقات v4.

تتطلّب منك واجهات برمجة التطبيقات غالبًا تحديد معرّف جدول بيانات للجدول الذي تعمل عليه. وغالبًا ما تتطلّب أيضًا إدخال رقم تعريف ورقة البيانات التي يتم التعديل عليها. تظهر هذه القيم إما كجزء من عنوان URL لنقطة نهاية واجهة برمجة التطبيقات، أو كمعلمات طلب بحث، أو كجزء من نص الطلب. في هذه الصفحة، يشير العنصران النائبان spreadsheetId وsheetId إلى معرّفَي جدول البيانات والورقة على التوالي. عند استخدام الطرق الموضّحة في هذه الصفحة، استبدِل المعرّفات الفعلية في هذه المواقع.

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

السماح بالطلبات

عند تشغيل تطبيقك، يطلب من المستخدمين منح أذونات معيّنة، وتحدّد النطاقات التي تحدّدها في تطبيقك الأذونات التي يطلبها.

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

تعمل واجهة Sheets API v3 بنطاق تفويض واحد:

https://spreadsheets.google.com/feeds

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

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

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

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

تستخدم واجهة برمجة التطبيقات Sheets API الإصدار 4 نطاقًا واحدًا أو أكثر من مجموعة النطاقات التالية:

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 الإصدار 3 مستوى العرض مباشرةً في نقاط النهاية. تم "نشر" جدول بيانات public على الويب، وبالتالي يمكن الوصول إليه من خلال واجهة برمجة التطبيقات بدون تفويض، بينما يتطلّب جدول بيانات private المصادقة. يتم تحديد مستوى العرض في نقطة النهاية بعد معرّف جدول البيانات:

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

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

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

الإسقاط

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

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

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

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

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

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

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

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

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

إنشاء جدول بيانات

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

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

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

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

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

POST https://sheets.googleapis.com/v4/spreadsheets
 
{
 "properties": {"title": "NewTitle"}
}

إدراج جداول البيانات للمستخدم الذي تمت المصادقة عليه

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

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

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

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

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

استرداد البيانات الوصفية للورقة

توفّر واجهة Sheets API الإصدار 3 خلاصة للوصول إلى البيانات الوصفية الخاصة بورقة البيانات المضمّنة في جدول بيانات معيّن (يتم الوصول إلى بيانات الصفوف والخلايا من خلال خلاصة منفصلة). تتضمّن البيانات الوصفية معلومات مثل عناوين أوراق البيانات ومعلومات الحجم.

توفّر الطريقة spreadsheets.get في Sheets API v4 إمكانية الوصول إلى هذه المعلومات وغيرها الكثير.

الإصدار 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 من واجهة برمجة التطبيقات

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

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

تغيير عنوان ورقة وحجمها

تتيح لك واجهة Sheets API v3 تعديل عناوين الجداول وحجمها، كما تتيح لك واجهة Sheets API v4 إجراء ذلك، بالإضافة إلى تعديل خصائص أخرى للجداول. يُرجى العِلم أنّ تقليل حجم ورقة قد يؤدي إلى حذف البيانات في الخلايا التي تم اقتصاصها بدون تحذير.

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

استرداد بيانات الصفوف

خلاصة صفوف القائمة هي إحدى الطريقتَين اللتَين توفّرهما واجهة Sheets API v3 للوصول إلى البيانات داخل خلايا جدول بيانات (الطريقة الأخرى هي خلاصة الخلايا). تم تصميم خلاصة الصفوف لتتوافق مع عمليات جداول البيانات الشائعة (القراءة صفًا صفًا، وإلحاق الصفوف، والترتيب)، ولكنها تتضمّن بعض الافتراضات التي تجعلها غير مناسبة لبعض المهام. على وجه التحديد، تفترض خلاصة القائمة أنّ الصفوف الفارغة هي نهايات الخلاصة، وأنّ العناوين الإلزامية مضمّنة في الصف الأول من ورقة البيانات.

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

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

يتم تلقائيًا عرض الصفوف التي تم إرجاعها في خلاصة القائمة بترتيب الصفوف. توفّر واجهة Sheets API الإصدار 3 مَعلمات طلب بحث لتغيير هذا الترتيب.

الترتيب العكسي:

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 الإصدار 3 أيضًا فلترة صفوف معيّنة من خلال طلب بحث منظَّم (يتم الرجوع إليه من خلال عناوين الأعمدة):

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

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

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

إضافة صف جديد من البيانات

يمكنك إضافة صف جديد من البيانات إلى جدول بيانات باستخدام أيّ من واجهتَي برمجة التطبيقات.

الإصدار 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 من واجهة برمجة التطبيقات

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

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

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

بالإضافة إلى ذلك، تتيح لك واجهة Sheets API الإصدار 4 أيضًا إلحاق خلايا بخصائص وتنسيق محدّدين باستخدام طلبات 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 من واجهة برمجة التطبيقات

باستخدام Sheets API v4، يمكنك تعديل صف باستخدام ترميز 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، ويُعدّ استخدام هذه الطريقة أكثر فعالية إذا كنت تريد إجراء تعديلات متعددة على الصفوف أو الخلايا.

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

يتم حذف الصفوف باستخدام 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 الإصدار 3 خلاصة خلايا للوصول الأساسي إلى جميع البيانات المخزّنة في جدول بيانات. بالنسبة إلى إذن القراءة، يمكن أن توفّر خلاصة الخلايا محتوى ورقة البيانات بأكملها أو نطاقًا من خلايا ورقة البيانات محدّدًا بمجموعة من مَعلمات طلب البحث، ولكن ككتلة واحدة فقط، ويجب استرداد النطاقات المنفصلة بشكل منفصل باستخدام طلبات GET إضافية.

يمكن لواجهة Sheets API الإصدار 4 استرداد أي مجموعة من بيانات الخلايا من ورقة (بما في ذلك نطاقات متعدّدة منفصلة). يمكن لواجهة Sheets API الإصدار 3 عرض محتوى الخلايا فقط كقيم إدخال (كما يدخلها المستخدم من لوحة المفاتيح) و/أو نواتج الصيغة (إذا كانت رقمية)؛ بينما تمنح واجهة Sheets API الإصدار 4 إذن الوصول الكامل إلى القيم والصيغ والتنسيق والارتباطات التشعبية والتحقّق من صحة البيانات والخصائص الأخرى.

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

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

تعديل خلية

تتيح لك Sheets API الإصدار 3 تعديل محتوى الخلايا من خلال إصدار الأمر PUT إلى خلاصة الخلايا مع إدخال الخلية المعدَّلة كنص الطلب.

في المقابل، توفّر Sheets API v4 الطريقتَين spreadsheets.values.update وspreadsheets.values.batchUpdate لتغيير محتوى الخلايا.

الإصدار 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 من واجهة برمجة التطبيقات

يمكن إجراء تعديل خلية واحدة في Sheets API v4 باستخدام الطريقة spreadsheets.values.update. تتطلّب هذه الطريقة مَعلمة طلب ValueInputOption، والتي تحدّد ما إذا كان سيتم التعامل مع البيانات المدخلة كما لو تم إدخالها في واجهة مستخدم &quot;جداول بيانات Google&quot; (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 من واجهة برمجة التطبيقات Sheets API إمكانية إجراء التعديلات الأخرى بنجاح. ومع ذلك، تعرض Sheets API v4 خطأً في حال تعذُّر إجراء أي من التعديلات المجمّعة، ولا يتم تطبيق أي منها في هذه الحالة.

الإصدار 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 من واجهة برمجة التطبيقات

توفّر واجهة 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"]]
       }
  ]
}

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