---
title: 為 OpenConnector 建立 Google OAuth app
description: 為
  Gmail、Drive、Calendar、Sheets、Docs、Slides、YouTube、Analytics、BigQuery 等 OOMOL
  OpenConnector Google provider 建立 OAuth credentials。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/openconnector-google-oauth-app/
markdown_url: https://oomol.com/zh-tw/docs/openconnector-google-oauth-app.md
---

# 為 OpenConnector 建立 Google OAuth app

自架 OOMOL OpenConnector 需要連接使用者的 Google 帳號時，請使用 Google OAuth app。一個 Google Cloud project 可以保存 Gmail、Google Drive、Google Calendar、Google Sheets、Google Docs、Google Slides、YouTube、Google Analytics、Google BigQuery 等 provider 使用的 OAuth client。

## OpenConnector services

| Service ID | Provider |
| --- | --- |
| `gmail` | Gmail |
| `googledrive` | Google Drive |
| `googlecalendar` | Google Calendar |
| `googlesheets` | Google Sheets |
| `googledocs` | Google Docs |
| `googleslides` | Google Slides |
| `youtube` | YouTube |
| `google_analytics` | Google Analytics |
| `google_bigquery` | Google BigQuery |

每個 service 在 OpenConnector 中會個別保存 OAuth client config。如果同一個 Google OAuth client 已允許相同的 redirect URI，且已啟用所需的 API 和 scopes，你可以把同一組 client ID / client secret 儲存給多個 Google service。

## 前置條件

- 一個正在運作的 OpenConnector runtime。
- 可以存取 Google Cloud project 的 Google 帳號。
- 有權限設定 OAuth consent、啟用 APIs、建立 OAuth credentials。
- 使用者在瀏覽器中開啟的 OpenConnector origin，例如 `http://localhost:3000` 或 `https://connect.example.com`。

## 第 1 步：確定 OpenConnector callback URL

本機測試時使用：

```text
http://localhost:3000/oauth/callback
```

公開 runtime 請先設定 `OOMOL_CONNECT_ORIGIN`，重新啟動後使用：

```text
https://connect.example.com/oauth/callback
```

## 第 2 步：準備 Google Cloud project

在 [Google Cloud Console](https://console.cloud.google.com/) 中：

1. 建立或選擇一個 project。
2. 開啟 **APIs & Services**。
3. 啟用 OpenConnector service 需要的 API，例如 Gmail API、Google Drive API、Google Calendar API、Google Sheets API、YouTube Data API、Google Analytics Data API 或 BigQuery API。
4. 開啟 **OAuth consent screen**，依 Google 要求設定 app name、support email、audience、contact information 和 test users。
5. 新增 OpenConnector service 需要的 scopes，或在啟動 OAuth 授權時由 Google 顯示這些 scopes。

敏感或受限 scopes 在廣泛正式使用前可能需要 Google verification。本機使用或內部測試時，請依你的 Google 帳號類型使用 testing 或 internal 狀態。

## 第 3 步：建立 OAuth credentials

在 **APIs & Services > Credentials** 中：

1. 選擇 **Create credentials**。
2. 選擇 **OAuth client ID**。
3. Application type 選擇 **Web application**。
4. 在 authorized redirect URIs 中新增 OpenConnector 的正確 callback URL。
5. 建立 client。
6. 複製 client ID 和 client secret。

Google 官方文件請見 [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server)。

## 第 4 步：在 OpenConnector 中儲存 client

建議優先在 OpenConnector Web 控制台設定目標 service：

1. 開啟 OpenConnector Web 控制台，例如 `http://localhost:3000`。
2. 開啟 **Providers**，選擇 **Gmail** 或其他 Google provider。
3. 點擊 **Configure OAuth Client** 或 **Edit OAuth Client**。
4. 貼上 Google client ID 和 client secret。
5. 點擊 **Save OAuth Client**。

如果要把同一個 Google OAuth client 用到其他 Google provider，請在對應的 Google provider 頁面重複這些步驟。

## 第 5 步：連接並測試

儲存 OAuth client 後，在 Google provider 頁面點擊 **Connect**。完成 Google consent，回到 OpenConnector，並確認 provider 頁面顯示帳號已連接。

Gmail 可用 `gmail.get_profile` 或 `gmail.list_labels` 做低風險測試。執行 action 前，請先在控制台 action 詳情中確認正確輸入。

## 疑難排解建議

| 現象 | 檢查項目 |
| --- | --- |
| `redirect_uri_mismatch` | Google 收到的 URI 必須和 OAuth client 中的 authorized redirect URI 完全一致。確認它是 `<openconnector-origin>/oauth/callback`。 |
| Google 顯示 app 未驗證 | 使用允許的 test users 測試，能使用 internal mode 時請使用 internal mode；廣泛使用前完成 Google verification。 |
| Google 沒有發出 refresh token | 重新連接帳號。需要 refresh token 的 OpenConnector Google provider 會在定義中請求 offline access 和 consent。 |
| Google action 提示權限不足 | 在 Google Cloud 啟用所需 API，新增或核准所需 scope，然後重新連接帳號。 |
| 執行時用了錯誤的 Google 帳號 | 使用已登入目標 Google 帳號的瀏覽器 profile 重新連接。 |

請把 Google client secret 放在密鑰管理系統中，並在 OpenConnector 中儲存 OAuth client 前設定 `OOMOL_CONNECT_ENCRYPTION_KEY`。