本教程详细讲解了在使用 php google bigquery 客户端库获取查询结果时，因未指定作业执行区域而导致 404 错误的常见问题。文章提供了明确的解决方案，即通过 `getqueryresults` 方法的第三个参数传入 `location` 选项，确保客户端能够正确检索到特定区域的 bigquery 作业结果，从而避免“job not found”错误。
BigQuery 作业与区域概念
Google BigQuery 是一项强大的、高度可扩展的无服务器数据仓库服务。在 BigQuery 中执行的任何查询或数据加载操作都被视为一个“作业”（Job）。这些作业通常在特定的地理区域（如 us-central1、europe-west1 或 asia-east1）内执行。即使在提交查询时没有显式指定区域，BigQuery 也会根据项目配置或默认设置在一个区域中运行该作业。
理解 BigQuery 作业的区域性至关重要，因为后续对该作业的任何操作（例如检查其状态、获取查询结果）都可能需要知道它是在哪个区域执行的。如果尝试从错误的区域或未指定区域检索作业，BigQuery 服务将无法找到它，从而导致错误。
问题描述：PHP 客户端获取 BigQuery 作业结果的 404 错误
在使用 PHP 的 Google BigQuery 客户端库（google/cloud-bigquery 或旧版 google/apiclient）时，开发者可能会遇到一个常见的 404 "Not found: Job" 错误，尤其是在尝试通过 getQueryResults 方法检索已成功提交的查询作业结果时。
例如，以下代码片段展示了提交 BigQuery 查询作业的典型流程：
立即学习“PHP免费学习笔记（深入）”；
setApplicationName('Google-BigQuery');
// 假设运行在 App Engine 或其他支持应用默认凭据的环境中
$client->useApplicationDefaultCredentials();
$client->addScope('https://www.googleapis.com/auth/bigquery');
$client->addScope('https://www.googleapis.com/auth/devstorage.read_write'); // 如果需要存储读写权限
$bq = new Bigquery($client);
$projectId = 'my-project'; // 替换为你的项目ID
// 构造查询作业配置
$query = "SELECT * FROM `my-project.my_dataset.my_table` LIMIT 100"; // 你的SQL查询
$queryConfig = new JobConfigurationQuery();
$queryConfig->setQuery($query);
$config = new JobConfiguration();
$config->setQuery($queryConfig);
$job = new Job();
$job->setConfiguration($config);
try {
// 提交查询作业
$submittedJob = $bq->jobs->insert($projectId, $job);
$jobReference = $submittedJob->getJobReference();
$jobId = $jobReference->getJobId();
$jobLocation = $jobReference->getLocation(); // 尝试获取作业的执行区域
echo "Job submitted successfully. Job ID: " . $jobId . ", Location: " . $jobLocation . PHP_EOL;
// 尝试获取查询结果 - 问题通常发生在这里
// 假设作业在 'europe-west1' 区域执行，但此处未指定
$queryResults = $bq->jobs->getQueryResults($projectId, $jobId); // 可能会导致 404 错误
} catch (\Google\Service\Exception $e) {
echo "Error submitting or fetching job: " . $e->getMessage() . PHP_EOL;
// 错误信息可能包含 "Not found: Job my-project:job-id"
// 或者 "Not found: Job my-project:job-id"
}
?>尽管作业提交（$bq->jobs->insert）可能成功，并且通过 BigQuery 控制台可以查看到该作业及其结果，但上述代码中的 $bq->jobs->getQueryResults($projectId, $jobId) 调用却经常返回 404 "Not found: Job" 错误。
这种错误的根本原因在于，BigQuery 作业的完整标识不仅包括项目 ID 和作业 ID，还可能隐含或明确包含其执行的区域信息。当客户端尝试不带区域信息去检索一个在特定区域执行的作业时，BigQuery 服务无法在默认或当前区域找到该作业，从而返回 404 错误。
解决方案：通过 location 参数指定作业区域
解决此问题的关键是，在调用 getQueryResults 方法时，明确告知 BigQuery 作业所在的区域。getQueryResults 方法接受一个可选的第三个参数，用于传递额外的查询选项，其中就包括 location。
你需要创建一个包含 location 键值对的关联数组，并将其作为第三个参数传递。例如，如果你的 BigQuery 作业在 europe-west1 区域执行，修正后的代码应如下所示：
jobs->insert($projectId, $job);
$jobReference = $submittedJob->getJobReference();
$jobId = $jobReference->getJobId();
$jobLocation = $jobReference->getLocation(); // 获取作业的实际执行区域
echo "Job submitted successfully. Job ID: " . $jobId . ", Location: " . $jobLocation . PHP_EOL;
// 构造包含 location 参数的选项数组
$options = ['location' => $jobLocation]; // 使用实际获取到的区域
// 使用带有 location 参数的 options 数组来获取查询结果
$queryResults = $bq->jobs->getQueryResults($projectId, $jobId, $options);
// 成功获取结果后，可以进一步处理 $queryResults
echo "Successfully fetched query results." . PHP_EOL;
// 例如，打印行数
echo "Total rows: " . $queryResults->getTotalRows() . PHP_EOL;
} catch (\Google\Service\Exception $e) {
echo "Error submitting or fetching job: " . $e->getMessage() . PHP_EOL;
}
?>通过这种方式，BigQuery 服务会知道在 $jobLocation 指定的区域查找 $jobId 这个作业，从而成功检索到结果。
确定 BigQuery 作业区域的方法
在实际应用中，你需要知道 BigQuery 作业是在哪个区域执行的。有几种方法可以确定这一点：
- 从 jobReference 对象获取： 当你成功提交一个 BigQuery 作业后，jobs->insert 方法返回的 Google\Service\Bigquery\Job 对象中的 jobReference 字段通常会包含 location 信息。这是最推荐和动态的方式。如上面的修正代码所示，可以通过 $submittedJob->getJobReference()->getLocation() 来获取。
- 从 BigQuery 控制台查看： 在 BigQuery UI 中，导航到“查询历史记录”或“作业”页面，点击特定的作业详情。在作业详情页面，通常会显示其执行的区域信息，格式可能为 project-id:region.job-id（例如 my-project:europe-west1.bquxjob_...）。
- 项目默认区域： 如果在提交作业时未明确指定区域，BigQuery 会使用项目配置的默认区域。在某些情况下，你可能需要确保你的查询也在特定区域执行，可以通过在 JobConfigurationQuery 中设置 defaultDataset 的 location 来影响作业的执行区域，但这通常是针对表和数据集的区域性，作业本身会基于这些区域或项目默认区域运行。
注意事项
- 区域一致性： 确保在提交作业（如果需要显式指定）和检索作业结果时使用的区域保持一致。如果不一致，仍可能导致“Job not found”错误。
- 错误处理： 始终为 BigQuery API 调用实现适当的错误处理机制。捕获 Google\Service\Exception 可以帮助你诊断问题，例如网络错误、权限问题或作业执行失败。
- Google Cloud 客户端库版本： 确保使用的 Google Cloud PHP 客户端库是最新版本，以获得最佳兼容性和功能支持。不同版本之间的方法签名或行为可能略有差异。
- 长时运行作业： 对于长时运行的 BigQuery 作业，你可能需要轮询作业状态，直到作业完成，然后再调用 getQueryResults。getQueryResults 方法本身也支持 timeoutMs 参数来等待作业完成，但最好是单独管理作业状态。
总结
在 PHP 中使用 Google BigQuery 客户端库处理作业时，明确指定作业的执行区域是避免 404 "Job not found" 错误的关键。通过在 getQueryResults 方法中传递 location 参数，可以确保客户端能够准确地定位并检索到 BigQuery 作业的结果。理解 BigQuery 的区域性是成功管理和操作其数据流的重要一环。始终从 jobReference 对象获取实际的作业区域，并将其用于后续的 API 调用，是处理这类问题的最佳实践。
