سرویس برگه های پیشرفته

سرویس Advanced Sheets به شما امکان می‌دهد با استفاده از Apps Script به Sheets API دسترسی داشته باشید. این API بسیار شبیه به سرویس Google Sheets API داخلی Apps Script است، و به اسکریپت‌ها اجازه می‌دهد داده‌ها را در Google Sheets بخوانند، ویرایش کنند، قالب‌بندی کنند و ارائه دهند. در بیشتر موارد، استفاده از سرویس داخلی آسان‌تر است، اما این سرویس پیشرفته چند ویژگی اضافی نیز ارائه می‌دهد.

مرجع

برای اطلاعات دقیق در مورد این سرویس، به مستندات مرجع API مربوط به Sheets مراجعه کنید. مانند تمام سرویس‌های پیشرفته در Apps Script، سرویس پیشرفته Sheets از همان اشیاء، متدها و پارامترهای API عمومی استفاده می‌کند. برای اطلاعات بیشتر، به بخش «نحوه تعیین امضاهای متد» مراجعه کنید.

برای گزارش مشکلات و یافتن پشتیبانی‌های دیگر، به راهنمای پشتیبانی Sheets مراجعه کنید.

کد نمونه

کد نمونه زیر از نسخه ۴ این API استفاده می‌کند؛ این تنها نسخه از API Sheets است که در حال حاضر به عنوان یک سرویس پیشرفته در 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);
  }
}