由 JavaScript 應用程式傳送已驗證要求

本頁說明如何由本機執行的 JavaScript 應用程式,將已驗證要求傳送至使用 Cloud Endpoints Frameworks 建立的 REST API。JavaScript 應用程式顯示如何在要求之中使用 Google 登入及傳送 Google ID 憑證,以驗證使用者。JavaScript 應用程式傳送要求時,Endpoints Frameworks 會先驗證使用者,然後再將要求傳送至在 App Engine 標準環境執行的後端程式碼。

必備條件

如要執行範例 JavaScript 應用程式,需符合下列條件:

  • 尋找您為範例 API 建立的 Google Cloud Platform (GCP) 專案 ID,因為您需要將其新增至範例 JavaScript 程式碼。如果您找不到專案 ID,請參閱列出專案

  • 您的本機電腦需要網路伺服器,才能提供含有 JavaScript 程式碼的範例 index.html 檔案。本頁包含執行 SimpleHTTPServer (隨附於 Python 2.7) 的步驟,但您可使用任何網路伺服器。

下載範例 JavaScript 用戶端程式碼

  1. 將範例複製到本機電腦:

    git clone https://github.com/GoogleCloudPlatform/web-docs-samples
    
  2. 變更為包含 JavaScript 用戶端的目錄:

    cd web-docs-samples/endpoints-frameworks
    

建立 OAuth 2.0 客戶端 ID

如要設定範例進行驗證,您需要在範例 JavaScript 程式碼及後端程式碼設定 OAuth 2.0 用戶端 ID。JavaScript 應用程式使用用戶端 ID,由 Google OAuth 2.0 伺服器取得 Google ID 憑證,並在要求中傳送 Google ID 憑證。Endpoints Frameworks 則以用戶端 ID 驗證 JavaScript 應用程式在要求中傳送的 ID 憑證。

如要建立用戶端 ID,請執行下列操作:

  1. 在 Google Cloud Platform 主控台中前往「Credentials」(憑證) 頁面。

    前往「Credentials」(憑證) 頁面

  2. 從專案清單中選取您為範例 API 建立的專案。

  3. 按一下 [Create credentials] (建立憑證) 按鈕,然後選取 [OAuth client ID] (OAuth 用戶端 ID)。若這是您第一次在此專案建立用戶端 ID,請使用子步驟在同意畫面設定產品名稱,否則請跳至下一步。

    1. 點選 [Configure consent screen] (設定同意畫面) 按鈕。
    2. 在「Application name」(應用程式名稱) 欄位輸入名稱。
    3. 按一下 [儲存]
  4. 請在「應用程式類型」下方按下 [網路應用程式]

  5. 在「Authorized JavaScript origins」(已授權的 JavaScript 來源) 欄位輸入下列內容:

    http://localhost:8080
    
  6. 按一下 [Create] (建立)。

  7. 複製您的用戶端 ID。完整的用戶端 ID 類似於下列範例,不過對專案中的網路應用程式而言是唯一識別碼。

    271473851874-mtll5dk2vultovbtilt31hakqbinpuvd.apps.googleusercontent.com

如要進一步瞭解如何建立用戶端 ID,請參閱設定 OAuth 2.0

設定後端程式碼及重新部署

為了讓 Cloud Endpoints Frameworks 驗證由 JavaScript 應用程式傳送的要求,您必須將剛剛建立的用戶端 ID 新增至範例程式碼,然後重新部署更新後的 OpenAPI 文件及應用程式後端程式碼。

下列程序假設您已由開始使用 Java 適用的 Endpoints Frameworks 部署範例 API。開始下列程序前,請確保您在傳送要求至 API 時獲得成功回應,如傳送要求至 API 一節所述。

如要設定後端程式碼及重新部署,請執行下列操作:

  1. 在您複製 java-docs-samples 存放區的目錄之中,變更為包含 Java 範例的目錄:

    cd YOUR_WORKING_DIRECTORY/java-docs-samples/appengine-java8/endpoints-v2-backend
    
  2. 在文字編輯器中開啟 src/main/java/com/example/echo/Echo.java 檔案。

  3. getUserEmail 方法的 @ApiMethod 註解中,將 audiencesclientIds 屬性中的 YOUR_OAUTH_CLIENT_ID 替換為您建立的用戶端 ID。

    @ApiMethod(
        httpMethod = ApiMethod.HttpMethod.GET,
        authenticators = {EspAuthenticator.class},
        audiences = {"YOUR_OAUTH_CLIENT_ID"},
        clientIds = {"YOUR_OAUTH_CLIENT_ID"}
    )
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
  4. 儲存 Echo.java 檔案。

  5. 清理專案,然後建構您的 API:

    Maven

    mvn clean package

    Gradle

          gradle clean
          gradle build
  6. 重新產生 OpenAPI 文件 openapi.json,使其包含用戶端 ID。

    Maven

    mvn endpoints-framework:openApiDocs

    Gradle

    gradle endpointsOpenApiDocs
  7. 確認 Cloud SDK (gcloud) 已取得授權,可存取您在 GCP 上的資料與服務:

    gcloud auth login
    
  8. 設定 gcloud 指令列工具的預設專案。將 YOUR_PROJECT_ID 替換成您為範例 API 建立的專案 ID:

    gcloud config set project YOUR_PROJECT_ID
    
  9. 部署更新後的 OpenAPI 文件:

    gcloud endpoints services deploy target/openapi-docs/openapi.json
    
  10. 等待指令完成,然後重新部署您的應用程式:

    Maven

    mvn appengine:deploy

    Gradle

    gradle appengineDeploy

