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

.

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

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

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

التدوين والمصطلحات

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

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

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

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

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

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

مستوى الرؤية

في الإصدارات الأقدم من واجهة برمجة التطبيقات، يتم استخدام مصطلح visibility للإشارة إلى مدى توفر جدول بيانات معين.

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

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

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

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

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

الإسقاط

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

توفر طريقة spreadsheets.get في Google 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 من واجهة برمجة التطبيقات

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

الإصدار 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 من Sheets API للوصول إلى البيانات داخل خلايا جدول البيانات (الأخرى هي خلاصة الخلايا). تهدف خلاصة الصفوف إلى دعم العمليات الشائعة لجداول البيانات (القراءة صفًا تلو الآخر، وإلحاق الصفوف، والفرز)، ولكنها تضع افتراضات معينة تجعلها غير مناسبة لبعض المهام. على وجه التحديد، تفترض خلاصة القائمة أنّ الصفوف الفارغة هي بمثابة إنهاء للخلاصة، وأنّ العناوين الإلزامية موجودة في الصف الأول من الورقة.

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

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

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

الإصدار 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 Sheets لمعالجة الخلية. وقد يكون 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 من Sheets API تعديل محتوى الخلية عن طريق إصدار أمر PUT إلى خلاصة الخلية مع إدخال الخلية المعدَّلة كنص الطلب.

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

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

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

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