使用 Google API

Google APIs package 提供了许多你可以从 Dart 项目中使用的 Google 服务。

The Google APIs package exposes dozens of Google services that you can use from Dart projects.

本页面描述了如何通过 Google 身份验证,使用这些 API 和终端用户数据交互。

This page describes how to use APIs that interact with end-user data by using Google authentication.

用户数据 API 的例子包括 CalendarGmailYouTube

Examples of user-data APIs include Calendar, Gmail, and YouTube.

概览

Overview

请遵循以下步骤使用 Google API。

To use Google APIs, follow these steps.

  1. 选择所需的 API

    Pick the desired API

  2. 启用 API 服务

    Enable the API

  3. 使用所需的作用域对用户进行身份验证

    Authenticate user with the required scopes

  4. 获取身份验证后的 HTTP 客户端

    Obtain an authenticated HTTP client

  5. 创建并使用所需的 API 类

    Create and use the desired API class

1. 选择所需的 API

1. Pick the desired API

文档 package:googleapis 采用 name.version 的形式,列举了每一个可以单独作为 Dart 库的 API。一起看看 youtube.v3 这个例子。

The documentation for package:googleapis lists each API as a separate Dart library – in a name.version format. Let’s look at youtube.v3 as an example.

每一个库都可以提供多种类型,但是一定会有一个以 Api 结尾的 类。在 YouTube 中,根类就是 YouTubeApi

Each library may provide many types, but there is one root class that ends in Api. For YouTube, it’s YouTubeApi.

Api 类不仅是你需要初始化的类——详见步骤 3 ——它还暴露了使用该 API 所需权限的作用域。请看 YouTubeApi 类中 常量 这一节,你会看到可用的作用域有哪些。为了获取终端用户的 YouTube 数据的读取(并非写入)权限,用户验证时使用 youtubeReadonlyScope

Not only is the Api class the one you need to instantiate – see step 3 – but it also exposes the scopes that represent the permissions needed to use the API. Look under the Constants section of the YouTubeApi class and you’ll see the available scopes. To request access to simply read (but not write) an end-users YouTube data, use the youtubeReadonlyScope when authenticating the user.

/// Provides the `YouTubeApi` class.
import 'package:googleapis/youtube/v3.dart';

2. 启用 API 服务

2. Enable the API

使用 Google API,你必须有一个 Google 账户和一个 Google 项目。你还需要启用所需的 API 服务。

To use Google APIs you must have a Google account and a Google project. You also need to enable your desired API.

在本示例中,你将需要启用 YouTube Data API v3 服务。

In this example, you’d enable YouTube Data API v3.

详情请看 入门指南

For details, see the getting started instructions.

3. 使用所需的作用域对用户进行身份验证

3. Authenticate the user with the required scopes

使用 google_sign_in 包对用户进行 Google 身份验证。你必须为每一种想要支持的平台配置登录。

Use the google_sign_in package to authenticate users with their Google identity. You will have to configure signin for each platform you want to support.

/// Provides the `GoogleSignIn` class
import 'package:google_sign_in/google_sign_in.dart';

当你初始化 GoogleSignIn 类时,你需要提供前面的小节中提到的所需的作用域。

When you instantiate the GoogleSignIn class, you provide the desired scopes as discussed in the previous section.

final _googleSignIn = GoogleSignIn(
  scopes: <String>[YouTubeApi.youtubeReadonlyScope],
);

按照 package:google_sign_in 中的介绍来进行用户验证。

Follow the instructions provided by package:google_sign_in to allow a user to authenticate.

一旦验证完毕,你必须获取一个验证后的 HTTP 客户端。

Once authenticated, you must obtain an authenticated HTTP client.

4. 获取身份验证后的 HTTP 客户端

4. Obtain an authenticated HTTP client

extension_google_sign_in_as_googleapis_auth 包在 GoogleSignIn 中提供了一个 扩展方法authenticatedClient

The extension_google_sign_in_as_googleapis_auth package provides an extension method on GoogleSignIn: authenticatedClient.

import 'package:extension_google_sign_in_as_googleapis_auth/extension_google_sign_in_as_googleapis_auth.dart';

你可以监听 onCurrentUserChanged。当事件值不是 null 时,你可以创建一个身份验证后的客户端。

You can listen to onCurrentUserChanged. When event value is not null, you can create an authenticated client.

var httpClient = (await _googleSignIn.authenticatedClient())!;

Client 实例包含了调用 Google API 类时所需的凭证。

This Client instance includes the nessesary credentials when invoking Google API classes.

5. 创建并使用所需的 API 类

5. Create and use the desired API class

使用 API 来创建所需的 API 类型和调用方法,例如:

Use the API to create the desired API type and call methods, for instance:

var youTubeApi = YouTubeApi(httpClient);

var favorites = await youTubeApi.playlistItems.list(
  ['snippet'],
  playlistId: 'LL', // Liked List
);

更多信息

More information