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

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

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

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى المكان الذي ستوفّر فيه هذه المعرّفات. يمكنك العثور على معرّف جدول البيانات في عنوان URL الخاص بجدول البيانات. يمكنك الحصول على معرّف جدول البيانات باستخدام طريقة spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. مثال على النطاق: Sheet1!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 لنسخ التنسيق فقط في النطاق A1:D10 ولصقه في النطاق F1:I10 في ورقة البيانات نفسها.CopyPasteRequest تستخدم الطريقة التعداد 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. يقطع النطاق A1:D10 ويستخدم التعداد PasteType مع PASTE_NORMAL للصق قيمه وصيغه وتنسيقه وعمليات الدمج في النطاق F1:I10 في ورقة البيانات نفسها. تتم إزالة محتوى خلايا النطاق المصدر الأصلي.CutPasteRequest

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

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"
      }
    }
  ]
}

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

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

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

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"
          }
        ]
      }
    }
  ]
}