舊版套裝組合服務的 Users API

區域 ID

REGION_ID 是 Google 根據您在建立應用程式時選取的地區所指派的縮寫代碼。此代碼不對應至國家/地區或省份，即使部分區域 ID 可能與常用的國家/地區和省份代碼相似。如果是 2020 年 2 月後建立的應用程式，App Engine 網址會包含 REGION_ID.r。如果是這段時間前建立的現有應用程式，網址可選擇是否包含地區 ID。

進一步瞭解區域 ID。

Users API 允許應用程式：

偵測目前的使用者是否已登入。
將使用者重新導向至適當的登入頁面以進行登入。
如果應用程式使用者尚未擁有 Google 帳戶，則要求使用者建立新帳戶。

使用者登入應用程式後，應用程式即可存取該使用者的電子郵件地址和專屬使用者 ID。而且也可以偵測目前的使用者是否為管理員 (也稱為「管理員使用者」)，方便您實作應用程式的管理員專屬區域。如要查看 user 套件的內容，請參閱user 套件參考資料。

使用者驗證

下列範例是以個人化訊息來歡迎登入應用程式的使用者，並為其提供一個登出連結。如果使用者未登入，應用程式會提供「Google 帳戶」登入頁面的連結。

package users

import (
    "fmt"
    "net/http"

    "google.golang.org/appengine/v2"
    "google.golang.org/appengine/v2/user"
)

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := appengine.NewContext(r)
    u := user.Current(ctx)
    if u == nil {
        url, _ := user.LoginURL(ctx, "/")
        fmt.Fprintf(w, `<a href="%s">Sign in or register</a>`, url)
        return
    }
    url, _ := user.LogoutURL(ctx, "/")
    fmt.Fprintf(w, `Welcome, %s! (<a href="%s">sign out</a>)`, u, url)
}

使用 app.yaml 強制要求登入和管理員權限

如果使用者必須先登入帳戶才能瀏覽某些頁面，您可以在 app.yaml 檔案中強制套用登入設定。

處理常式的設定也可要求使用者必須是應用程式的已註冊管理員，也就是使用者必須擁有檢視者、編輯者、擁有者或 App Engine 管理員角色。這樣一來，由於不需要另外實作授權機制，建構網站的管理員專屬區域變得很容易。

如要瞭解如何設定網址的驗證，請參閱 app.yaml 參考資料中如何要求登入或管理員狀態的相關說明。

Go 中的 OAuth

除了標準的使用者驗證模式外，您的應用程式也可以透過 OAuth 識別使用者。OAuth 是一種通訊協定，可讓使用者授予第三方有限的權限，以代表他們存取網路應用程式，而不必與第三方共用憑證 (使用者名稱與密碼)。關於 OAuth API 的更多資訊 (包括用戶端所需的互動)，請參閱 OAuth 說明文件。

請注意，使用 OAuth 識別使用者與標準的使用者驗證模式完全沒有關聯。舉例來說，如果使用者僅透過 OAuth 驗證，標有 login: required 或 login: admin 的頁面將拒絕載入。

以下是在 Go 要求處理常式中存取 OAuth 使用者資訊的簡單範例：

package users

import (
    "fmt"
    "net/http"

    "google.golang.org/appengine/v2"
    "google.golang.org/appengine/v2/user"
)

func oauthHandler(w http.ResponseWriter, r *http.Request) {
    ctx := appengine.NewContext(r)
    u, err := user.CurrentOAuth(ctx, "")
    if err != nil {
        http.Error(w, "OAuth Authorization Required", http.StatusUnauthorized)
        return
    }
    if !u.Admin {
        http.Error(w, "Admin Authorization Required", http.StatusUnauthorized)
        return
    }
    fmt.Fprintf(w, `Welcome, %s!`, u)
}

驗證選項

您的應用程式可以使用以下其中一個選項來驗證使用者：

Google 帳戶
Google Workspace 網域上的帳戶

選擇驗證的選項

您建立應用程式之後，可選擇要使用的驗證選項。根據預設，您的應用程式將使用「Google 帳戶」來驗證。如要選擇其他選項 (例如 Google Workspace 網域)，請前往 Google Cloud 控制台中專案的「Settings」(設定) 頁面，然後按一下「Edit」(編輯)。在「Google authentication」(Google 驗證) 下拉式選單中，選取所需的驗證類型，然後按一下「Save」(儲存)。

登入和登出

應用程式可以偵測使用者是否透過應用程式所選擇的驗證選項登入應用程式。如果使用者未登入，應用程式會將使用者導向到「Google 帳戶」以便登入，或建立新的「Google 帳戶」。應用程式會呼叫 Users API 的方法，取得登入頁面的網址。使用者造訪需要驗證的頁面時，應用程式能將此網址顯示為連結，或發出對於網址的 HTTP 重新導向。

如果應用程式使用 Google 帳戶或 Google Workspace 進行驗證，使用者登入應用程式時，登入頁面會顯示應用程式名稱。顯示的名稱是您在註冊應用程式時指定的應用程式名稱。您可以在 Google Cloud 控制台「憑證」頁面的「應用程式名稱」欄位中變更這個名稱。

使用者一旦登入或建立 Google 帳戶之後，就會重新導向回到您的應用程式。應用程式將提供重新導向網址，以連結可產生登入網址的方法。

Users API 也提供方法，可產生用來登出應用程式的網址。登出網址會從應用程式取消使用者驗證，然後重新導向回到應用程式的網址，而不顯示任何內容。

在應用程式提示要登入應用程式，且使用者輸入其帳戶的電子郵件地址和密碼後，使用者才能登入應用程式。就算使用者已經使用其「Google 帳戶」登入其他應用程式也是如此。

存取帳戶資訊

如果使用者已登入應用程式，應用程式可針對使用者向應用程式提出的每一項要求，存取帳戶的電子郵件地址。應用程式也能存取可識別使用者的唯一使用者 ID，就算使用者變更了其帳戶的電子郵件地址也是如此。

應用程式還能偵測目前的使用者是否為管理員。使用者是擁有檢視者、編輯者、擁有者或 App Engine 管理員角色的任何使用者。即使您不驗證其他使用者，也可以使用這項功能建構應用程式的管理功能。Go、Java、PHP 和 Python API 都能將網址輕易設定為「管理員專屬」。

Google 帳戶和開發伺服器

開發伺服器使用虛擬登入畫面模擬「Google 帳戶」系統。當應用程式呼叫 Users API 以取得登入畫面的網址時，API 將傳回特殊的開發伺服器網址，提示使用者輸入電子郵件地址，但不用輸入密碼。您可以在提示下輸入任何電子郵件地址，應用程式的行為會如同您已經以該地址帳戶登入一樣。

虛擬登入畫面中也有核取方塊，顯示虛擬帳戶是否為管理員；也就是該帳戶是否擁有檢視者、編輯者、擁有者或 App Engine 管理員角色。若勾選此核取方塊，應用程式的行為會如同您已使用管理員帳戶登入一樣。

同樣的，Users API 會傳回登出網址，以取消虛擬登入。