GoogleデータへのアクセスのためのシンプルなコマンドラインスクリプトにおけるOAuthの利用

認証のアウトラインフロー

私が機能させた方法は、Googleがモバイルおよびデスクトップアプリ向けのOAuth 2.0と呼んでいるものに基づいていますが、手動で介入したり、ブラウザを使用したりすることなく（ほとんど）実行できるように適応する必要がありました。

これがどのように機能するかを説明するために、YouTubeリストを取得するための簡単なリクエストから始めます。スクリプトがGoogleデータを取得するためのリクエストを行うときはいつでも、リクエストにアクセストークンを含める必要があります。Googleのドキュメントでは、このようなHTTPリクエストが示されています。

GET /plus/v1/people/me HTTP/1.1
Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg
Host: googleapis.com

アクセストークンは、ランダムに見える文字の束です。これは短時間（約1時間）有効です。アクセストークンはスクリプトが作業を行うために必要なものですが、それは単に質問につながります。そもそもアクセストークンをどのように取得するのですか？

アクセストークンを取得する1つの方法は、別の種類のトークンである更新トークンを持つことです。アクセストークンとは異なり、更新トークンは長時間有効です。それらは取り消された場合、後の更新トークンによって置き換えられた場合、またはGoogleが激怒した場合にのみ期限切れになります。私は数年間、Googleアナリティクスにアクセスするために同じものを使用しています。私たちのスクリプトの目的のために、更新トークンはまさに仕事です。更新トークンを取得したら、スクリプトが手動で介入せずにアクセスできる安全な場所に保存できます。スクリプトを実行するときに更新トークンにアクセスし、最初のステップとして更新トークンを使用して真新しいアクセストークンを取得できます。その後、スクリプトの実行の残りの部分でアクセストークンを使用します（スクリプトがアクセストークンの有効時間よりも長く実行されない限り—そしてRubyでさえそれほど遅くはありません）。

更新トークンの取得方法を説明する前に、それらに関するもう1つのことがあります。各更新トークン（およびそれらが取得するアクセストークン）には、制限された認可スコープがあります。つまり、アクセスを許可するデータを指定します。YouTubeデータの読み取りのみに有効な更新トークンを作成できます。悪人がこのトークンを取得した場合、私のカレンダーデータを読み取ったり、YouTubeデータを変更したりすることはできません。さまざまなスコープを持つ異なるトークンを持つことは、各トークンで何を行うかを制限するのに役立ち、より安全になり（トークンを安全に保存する方法について心配するのも少なくなります）。

更新トークンを取得するには、ブラウザを使用してGoogleにログインし、自分として認証する必要があります。ほとんどの人と同様に、ラップトップでGoogleに常時ログインしているブラウザインスタンスを持っているため、これは問題ではありません。私が行うのは、私が望む認可スコープを指定するように構築されたGoogle URLにアクセスすることです。Googleアカウントにログインした状態でそれを行うと、Googleはワンタイム認証コードを返します。次に、そのコードを使用して別のURLにアクセスすると、Googleは必要な更新トークンを渡します。これは手動のステップですが、めったにこれを行う必要がないため、それで問題ありません。

これらすべてを行う前に、さらに1つのことを行う必要があります。つまり、APIを使用し、APIアクセスが到達するアプリケーションへのアクセスを許可するようにGoogleを設定することです。これも手動のタスクですが、（Googleが本当に激怒しない限り）一度だけ行う必要があります。

それでは、私が実行する必要がある手順を示します。

• APIアクセスのためのGoogleの設定—ログインしたブラウザを使用した1回限りの手動アクション
• ワンタイム認証コードの取得—ログインしたブラウザが必要、めったに行われない
• 認証コードを更新トークンと交換する—API、めったに行われない
• 更新トークンを使用して新しいアクセストークンを取得する—APIのみ、スクリプトを実行するたびに1回実行される
• Googleを呼び出す際にアクセストークンを使用する—APIのみ、Google APIを呼び出すたびに実行される

Googleの設定

GoogleアカウントでAPIを使用するには、Googleにアクセスして設定する必要があります。必要な場所はGoogle Cloud Consoleです。コンソールに既にプロジェクトが定義されていましたが、まだ持っていない場合はそれを行う必要があります。

