عمليات البيانات

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

يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون متعافِية من اللغة. للتعرّف على كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج Google API، اطّلِع على مقالة تعديل جداول بيانات Google.

في هذين المثالَين، تشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى المكان الذي يجب فيه تقديم معرّفات التطبيقَين. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على معرّف جدول البيانات باستخدام الأسلوب spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. أحد مثالي النطاق هو الورقة1!A1:D5.

تطبيق ميزة "التحقّق من صحة البيانات" على نطاق

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام SetDataValidationRequest لتطبيق قاعدة التحقّق من صحة البيانات، حيث تكون "القيمة > 5"، على كل خلية في النطاق A1:D10.

يظهر بروتوكول الطلب أدناه.

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

{
  "requests": [
    {
      "setDataValidation": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "rule": {
          "condition": {
            "type": "NUMBER_GREATER",
            "values": [
              {
                "userEnteredValue": "5"
              }
            ]
          },
          "inputMessage": "Value must be > 5",
          "strict": true
        }
      }
    }
  ]
}

نسخ تنسيق الخلايا ولصقه

يوضّح نموذج الرمز التالي spreadsheets.batchUpdate كيفية استخدام الرمز CopyPasteRequest لنسخ التنسيق في النطاق A1:D10 فقط ولصقه في النطاق F1:I10 في الورقة نفسها. تستخدِم الطريقة العنصر النائب PasteType مع PASTE_FORMAT للصق التنسيق والتحقّق من صحة البيانات فقط. تظلّ القيم الأصلية في A1:D10 بدون تغيير.

يظهر بروتوكول الطلب أدناه.

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

{
  "requests": [
    {
      "copyPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 5,
          "endColumnIndex": 9
        },
        "pasteType": "PASTE_FORMAT",
        "pasteOrientation": "NORMAL"
      }
    }
  ]
}

قص الخلايا ولصقها

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام الرمز CutPasteRequest. تقطع هذه الدالة النطاق A1:D10 وتستخدم العنصر المدرَج PasteType مع PASTE_NORMAL للصق قيمه وصيغه وتنسيقه ودمج النطاق F1:I10 في الورقة نفسها. تتم إزالة محتويات خلايا نطاق المصدر الأصلي.

يظهر بروتوكول الطلب أدناه.

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

{
  "requests": [
    {
      "cutPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "rowIndex": 0,
          "columnIndex": 5
        },
        "pasteType": "PASTE_NORMAL"
      }
    }
  ]
}

تكرار صيغة على نطاق

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام الرمز RepeatCellRequest لنسخ الصيغة =FLOOR(A1*PI()) إلى النطاق B1:D10. يزداد نطاق الصيغة تلقائيًا لكل صف وعمود في النطاق، بدءًا من الخلية العلوية اليسرى. على سبيل المثال، تحتوي الخلية B1 على الصيغة =FLOOR(A1*PI())، بينما تحتوي الخلية D6 على الصيغة =FLOOR(C6*PI()).

يظهر بروتوكول الطلب أدناه.

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

{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 4
        },
        "cell": {
          "userEnteredValue": {
              "formulaValue": "=FLOOR(A1*PI())"
          }
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

ترتيب نطاق باستخدام مواصفات ترتيب متعددة

يوضِّح نموذج التعليمات البرمجية التالي spreadsheets.batchUpdate كيفية استخدام الرمز SortRangeRequest لترتيب النطاق A1:D10، أولاً حسب العمود B بترتيب تصاعدي، ثم حسب العمود C بترتيب تنازلي، ثم حسب العمود D بترتيب تنازلي.

يظهر بروتوكول الطلب أدناه.

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

{
  "requests": [
    {
      "sortRange": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "sortSpecs": [
          {
            "dimensionIndex": 1,
            "sortOrder": "ASCENDING"
          },
          {
            "dimensionIndex": 2,
            "sortOrder": "DESCENDING"
          },
          {
            "dimensionIndex": 3,
            "sortOrder": "DESCENDING"
          }
        ]
      }
    }
  ]
}