为 API 请求授权

BigQuery API 使用 OAuth 2.0 访问令牌或 JSON Web 令牌 (JWT) 向请求授权。这些令牌授予对 API 的临时访问权限。

您应该尽可能使用应用中的应用默认凭据 (ADC) 从常见来源（包括 OAuth 2.0 和 JWT）发现凭据。如需了解详情，请参阅自动查找凭据。

如果您无法使用 ADC，则可以使用 Google 的 OAuth 2.0 服务器获取 OAuth 2.0 访问令牌，或者，如果您使用服务账号进行身份验证，则可以改为使用签名的 JWT。使用 JWT 可以避免在发出 API 调用之前向 Google 的授权服务器发出网络请求。

准备工作

使用 OAuth 2.0 进行身份验证

本部分介绍如何向 BigQuery API 提供 OAuth 2.0 访问令牌。如果您使用 BigQuery 客户端库，则无需此信息，因为系统会自动为您完成此操作。

范围

访问令牌与一个范围关联，此范围会限制令牌的访问权限。如需了解与 BigQuery API 关联的范围，请参阅完整的 Google API 范围列表。

获取访问令牌

使用应用默认凭据获取临时访问令牌。

命令行

使用 Google Cloud CLI 来输出访问令牌。

ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"

请参阅身份验证指南，以了解如何在其他环境中获取访问令牌。

由于访问令牌仅提供临时授权，因此您必须定期刷新访问令牌。

向请求授权

要使用访问令牌为针对 BigQuery API 的请求授权，您可以使用任一种 OAuth 2.0 令牌使用方法。

请求标头

在 Authorization 请求标头中设置值为 Bearer ACCESS_TOKEN 的令牌。

命令行

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://www.googleapis.com/bigquery/v2/projects/$GOOGLE_CLOUD_PROJECT/datasets"

使用 JWT 进行身份验证

您可以通过以下方式使用 JWT 进行身份验证：

受众

对于 JWT，使用目标设备声明而不是范围。对于 BigQuery API，请将目标设备值设置为 https://bigquery.googleapis.com/。

使用客户端库创建 JWT

对于在 Google Cloud 控制台中或使用 gcloud CLI 创建的服务账号密钥，请使用提供 JWT 签名的客户端库。以下列表提供了一些适用于常用编程语言的选项：

Java 示例

以下示例使用 Java 版 BigQuery 客户端库创建和签署 JWT。

import com.google.auth.Credentials;
import com.google.auth.oauth2.ServiceAccountJwtAccessCredentials;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

import java.io.FileInputStream;
import java.net.URI;

public class Example {
    public static void main(String... args) throws Exception {
        String projectId = "myproject";
        // Load JSON file that contains service account keys and create ServiceAccountJwtAccessCredentials object.
        String credentialsPath = "/path/to/key.json";
        URI audience = URI.create("https://bigquery.googleapis.com/");
        Credentials credentials = null;
        try (FileInputStream is = new FileInputStream(credentialsPath)) {
            credentials = ServiceAccountJwtAccessCredentials.fromStream(is, audience);
        }
        // Instantiate BigQuery client with the credentials object.
        BigQuery bigquery =
                BigQueryOptions.newBuilder().setCredentials(credentials).build().getService();
        // Use the client to list BigQuery datasets.
        System.out.println("Datasets:");
        bigquery
            .listDatasets(projectId)
            .iterateAll()
            .forEach(dataset -> System.out.printf("%s%n", dataset.getDatasetId().getDataset()));
    }
}

使用 REST 或 gcloud CLI 创建 JWT

对于系统管理的服务账号，您必须手动组合 JWT，然后使用 REST 方法 projects.serviceAccounts.signJwt 或 Google Cloud CLI 命令 gcloud beta iam service-accounts sign-jwt 来签署 JWT。如需使用上述任何一种方法，您必须是 Service Account Token Creator Identity and Access Management 角色的成员。

gcloud CLI 示例

以下示例展示了一个 bash 脚本，该脚本组合 JWT，然后使用 gcloud beta iam service-accounts sign-jwt 命令来签署它。

#!/bin/bash

SA_EMAIL_ADDRESS="myserviceaccount@myproject.iam.gserviceaccount.com"

TMP_DIR=$(mktemp -d /tmp/sa_signed_jwt.XXXXX)
trap "rm -rf ${TMP_DIR}" EXIT
JWT_FILE="${TMP_DIR}/jwt-claim-set.json"
SIGNED_JWT_FILE="${TMP_DIR}/output.jwt"

IAT=$(date '+%s')
EXP=$((IAT+3600))

cat <<EOF > $JWT_FILE
{
  "aud": "https://bigquery.googleapis.com/",
  "iat": $IAT,
  "exp": $EXP,
  "iss": "$SA_EMAIL_ADDRESS",
  "sub": "$SA_EMAIL_ADDRESS"
}
EOF

gcloud beta iam service-accounts sign-jwt --iam-account $SA_EMAIL_ADDRESS $JWT_FILE $SIGNED_JWT_FILE

echo "Datasets:"
curl -L -H "Authorization: Bearer $(cat $SIGNED_JWT_FILE)" \
-X GET \
"https://bigquery.googleapis.com/bigquery/v2/projects/myproject/datasets?alt=json"

后续步骤

  • 如需了解如何通过编程方式获取 OAuth 2.0 访问令牌，请参阅身份验证指南。