最初に必要なことは、YouTubeデータAPIを有効にすることです。「APIとサービスを有効にする」という上部のリンクをクリックします。

そのリンクをクリックすると、追加して有効にするAPIを検索できます。

次に、資格情報を整理する必要があります。これには、「資格情報」タブ（左側）をクリックします。まだ資格情報を持っていない場合は、「資格情報の作成」ボタンを使用して作成します。クライアントの種類を選択できます。ここでは「その他」を選択します。次に、クライアントIDとクライアントシークレットが表示されます。その資格情報の鉛筆アイコンをクリックすることで、後でこの情報にアクセスできます。これらの情報は後でコードで使用します。

最後に、適切なAPIスコープをプロジェクトに追加します。これには、上部の「OAuth同意画面」というリンクをクリックします。「Google APIのスコープ」セクションまでスクロールし、「スコープの追加」ボタンをクリックして../auth/youtube.readonlyスコープを追加します。

ワンタイム認証コードの取得

ワンタイム認証コードを取得するには、Googleにログインした状態で、特別に作成されたGoogle URLにアクセスする必要があります。次に、Googleは認証コードを返します。Googleのドキュメントと、私が遭遇したさまざまなサンプルでは、Webアプリを介してこれを行うことが説明されています。通常のWebアプリケーションフローの中で、Webアプリケーションは認証が必要であることを認識し、ユーザーをGoogleに送信します。

Googleは認証コードをウェブアプリに直接返すことができます。必要なのは、ローカルマシンでサーバーを実行し、そのURL（例：localhost:1234）をGoogleに伝えるだけです。その後、GoogleはそのURLにGETリクエストを送信し、認証コードをURLのパラメータとして含めます。コードはそのパラメータを簡単に取得できます。このポートでこのリクエストを受け取るためのウェブサーバーはそれほど複雑なものではありません。この1つのリクエストに応答できれば十分です。このレベルのシンプルなサーバーでは、Sinatra（Rubyの軽量ウェブサーバーフレームワーク）も必要ありません。何年も前にPrag Daveと一緒にRubyの入門クラスで、数分でシンプルなウェブサーバーを作成したことを覚えています。しかし、私はそれをするのが面倒でした。

代わりに、プログラムに必要なGoogleのURLを作成し、そのURLをコンソールに出力しました。そして、それをブラウザにコピー＆ペーストします。Googleは（私が何をしているかを確認するためのちょっとした処理の後）、ウェブページに認証コードを表示します。その後、このコードをスクリプトにコピー＆ペーストします。自動化されたメカニズムほどスムーズではありませんが、めったに実行しないので問題ありません。

コードを見てみましょう。私は、些細ではないコマンドラインスクリプトを複数のクラスに分割し、コマンドラインのやり取りを処理するクラスと、バックグラウンドで作業を行う「エンジン」クラスを分離します。これは基本的にSeparated Presentationの活用です。コマンドラインとコアコードを個別に作業する方が簡単だと感じるからです。このケースではほとんど価値がありませんが、これは役に立つ習慣だと考えています。

資格情報を操作するために、Google資格情報クラスを作成します。

class GoogleCredentials…

  def initialize(application_name: nil, refresh_key: , scopes: nil,
      client_secret: nil, client_id: nil)
    @application_name = application_name
    @refresh_key = refresh_key
    @scopes = scopes
    @client_secret = client_secret
    @client_id = client_id
  end

必要なデータすべてを入力して、ファクトリメソッドで資格情報オブジェクトを作成できます。

class GoogleCredentials…

  def self.for_youtube
    return self.new(
      application_name: 'Youtube Analytics',
      refresh_key: 'yt-analyze',
      scopes: ['https://www.googleapis.com/auth/youtube.readonly'],
      client_id: '12434.apps.googleusercontent.com',
      client_secret: '1234secretstring'
      )
  end

名前にもかかわらず、client_secretはこのコンテキストではそれほど秘密ではなく、むしろユーザーIDのようなものです。

このデータのほとんどはGoogleとのやり取りに必要なものです。例外はrefresh_keyで、これは取得したリフレッシュトークンを保存するために使用するキーです。

認証コードを取得するには、それにアクセスするためのGoogle URLを作成する必要があります。これはauthorization_urlメソッドで行います。

