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

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

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

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

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

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

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

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

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

يوضّح نموذج الرمز التالي كيفية استخدام 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"
          }
        ]
      }
    }
  ]
}