خدمة "جداول بيانات Google" المتقدمة

تتيح لك خدمة "جداول بيانات متقدمة" الوصول إلى واجهة برمجة تطبيقات جداول البيانات باستخدام "برمجة التطبيقات". تسمح واجهة برمجة التطبيقات هذه للنصوص البرمجية بقراءة البيانات وتعديلها وتنسيقها وتقديمها في "جداول بيانات Google"، كما هو الحال إلى حد كبير مع خدمة واجهة برمجة تطبيقات "جداول بيانات Google" المضمّنة في "برمجة التطبيقات". في معظم الحالات، تكون الخدمة المُدمجة أسهل من حيث الاستخدام، لكن هذه الخدمة المتقدّمة توفّر بعض الميزات الإضافية.

مَراجع

للحصول على معلومات تفصيلية حول هذه الخدمة، اطّلع على المستندات المرجعية لواجهة برمجة تطبيقات Sheets. مثل جميع الخدمات المتقدمة في "برمجة التطبيقات"، تستخدم خدمة "جداول بيانات Google" المتقدمة العناصر والطرق والمعلَمات نفسها التي تستخدمها واجهة برمجة التطبيقات العامة. لمزيد من المعلومات، يُرجى الاطِّلاع على كيفية تحديد توقيعات الطريقة.

للإبلاغ عن المشاكل والعثور على خدمات دعم أخرى، يُرجى الاطّلاع على دليل دعم "جداول بيانات Google".

نموذج التعليمات البرمجية

يستخدم الرمز النموذجي أدناه الإصدار 4 من واجهة برمجة التطبيقات، وهو الإصدار الوحيد المتاح حاليًا من Sheets API كخدمة متقدمة في Apps Script.

قراءة القيم من نطاق

يوضح المثال التالي كيفية قراءة قيم البيانات من نطاق محدد في ورقة باستخدام الخدمة المتقدمة لـ Sheets. تعادل هذه الطريقة عيّنة وصفة قراءة نطاق واحد.

إعدادات متقدمة/sheets.gs
/**
 * Read a range (A1:D5) of data values. Logs the values.
 * @param {string} spreadsheetId The spreadsheet ID to read from.
 * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/get
 */
function readRange(spreadsheetId = yourspreadsheetId) {
  try {
    const response = Sheets.Spreadsheets.Values.get(spreadsheetId, 'Sheet1!A1:D5');
    if (response.values) {
      console.log(response.values);
      return;
    }
    console.log('Failed to get range of values from spreadsheet');
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', e.message);
  }
}

كتابة قيم لنطاقات متعددة

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

إعدادات متقدمة/sheets.gs
/**
 * Write to multiple, disjoint data ranges.
 * @param {string} spreadsheetId The spreadsheet ID to write to.
 * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/batchUpdate
 */
function writeToMultipleRanges(spreadsheetId = yourspreadsheetId) {
  // Specify some values to write to the sheet.
  const columnAValues = [
    ['Item', 'Wheel', 'Door', 'Engine']
  ];
  const rowValues = [
    ['Cost', 'Stocked', 'Ship Date'],
    ['$20.50', '4', '3/1/2016']
  ];

  const request = {
    'valueInputOption': 'USER_ENTERED',
    'data': [
      {
        'range': 'Sheet1!A1:A4',
        'majorDimension': 'COLUMNS',
        'values': columnAValues
      },
      {
        'range': 'Sheet1!B1:D2',
        'majorDimension': 'ROWS',
        'values': rowValues
      }
    ]
  };
  try {
    const response = Sheets.Spreadsheets.Values.batchUpdate(request, spreadsheetId);
    if (response) {
      console.log(response);
      return;
    }
    console.log('response null');
  } catch (e) {
    // TODO (developer) - Handle  exception
    console.log('Failed with error %s', e.message);
  }
}

إضافة ورقة جديدة

يوضح المثال التالي كيفية إنشاء ورقة جديدة بحجم محدد ولون علامة تبويب. وهو يوازي عينة إضافة ورقة.

إعدادات متقدمة/sheets.gs
/**
 * Add a new sheet with some properties.
 * @param {string} spreadsheetId The spreadsheet ID.
 * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/batchUpdate
 */
function addSheet(spreadsheetId = yourspreadsheetId) {
  const requests = [{
    'addSheet': {
      'properties': {
        'title': 'Deposits',
        'gridProperties': {
          'rowCount': 20,
          'columnCount': 12
        },
        'tabColor': {
          'red': 1.0,
          'green': 0.3,
          'blue': 0.4
        }
      }
    }
  }];
  try {
    const response =
      Sheets.Spreadsheets.batchUpdate({'requests': requests}, spreadsheetId);
    console.log('Created sheet with ID: ' +
      response.replies[0].addSheet.properties.sheetId);
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', e.message);
  }
}

إنشاء جدول محوري

يوضح المثال التالي كيفية إنشاء جدول محوري من بيانات المصدر. وهو يكافئ نموذج وصفة إضافة جدول محوري.

إعدادات متقدمة/sheets.gs
/**
 * Add a pivot table.
 * @param {string} spreadsheetId The spreadsheet ID to add the pivot table to.
 * @param {string} pivotSourceDataSheetId The sheet ID to get the data from.
 * @param {string} destinationSheetId The sheet ID to add the pivot table to.
 * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/batchUpdate
 */
function addPivotTable(
    spreadsheetId = yourspreadsheetId,
    pivotSourceDataSheetId= yourpivotSourceDataSheetId,
    destinationSheetId= yourdestinationSheetId) {
  const requests = [{
    'updateCells': {
      'rows': {
        'values': [
          {
            'pivotTable': {
              'source': {
                'sheetId': pivotSourceDataSheetId,
                'startRowIndex': 0,
                'startColumnIndex': 0,
                'endRowIndex': 20,
                'endColumnIndex': 7
              },
              'rows': [
                {
                  'sourceColumnOffset': 0,
                  'showTotals': true,
                  'sortOrder': 'ASCENDING',
                  'valueBucket': {
                    'buckets': [
                      {
                        'stringValue': 'West'
                      }
                    ]
                  }
                },
                {
                  'sourceColumnOffset': 1,
                  'showTotals': true,
                  'sortOrder': 'DESCENDING',
                  'valueBucket': {}
                }
              ],
              'columns': [
                {
                  'sourceColumnOffset': 4,
                  'sortOrder': 'ASCENDING',
                  'showTotals': true,
                  'valueBucket': {}
                }
              ],
              'values': [
                {
                  'summarizeFunction': 'SUM',
                  'sourceColumnOffset': 3
                }
              ],
              'valueLayout': 'HORIZONTAL'
            }
          }
        ]
      },
      'start': {
        'sheetId': destinationSheetId,
        'rowIndex': 49,
        'columnIndex': 0
      },
      'fields': 'pivotTable'
    }
  }];
  try {
    const response = Sheets.Spreadsheets.batchUpdate({'requests': requests}, spreadsheetId);
    // The Pivot table will appear anchored to cell A50 of the destination sheet.
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', e.message);
  }
}