class GoogleCredentials…

  def authorization_url 
    params = {
      scope: @scopes.join(" "),
      redirect_uri: 'urn:ietf:wg:oauth:2.0:oob',
      response_type: 'code',
      client_id: @client_id
    }
    url = {
      host: 'accounts.google.com',
      path: '/o/oauth2/v2/auth',
      query: URI.encode_www_form(params)
    }

    return URI::HTTPS.build(url)
  end

コマンドラインの処理にはThorライブラリ[2]を使用します。

class CLI…

  class CLI < Thor
    include Thor::Actions

    def initialize *args
      super(*args)
      @engine = GoogleCredentials.for_youtube
    end
    
    desc "url", "display the google auth url to hit in the browser"
    def url
      puts @engine.authorization_url
    end      

これで、コマンドラインでruby cli.rb urlを実行すると、次のようなURLがコードによって出力されます。

https://#/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/youtube.readonly&
  redirect_uri=urn:ietf:wg:oauth:2.0:oob&
  response_type=code&
  client_id=12434.apps.googleusercontent.com

読みやすくするために、改行と空白を追加し、URLエスケープをデコードしました。また、client_idは架空のものです。

URLのパラメータは次のとおりです。

• scope: アクセスするAPIの範囲。この場合は、YouTube Data APIへの読み取り専用アクセスを希望します。
• redirect_uri: ウェブアプリで通常どおりこれを使用する場合、Googleはブラウザを別のURL（通常はlocalhostのポート）にリダイレクトし、そこにレスポンスを配置します。この値を使用することで、Googleにブラウザに表示させてコピー＆ペーストすることを指示します。
• response_type: 一時的な認証コードを返してほしいです。
• client_id: これは、Google Developers Consoleとの以前のやり取りで取得します。

そのURLをブラウザに貼り付けると（最終的に）、Googleから輝く認証コードを表示するウェブページが表示されます。

認証コードを更新トークンと交換する

認証コードを取得したので、2番目の操作を開始して、リフレッシュトークンを取得できます。これには、Googleの認証リソースに再度アクセスし、今回取得した認証コードを提供し、それをclient_secret（Google APIに対して私を識別するコード）と組み合わせます。このステップでは、Googleにログインする必要も、ブラウザを使用する必要もありません。

この時点で、別の問題に直面しなければなりません。リフレッシュトークンはどこに保存するべきでしょうか？これは私だけが使用するスクリプトなので、次のような形でソースコードに保存できます。

def refresh_token
  '1234567890WOxNS_gTztCGW3OBTKcSoKfLXDPc5TA7xz4MEudVrK5jSpoR30zcRFq6'
end

しかし、コードを広くコピーされ、他の人と共有されることが多いリポジトリにコードを保存したいので、これは好きではありません。実際、一般的なセキュリティに関するアドバイスとして、**リポジトリコードツリーの中に決して秘密を保存しない**ことが挙げられています。秘密を含むファイルを誤ってコミットするのは非常に簡単であり、一度コミットしてしまうと削除することはほぼ不可能です。私は自然とかなり不注意なので、避けられないミスが永続的な損害を引き起こさないように工夫しようとします。

別のオプションとして、トークンをソースツリー外のファイルにダンプすることです。私のハードドライブは暗号化されているため、これはかなり安全です。特に、保護しているのは私のYouTube視聴習慣の暗い秘密だけだからです。もう少し用心深いのであれば、そのファイルを暗号化することもできますが、そうすると、スクリプトを使用するたびにパスワードを入力したくないため、そのファイルの暗号化キーはどこに保存するかという問題が出てきます。

Macで実行しているので、Macの組み込みキーチェーンを使用することにしました。これはログイン時に自動的に開き、securityコマンドラインアプリケーションを使用してアクセスできます。Ubuntuマシンで実行する必要がある場合は別の方法を考える必要がありますが、必要になったときに対応します。

リフレッシュトークンを取得するには、先に取得したワンタイム認証コードを使用して新しいトークンをリクエストし、リフレッシュトークンを取り出し、キーチェーンに保存する必要があります。（「トークン」と言っているのは、Googleはアクセストークンとリフレッシュトークンの両方を返すためです。）

