Google APIs

Google APIs 套件 提供數十種 Google 服務，您可以在 Dart 專案中使用。

本頁說明如何透過 Google 驗證，使用與 終端使用者資料互動的 API。

屬於使用者資料 API 的範例包括 Calendar、Gmail、YouTube 以及 Firebase。

若要明確地為 Firebase 加入驗證功能，請參考 使用 FirebaseUI 為 Flutter 應用程式新增使用者驗證流程 教學，以及 在 Flutter 上開始使用 Firebase Authentication 文件。

要使用 Google APIs，請依照下列步驟：

1. 選擇所需的 API
2. 啟用該 API
3. 驗證並取得目前使用者
4. 取得已驗證的 HTTP 用戶端
5. 建立並使用所需的 API 類別

package:googleapis 的文件 將每個 API 視為獨立的 Dart 函式庫&emdash;以 name_version 格式呈現。 可參考 youtube_v3 作為範例。

每個函式庫可能會提供多種型別， 但會有一個結尾為 Api 的「根」類別（root class）。 以 YouTube 為例，根類別是 YouTubeApi。

Api 類別不僅是您需要 實例化的類別（請參考步驟 3），同時也 提供了代表使用該 API 所需權限的 scopes。 舉例來說， YouTubeApi 類別的 常數區段（Constants section） 列出了可用的 scopes。 如果您只需讀取（但不寫入）終端使用者的 YouTube 資料，請以 youtubeReadonlyScope 進行使用者驗證。

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

要使用 Google API，您必須擁有 Google 帳戶以及一個 Google 專案。 您也需要啟用您想要使用的 API。

本範例啟用了 YouTube Data API v3。 詳細資訊請參閱 入門說明。

使用 google_sign_in 套件， 以 Google 身分驗證使用者。 請針對您想支援的每個平台進行登入設定。

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

此套件的功能可透過 GoogleSignIn 類別的靜態實例來存取。 在與該實例互動之前， 必須先呼叫 initialize 方法並等待其完成。

final GoogleSignIn _googleSignIn = GoogleSignIn.instance;
​
@override
void initState() {
  super.initState();
  _googleSignIn.initialize();
  // ···
}

初始化完成後，但在使用者驗證（authentication）之前，請監聽驗證事件，以判斷使用者是否已登入。

GoogleSignInAccount? _currentUser;
​
@override
void initState() {
  super.initState();
  _googleSignIn.initialize().then((_) {
    _googleSignIn.authenticationEvents.listen((event) {
      setState(() {
        _currentUser = switch (event) {
          GoogleSignInAuthenticationEventSignIn() => event.user,
          _ => null,
        };
      });
    });
  });
}

一旦你開始監聽任何相關的驗證事件後，你就可以嘗試對先前已登入的使用者進行驗證。

void initState() {
  super.initState();
  _googleSignIn.initialize().then((_) {
    // ...
    // Attempt to authenticate a previously signed in user.
    _googleSignIn.attemptLightweightAuthentication();
  });
}

若要同時允許新使用者進行驗證，請依照 package:google_sign_in 所提供的指示操作。

當使用者已完成驗證後，您必須取得一個已驗證的 HTTP 用戶端。

當您有已登入的使用者後，請使用 authorizationForScopes 來為您的應用程式所需的 API 權限範圍請求相關的用戶端授權權杖。

const relevantScopes = [YouTubeApi.youtubeReadonlyScope];
final authorization = await currentUser.authorizationClient
    .authorizationForScopes(relevantScopes);

取得相關授權憑證（authorization tokens）後， 請使用 authClient 擴充套件（extension）， 搭配 package:extension_google_sign_in_as_googleapis_auth， 建立一個已套用相關憑證的已驗證 HTTP 用戶端（authenticated HTTP client）。

import 'package:extension_google_sign_in_as_googleapis_auth/extension_google_sign_in_as_googleapis_auth.dart';

final authenticatedClient = authorization!.authClient(
  scopes: relevantScopes,
);

使用 API 來建立所需的 API 類型並呼叫方法。 例如：

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

您可能會想參考以下內容：

• extension_google_sign_in_as_googleapis_auth 範例 是本頁所述概念的實作範例。