Java 快速入門導覽課程

本快速入門指南說明如何設定簡單的 Java 指令列應用程式,向 YouTube Data API 提出要求。本快速入門導覽課程實際上會說明如何發出兩項 API 要求:

  1. 您將使用 API 金鑰 (用於識別應用程式),擷取 GoogleDevelopers YouTube 頻道資訊。
  2. 您將使用 OAuth 2.0 用戶端 ID 提交「已授權」要求,以擷取自家 YouTube 頻道的相關資訊。

必要條件

如要執行這項快速入門導覽課程,您需要:

  • Java 1.7 以上版本。
  • Gradle 2.3 以上版本
  • 可連上網際網路並具備網路瀏覽器。
  • Google 帳戶。

步驟 1:設定專案和憑證

API 控制台中建立或選取專案。在專案的 API 控制台中完成下列工作:

  1. 程式庫面板中,搜尋 YouTube Data API v3。點選該 API 的清單,確認專案已啟用該 API。

  2. 憑證面板中,建立兩項憑證:

    1. 建立 API 金鑰:您將使用 API 金鑰發出不需要使用者授權的 API 要求。舉例來說,如要擷取公開 YouTube 頻道的資訊,不需要使用者授權。

    2. 建立 OAuth 2.0 用戶端 ID 將應用程式類型設為「其他」。對於需要使用者授權的要求,您必須使用 OAuth 2.0 憑證。舉例來說,您需要使用者授權,才能擷取目前已驗證使用者 YouTube 頻道的相關資訊。

      下載包含 OAuth 2.0 憑證的 JSON 檔案。檔案名稱類似於 client_secret_CLIENTID.json,其中 CLIENTID 是專案的用戶端 ID。

步驟 2:準備專案

請完成下列步驟,準備 Gradle 專案:

  1. 在工作目錄中執行下列指令,建立新的專案結構:

    $ gradle init --type basic $ mkdir -p src/main/java src/main/resources 
  2. 將建立 OAuth 2.0 用戶端 ID 後下載的 JSON 檔案,移至工作目錄下方的 src/main/resources 目錄,並將檔案重新命名為 client_secret.json

  3. 開啟工作目錄中的 build.gradle 檔案,並將內容替換為下列內容:

    apply plugin: 'java' apply plugin: 'application'  mainClassName = 'ApiExample' sourceCompatibility = 1.7 targetCompatibility = 1.7 version = '1.0'  repositories {     mavenCentral() }  dependencies {     compile 'com.google.api-client:google-api-client:1.23.0'     compile 'com.google.oauth-client:google-oauth-client-jetty:1.23.0'     compile 'com.google.apis:google-api-services-youtube:v3-revREVISION-CL_VERSION' }
  4. build.gradle 檔案中,您需要將 REVISIONCL_VERSION 變數替換為 YouTube Data API 用戶端程式庫文件中的兩個值。下方的 YouTube 數據分析 API 說明文件螢幕截圖,顯示了這兩個變數在頁面上的位置。

    JavaDoc 參照的螢幕截圖,顯示如何找出「REVISION」和「CL_VERSION」變數的值

步驟 3:設定及執行範例

使用側邊面板中的 APIs Explorer 小工具,取得用於擷取 GoogleDevelopers YouTube 頻道相關資訊的程式碼範例。這項要求會使用 API 金鑰識別您的應用程式,不需要使用者授權,也不需要執行範例的使用者提供任何特殊權限。

  1. 開啟 API 的 channels.list 方法說明文件。
  2. 該頁面的「常見用途」部分包含一個表格,說明這個方法常見的幾種用途。表格中的第一個項目是依頻道 ID 列出的結果。

    按一下第一個項目的程式碼符號,開啟並填入全螢幕的 API Explorer。

    圖片:指出頻道用途清單表格中程式碼符號連結的位置。該圖片的替代文字會將圖片識別為程式碼符號,並指定與該連結相關聯的使用案例。

  3. 全螢幕 API Explorer 的左側會顯示下列內容:

    1. 「要求參數」標頭下方會列出方法支援的參數。請設定 partid 參數值。id 參數值 UC_x5XG1OV2P6uZZ5FSM9Ttw 是 GoogleDevelopers YouTube 頻道的 ID。

    2. 參數下方有一個名為「憑證」的部分。該專區的下拉式選單應會顯示「API 金鑰」值。API 探索工具預設會使用示範憑證,方便您輕鬆上手。但您會使用自己的 API 金鑰在本機執行範例。

      圖片:全螢幕 API 探索工具中的「憑證」,以及下拉式選單已選取「API 金鑰」選項。

  4. 全螢幕 API Explorer 的右側會顯示分頁,內含不同語言的程式碼範例。選取「Java」分頁標籤。

  5. 複製程式碼範例,並儲存至名為 src/main/java/ApiExample.java 的檔案。每個範例都使用相同的類別名稱 (ApiExample),因此您不需要修改 build.gradle 檔案,就能執行不同的範例。

  6. 在下載的範例中,找出 YOUR_API_KEY 字串,並替換為您在本快速入門導覽課程步驟 1 中建立的 API 金鑰。

  7. 透過指令列執行範例。在工作目錄中執行下列指令:

    gradle -q run

  8. 範例應會執行要求,並將回應列印至 STDOUT

步驟 4:執行授權要求

在這個步驟中,您將修改程式碼範例,讓系統擷取您的 YouTube 頻道資訊,而非 GoogleDevelopers YouTube 頻道資訊。這項要求需要使用者授權。

  1. 返回 API 的 channels.list 方法說明文件。

  2. 在「常見用途」部分,按一下表格中第三個項目的程式碼符號。這個用途是為「我的頻道」呼叫 list 方法。

  3. 同樣地,在全螢幕 API Explorer 的左側,您會看到參數清單,後面接著「憑證」部分。不過,與您擷取 GoogleDevelopers 頻道資訊的範例相比,有兩項變更:

    1. 在參數部分,mine 參數值應設為 true,而非設定 id 參數值。這會指示 API 伺服器擷取目前已驗證使用者頻道的相關資訊。

    2. 在「憑證」部分,下拉式選單應選取「Google OAuth 2.0」選項。

      此外,如果點選「顯示範圍」連結,應會看到 https://www.googleapis.com/auth/youtube.readonly 範圍已勾選。

      圖片:顯示全螢幕 APIs Explorer 中的範圍,以及選取使用「Google OAuth 2.0」憑證的選項。

  4. 如同上一個範例,選取「Java」分頁,複製程式碼範例,然後儲存至 src/main/java/ApiExample.java

  5. 透過指令列執行範例。在工作目錄中執行下列指令:

    gradle -q run

  6. 範例應會嘗試在預設瀏覽器中開啟新視窗或分頁。如果失敗,請從終端機複製網址,然後在瀏覽器中手動開啟。

    如果尚未登入 Google 帳戶,系統會提示你登入。如果您登入了多個 Google 帳戶,系統會要求您選取一個帳戶進行授權。

  7. 按一下按鈕,授予應用程式存取權,存取程式碼範例中指定的範圍。

  8. 範例會自動繼續,您也可以關閉用於驗證流程的瀏覽器分頁。

    API 回應應再次列印至 STDOUT

延伸閱讀