設定 JavaScript 程式碼

如要設定 JavaScript 程式碼,請執行下列操作:

  1. web-docs-samples/endpoints-frameworks 目錄中,以文字編輯器開啟 main.js
  2. initGoogleAuth 函式中,將 YOUR_CLIENT_ID 替換為您剛剛建立的用戶端 ID。

    function initGoogleAuth (clientId = 'YOUR_CLIENT_ID') {
      gapi.auth2.init({
        client_id: clientId,
        scope: 'https://www.googleapis.com/auth/userinfo.email'
      }).then(() => {
        document.getElementById('sign-in-btn').disabled = false;
      }).catch(err => {
        console.log(err);
      });
    }
  3. sendSampleRequest 函式中,將 YOUR_PROJECT_ID 替換成您剛剛為範例 API 建立的專案 ID。

    function sendSampleRequest (projectId = 'YOUR_PROJECT_ID') {
      var user = gapi.auth2.getAuthInstance().currentUser.get();
      var idToken = user.getAuthResponse().id_token;
      var endpoint = `https://${projectId}.appspot.com/_ah/api/echo/v1/email`;
      var xhr = new XMLHttpRequest();
      xhr.open('GET', endpoint + '?access_token=' + encodeURIComponent(idToken));
      xhr.onreadystatechange = function () {
        if (this.readyState === XMLHttpRequest.DONE && this.status === 200) {
          window.alert(xhr.responseText);
        }
      };
      xhr.send();
    }

傳送已驗證要求

  1. 在您複製 web-docs-samples 存放區的目錄之中,變更為包含 JavaScript 範例的目錄:

    cd YOUR_WORKING_DIRECTORY/web-docs-samples/endpoints-frameworks
    
  2. 啟動網路伺服器,在通訊埠 8080 提供 index.html。以下範例使用 Python 2.7 的 SimpleHTTPServer:

    python -m SimpleHTTPServer 8080
    
  3. 在瀏覽器中,輸入 localhost:8080

    JavaScript 應用程式會顯示兩個按鈕。

    登入

  4. 點選 [Sign In] (登入)。隨即顯示「Sign in with Google」(登入 Google 帳戶) 頁面。

  5. 登入後請按一下 [Send sample request] (傳送範例要求) 按鈕。您第一次傳送要求時,可能會因為 App Engine 啟動而延遲約 20 秒鐘。Endpoints Frameworks 會攔截要求,並使用您在後端程式碼設定的用戶端 ID 驗證要求。如果驗證成功:

    1. Endpoints Frameworks 就會將要求傳送至在 App Engine 執行的範例後端。

    2. 在後端程式碼之中,getUserEmail 方法會傳回您登入時使用的使用者帳戶電子郵件地址。

    3. JavaScript 用戶端會顯示對話方塊及電子郵件地址。

JavaScript 用戶端總覽

JavaScript 用戶端使用 Google 登入,管理 OAuth 2.0 流程。本節將簡述 JavaScript 用戶端程式碼總覽。

Auth 設定

  1. 載入 Google API 平台資料庫以建立 gapi 專案:

      <script src="https://apis.google.com/js/platform.js?onload=loadAuthClient" async defer></script>
    </head>
  2. Google API 平台資料庫載入後,請載入 auth2 資料庫:

    function loadAuthClient () {
      gapi.load('auth2', initGoogleAuth);
    }
  3. 初始化 GoogleAuth 物件:

    function initGoogleAuth (clientId = 'YOUR_CLIENT_ID') {
      gapi.auth2.init({
        client_id: clientId,
        scope: 'https://www.googleapis.com/auth/userinfo.email'
      }).then(() => {
        document.getElementById('sign-in-btn').disabled = false;
      }).catch(err => {
        console.log(err);
      });
    }

初始化 GoogleAuth 物件時,請以 OAuth 2.0 用戶端 ID 設定物件,並設定您要指定的其他任何選項。一般來說,您會指定存取範圍。範圍可讓應用程式僅要求存取其需要的資源,也能讓使用者控制對應用程式授予的存取量。開始實作 OAuth 2.0 授權之前,我們建議您找出應用程式需要權限存取的範圍。此範例要求存取 https://www.googleapis.com/auth/userinfo.email 範圍,這個範圍會授予存取權以檢視使用者電子郵件地址。

登入

初始化 GoogleAuth 物件後,您可呼叫 GoogleAuth 物件的 signIn 函式,提示使用者進行登入:

function signIn () {
  gapi.auth2.getAuthInstance().signIn().then(() => {
    document.getElementById('sign-in-btn').hidden = true;
    document.getElementById('sign-out-btn').hidden = false;
    document.getElementById('send-request-btn').disabled = false;
  }).catch(err => {
    console.log(err);
  });
}

以 ID 憑證進行要求

使用者完成登入後,以使用者 ID 憑證傳送含授權標頭的要求:

function sendSampleRequest (projectId = 'YOUR_PROJECT_ID') {
  var user = gapi.auth2.getAuthInstance().currentUser.get();
  var idToken = user.getAuthResponse().id_token;
  var endpoint = `https://${projectId}.appspot.com/_ah/api/echo/v1/email`;
  var xhr = new XMLHttpRequest();
  xhr.open('GET', endpoint + '?access_token=' + encodeURIComponent(idToken));
  xhr.onreadystatechange = function () {
    if (this.readyState === XMLHttpRequest.DONE && this.status === 200) {
      window.alert(xhr.responseText);
    }
  };
  xhr.send();
}

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