これらのトークンをリクエストするには、Googleに再度アクセスしますが、今回はGoogle APIのRubyクライアントライブラリを使用するのが最善だと感じています。トークンを取得するためのコードを以下に示します。

class CLI…

  desc "refresh", "put in auth code, save refresh code"
  def refresh
    auth_code = ask "paste in the authorization code"
    @engine.renew_refresh_token auth_code
  end

class GoogleCredentials…

  def renew_refresh_token auth_code
    token = get_new_refresh_token(auth_code)
    puts "new token: #{token}"
    save_refresh_token token
  end

  def get_new_refresh_token auth_code
    client = Signet::OAuth2::Client.new(
      token_credential_uri: 'https://www.googleapis.com/oauth2/v3/token',
      code: auth_code,
      client_id: @client_id,
      client_secret: client_secret,
      redirect_uri: 'urn:ietf:wg:oauth:2.0:oob',
      grant_type: 'authorization_code'
      )
    client.fetch_access_token!
    return client.refresh_token
  end

このコードはまず、必要なデータすべてを使用してSignet OAuth2クライアントオブジェクトをインスタンス化し、アクセストークンのフェッチを指示します。それが完了すると、リフレッシュトークンを要求して保存できます。

トークンをMacのキーチェーンに保存します。

class GoogleCredentials…

  def save_refresh_token arg
    cmd = "security add-generic-password -a '#{@refresh_key}' -s '#{@refresh_key}' -w '#{arg}'"
    system cmd
  end

securityコマンドは、値を保存する際にサービス（-s）とアカウント（-a）の両方を必要とします。キーバリューストアとしてのみ使用したいので、両方に同じ値を使用します。

更新トークンを使用してアクセストークンを取得する

上記の認証ロジックはまれなものです。私は数年に一度しか呼び出さないことを期待しており、実際、過去数年で2回しか実行していません。次に必要になるまでには、ライブラリが変更されていなければいいのですが。新しいスコープにアクセスする必要がある場合は、新しいファクトリメソッドを宣言するだけです。

これで資格情報オブジェクトができたので、それを活用して何か有用なことをするだけです（この場合はプレイリストを出力します）。

リフレッシュトークンを使用するには、リフレッシュトークンを使用してUserRefreshCredentialsを作成し、fetch_access_token!を使用してGoogleと通信し、Google APIを呼び出すために必要なアクセストークンをロードする必要があります。そのためのコードを以下に示します。

class GoogleCredentials…

  def load_user_refresh_credentials
    @credentials = Google::Auth::UserRefreshCredentials.new(
      client_id: @client_id,
      scope: @scopes,
      client_secret: @client_secret,
      refresh_token: refresh_token,
      additional_parameters: { "access_type" => "offline" })
    @credentials.fetch_access_token!
    return @credentials
  end
  def refresh_token
    @refresh_token ||= `security find-generic-password -wa #{@refresh_key}`.chomp
    @refresh_token
  end

Google APIから動画のリストを取得する

この記事を最初に書いたとき、GoogleにアクセスするためのRubyライブラリは特にわかりにくかったです。ランタイムコード生成を使用していたため、どのようなメソッドを呼び出せるかを調べるためにpryを使用する必要がありました。しかし、今ではビルドのステップとしてコード生成を行い、生成されたクラスをファーストクラスアーティファクトとして保存します。これにより、どのようなメソッドがあるかを確認できるようになり、作業がはるかに簡単になります。また、rubydocでオンラインのAPIドキュメントも提供できるようになります。

YouTubeと通信するには、YouTubeサービスを使用する必要があります。認証と認可を処理するために、ユーザーリフレッシュ資格情報を提供するだけです。

auth_client = GoogleCredentials.for_youtube.load_user_refresh_credentials
youtube = Google::Apis::YoutubeV3::YouTubeService.new
youtube.authorization = auth_client

これで、プレイリストのアイテムを一覧表示するメソッドなど、このYouTubeオブジェクトのメソッドを呼び出すことができます。

youtube.list_playlists('snippet', max_results: 50, mine: true)

この呼び出しはListPlaylistResponseオブジェクトを返します。これは単純なデータオブジェクトであり、OOの専門家である私が通常嫌うような貧弱なデータオブジェクトですが、Data Transfer Objectとして機能するため、このコンテキストでは問題ありません。