PHP中通过getByDataFilter按工作表名筛选获取Google Sheets单元格格式

问题背景 #

我有一个包含多个工作表的大型复杂Google表格，需要获取其中部分工作表所有单元格的格式（如字体颜色）。使用spreadsheets->get并添加includeGridData参数时：

$sheetMeta = $service->spreadsheets->get($spreadsheetId,['includeGridData' => true]);

请求会超时或耗尽资源，因此尝试用getByDataFilter按工作表筛选，但以下代码报错：

$body= json_encode(array('data_filters' => [], 'include_grid_data'=>true));
$response = $service->spreadsheets->getByDataFilter($spreadsheetId, $body);

错误信息：

Expected parameter of type 'Google\Service\Sheets\GetSpreadsheetByDataFilterRequest'

正确实现代码 #

Google Sheets PHP API要求getByDataFilter方法的第二个参数必须是GetSpreadsheetByDataFilterRequest实例，而非JSON字符串或数组。以下是完整的可运行示例：

// 初始化请求对象
$request = new Google\Service\Sheets\GetSpreadsheetByDataFilterRequest();

// 构建要筛选的工作表数据过滤器数组
$dataFilters = [];

// 示例1：按工作表名称筛选（比如筛选"Sheet1"和"Sheet2"）
// 第一个工作表筛选器
$sheetFilter1 = new Google\Service\Sheets\SheetDataFilter();
$sheetFilter1->setSheetName("Sheet1");
$filter1 = new Google\Service\Sheets\DataFilter();
$filter1->setSheetFilter($sheetFilter1);
$dataFilters[] = $filter1;

// 第二个工作表筛选器
$sheetFilter2 = new Google\Service\Sheets\SheetDataFilter();
$sheetFilter2->setSheetName("Sheet2");
$filter2 = new Google\Service\Sheets\DataFilter();
$filter2->setSheetFilter($sheetFilter2);
$dataFilters[] = $filter2;

// 示例2：按工作表ID筛选（替换为你的工作表ID）
// $sheetFilter3 = new Google\Service\Sheets\SheetDataFilter();
// $sheetFilter3->setSheetId(123456789);
// $filter3 = new Google\Service\Sheets\DataFilter();
// $filter3->setSheetFilter($sheetFilter3);
// $dataFilters[] = $filter3;

// 将筛选器添加到请求，并开启格式数据获取
$request->setDataFilters($dataFilters);
$request->setIncludeGridData(true);

// 执行请求
$response = $service->spreadsheets->getByDataFilter($spreadsheetId, $request);

// 解析返回的格式数据
foreach ($response->getSheets() as $sheet) {
    $sheetTitle = $sheet->getProperties()->getTitle();
    echo "工作表：{$sheetTitle}\n";
    
    foreach ($sheet->getData() as $gridData) {
        foreach ($gridData->getRowData() as $row) {
            foreach ($row->getValues() as $cell) {
                $textFormat = $cell->getUserEnteredFormat()?->getTextFormat();
                if ($textFormat) {
                    $fontColor = $textFormat->getForegroundColor();
                    echo "单元格字体颜色：" . print_r($fontColor, true) . "\n";
                }
            }
        }
    }
}

错误原因说明 #

之前的代码直接传入JSON字符串，不符合API参数要求。Google Sheets PHP API的getByDataFilter方法要求第二个参数必须是Google\Service\Sheets\GetSpreadsheetByDataFilterRequest类型的实例，需要通过API提供的实体类来构建请求体，而非手动序列化JSON。

内容的提问来源于stack exchange，提问作者Dan Wenschhof