针对 Ambient API 配置您的应用

如需开始使用 Ambient API，请在 Google API 控制台中启用该 API 并设置 OAuth 2.0 客户端 ID，以便配置您的项目。Ambient API 使用适用于电视和输入受限的设备应用的 OAuth 2.0。

您的应用会代表 Ambient API 用户与 Ambient API 进行互动。用户使用 OAuth 2.0 协议授权这些 API 请求。

您的应用用户可利用 OAuth 2.0 客户端 ID 进行登录和身份验证，进而使用 Ambient API。Ambient API 不支持服务账号；如需使用这些 API，用户必须登录到有效的 Google 账号。

配置您的应用

请先启用该 API，然后请求 OAuth 2.0 客户端 ID。

启用 API

您必须先在项目中启用 Ambient API，然后才能使用它。

  1. 前往 Google API 控制台。
  2. 在菜单栏中选择项目或新建项目。
  3. 如需打开 Google 相册 API，请在导航菜单中依次选择 API 和服务 > 库。
  4. 搜索“Ambient API”。选择 Ambient API，然后点击启用。

请求 OAuth 2.0 客户端 ID

请按照以下步骤请求 OAuth 客户端 ID 并为您的应用进行配置。Ambient API 使用适用于电视和输入受限的设备应用的 OAuth 2.0。

  1. 前往 Google API 控制台，然后选择您的项目。
  2. 在菜单中，依次选择 API 和服务 > 凭据。

  3. 在凭据页面上，依次点击创建凭据 > OAuth 客户端 ID。

  4. 选择您的应用类型。在此示例中，应用类型为电视和受限输入设备。

  5. 为您的 OAuth 2.0 客户端提供一个名称，然后点击创建。

  6. 在显示的 OAuth 客户端对话框中，复制以下内容：

    • 客户 ID
    • 客户端密钥

利用这些值，您的应用便可访问已启用的 Google API。

在您启动访问 Ambient API 的公开应用前，您的应用必须经过 Google 审核。测试应用时，屏幕上会显示“未经验证的应用”消息，直至应用通过验证。

配置好应用后，您就可以开始使用了。您可以浏览以下资源，或继续了解 Ambient API 的简化身份验证流程。

更改客户端 ID

通过任何 Google 相册 API 创建的资源只能使用创建这些资源时所用的原始客户端 ID 进行访问或修改。例如，如果您使用特定客户端 ID 在 Picker API 中创建了 session，但后来在应用中更改了该客户端 ID，则您的应用将无法再访问使用之前的客户端 ID 创建的任何 API 资源。

请仔细规划，为您使用的 Google 相册 API 选择正确的客户端 ID 类型。请仅在绝对必要时更改您的客户端 ID，以免出现访问问题。

简化了 Ambient API 的身份验证流程

标准 Ambient API 身份验证流程要求用户扫描 2 个二维码：

  • 先登录 Google 账号（如果尚未登录）。
  • 第二个链接会指向 Google 相册账号中新创建的氛围模式设备，用户可以在该设备上选择要显示的媒体内容。

通过简化流程，您可以通过在初始身份验证调用中传递额外的 state 参数，向用户提供单个二维码。

在 OAuth 中请求设备和用户代码（适用于受限输入设备）时，请在请求中添加额外的 state 参数。将以下内容添加到 state 参数：

参数
requestId

string

必需。客户端为此请求提供的唯一标识符。这用于在网络故障时减少资源重复。

此 ID 必须采用 UUID（版本 4）字符串的格式，并符合以下要求：

  • 不得包含任何与用户相关的敏感身份信息。
  • 必须包含 32 个十六进制字符，这些字符由连字符分为五组，格式为“xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”（或 8-4-4-4-12）。
displayName

string

可选。此设备的用户定义显示名称。

用户可以在 Google 相册应用设置中看到此信息，但只能通过此 API 进行修改。

有效的显示名称必须介于 1 到 100 个字符之间（包括这两个数值）。

例如，请参阅以下代码块：

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

成功响应将包含 user_code 和 verification_url，您需要将其显示给用户（很可能是以二维码的形式），以便用户在其他设备上前往该位置。通过添加 state 参数，当您稍后使用 Ambient API 调用 createDevice 时，可以跳过在第二个二维码中显示 settingsUri，因为 OAuth 流程的最后一步将自动重定向到此位置。

如需了解完整详情，请参阅我们提供的更详细说明。您还可以查看我们的示例应用中的代码，了解如何使用 state 参数作为 OAuth 的一部分，为具有 Ambient API 的输入受限设备授予访问权限。

有关简化身份验证流程的详细信息

如需全面了解 Ambient API 的简化 OAuth 流程，建议您同时了解适用于电视和输入受限的设备应用的 OAuth 2.0 流程以及标准 Ambient API 流程。以下是每种流程的步骤。

适用于电视和输入受限的设备应用的 OAuth 2.0：

  1. 您的应用会向 Google 的授权服务器发送请求，该服务器会识别您的应用将请求访问的范围。
  2. 服务器会响应并提供一些信息，以供后续步骤使用，例如设备代码和用户代码。
  3. 您可以显示用户可以在其他设备上输入的信息，以便授权您的应用。
  4. 您的应用会开始轮询 Google 的授权服务器，以确定用户是否已授权您的应用。
  5. 用户切换到输入功能更丰富的设备，启动网络浏览器，前往第 3 步中显示的网址，然后输入第 3 步中显示的代码。然后，用户可以授予（或拒绝）对应用的访问权限。
  6. 对轮询请求的下一个响应包含您的应用需要用来代表用户授权请求的令牌。（如果用户拒绝了对您应用的访问权限，则响应中不会包含令牌。）

Ambient API 流程：

  1. 检查是否存在现有 OAuth 令牌，然后刷新令牌或请求新的令牌。
  2. 获取 OAuth 令牌后，创建一个新设备。
  3. 向用户显示 settingsUri，并开始轮询设备，直到 mediaSourcesSet 返回 true。
  4. 用户进入 settingsUri，然后选择要与您的应用分享的照片。
  5. mediaSourcesSet 返回 true 后，检索 mediaItems 列表。
  6. 现在，您可以开始幻灯片或其他氛围体验了。

这两种流程都包含一个步骤，即您向用户显示网址，用户在更丰富的输入设备上导航到该网址。通过在初始 OAuth 调用中添加 state 参数，您可以避免显示第二个网址。

之所以能这样，是因为适用于电视和限输入设备应用的 OAuth 2.0 流程的最后一步通常会将用户重定向到显示“您现在可以返回设备”的页面。通过添加 state 参数，流程的最后一步现在会尝试将您重定向到 settingsUri。您的应用仍会接收 OAuth 令牌。您应使用此令牌使用相同的 requestId 调用 createDevice。创建具有相同 ID 的设备后，初始 OAuth 流程将成功将用户重定向到 Google 相册应用中富媒体设备上的正确页面。

请注意以下几点：

  • 不过，最好还是显示 settingsUri，以防身份验证出现任何问题。
  • 您仍然可以在其他情况下使用 settingsUri，例如当用户想要更新其选择的照片时。