舊版套裝組合服務的 Users API

區域 ID

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

進一步瞭解區域 ID。

Users API 允許應用程式：

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

使用者登入應用程式後，應用程式即可存取該使用者的電子郵件地址和專屬使用者 ID。而且也可以偵測目前的使用者是否為管理員 (也稱為「管理員使用者」)，方便您實作應用程式的管理員專屬區域。

使用者驗證

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

您可以使用標準 Servlet API 及要求物件的 getUserPrincipal() 方法，測試使用者是否已登入，並取得使用者的電子郵件地址。您可以利用 User Service API 來產生登入和登出網址。


package com.example.appengine.users;

import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;
import java.io.IOException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(
    name = "UserAPI",
    description = "UserAPI: Login / Logout with UserService",
    urlPatterns = "/userapi"
)
public class UsersServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    UserService userService = UserServiceFactory.getUserService();

    String thisUrl = req.getRequestURI();

    resp.setContentType("text/html");
    if (req.getUserPrincipal() != null) {
      resp.getWriter()
          .println(
              "<p>Hello, "
                  + req.getUserPrincipal().getName()
                  + "!  You can <a href=\""
                  + userService.createLogoutURL(thisUrl)
                  + "\">sign out</a>.</p>");
    } else {
      resp.getWriter()
          .println(
              "<p>Please <a href=\"" + userService.createLoginURL(thisUrl) + "\">sign in</a>.</p>");
    }
  }
}

User Service API 可以將目前使用者資訊做為 User 物件傳回。雖然 User 物件可以做為屬性值儲存在資料儲存庫中，但我們強烈建議您避免這麼做，因為這包含電子郵件地址以及使用者的唯一 ID。如果使用者變更了電子郵件地址，但您還是使用先前儲存的 User 來比對新的 User 值，兩者將無法配對。請考慮改用「User 使用者 ID 值」做為該使用者的穩定專屬 ID。

使用 web.xml 強制要求登入和管理員權限

如果使用者必須登入才能存取您的網頁，您可以在部署作業描述元 (web.xml 檔案) 中為這些網頁建立安全限制。如果使用者存取設有安全限制的網址，而且使用者沒有登入，App Engine 會自動將使用者重新導向到登入頁面 (進行「Google 帳戶」或 Google Workspace 驗證)，然後在成功登入或註冊之後，將使用者引導回到網址。

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

如要瞭解如何為網址設定安全限制，請參閱部署作業描述元：安全性和驗證中的 web.xml。

驗證選項

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

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 都能將網址輕易設定為「管理員專屬」。

Users 和資料儲存庫

Users 服務 API 可以將目前使用者資訊做為 User 物件傳回。雖然 User 物件可以做為屬性值儲存在資料儲存庫中，但我們強烈建議您避免這麼做，因為這包含電子郵件地址以及使用者的唯一 ID。如果使用者變更了電子郵件地址，但您還是使用先前儲存的 User 來比對新的 User 值，兩者將無法配對。請考慮改用「使用者 ID 值」User做為該使用者的穩定專屬 ID。

Google 帳戶和開發伺服器

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

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

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