Java 快速入門導覽課程

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

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

必要條件

如要執行本快速入門導覽課程，您需要：

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

步驟 1：設定專案和憑證

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

  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 檔案中，您需要將 REVISION 和 CL_VERSION 變數，替換為 YouTube Data API 用戶端程式庫文件中的兩個值。下方的螢幕截圖顯示 YouTube Analytics API 的說明文件，以及這兩個變數在頁面上的位置。

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

步驟 3：設定及執行範例

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

  1. 開啟 API 的 channels.list 方法說明文件。

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

    按一下第一個清單的程式碼符號，開啟並填入全螢幕 APIs Explorer。

    這張圖片標示出 channels.list 說明文件用途表格中，程式碼符號連結的位置。該圖片的替代文字會將圖片識別為程式碼符號，並指定與該連結相關聯的用途。

  3. 全螢幕 APIs Explorer 左側會顯示下列內容：

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

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

      這張圖片顯示全螢幕 APIs Explorer 中的「Credentials」，以及已選取「API 金鑰」選項的下拉式選單。

  4. 全螢幕 APIs 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. 在「Common use cases」(常見用途) 部分，按一下表格中第三個項目的程式碼符號。這個用途是呼叫「我的頻道」的 list 方法。

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

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

    2. 在「Credentials」部分，下拉式選單應選取「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。

延伸閱讀