Python クライアント ライブラリの使用

このチュートリアルでは、Python 用 Google API クライアント ライブラリを使用して、Python アプリケーションから AI Platform Training の REST API を呼び出す方法について説明します。このドキュメントの以降のコード スニペットとサンプルでは、この Python クライアント ライブラリを使用します。

このチュートリアルでは、Google Cloud プロジェクトにモデルを作成します。少量のコード例で記述できるほどのシンプルな作業です。

目標

このチュートリアルは、Python クライアント ライブラリに慣れることを目的として設計された基本的なチュートリアルです。完了すれば、次のことができるようになります。

  • AI Platform Training サービスの Python 表現を取得する。
  • その表現を使用してプロジェクト内でモデルを作成する。これにより、他のモデルやジョブ管理 API を呼び出す方法を理解しやすくなります。

料金

このチュートリアルのオペレーションは課金されません。詳細については、料金ページをご覧ください。

始める前に

GCP プロジェクトの設定

  1. Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

  2. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタに移動

  3. Google Cloud プロジェクトで課金が有効になっていることを確認します。

  4. AI Platform Training & Prediction and Compute Engine API を有効にします。

    API を有効にする

  5. Google Cloud CLI をインストールします。

  6. gcloud CLI を初期化するには:

    gcloud init
    7.

  7. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタに移動

  8. Google Cloud プロジェクトで課金が有効になっていることを確認します。

  9. AI Platform Training & Prediction and Compute Engine API を有効にします。

    API を有効にする

  10. Google Cloud CLI をインストールします。

  11. gcloud CLI を初期化するには:

    gcloud init
    12.

認証の設定

認証を設定するには、サービス アカウント キーを作成し、そのサービス アカウント キーへのファイルパスの環境変数を設定する必要があります。

  1. サービス アカウントを作成します。

    1. Google Cloud コンソールで [サービス アカウントの作成] ページに移動します。

      [サービス アカウントの作成] に移動

    2. [サービス アカウント名] フィールドに名前を入力します。
    3. 省略可: [サービス アカウントの説明] フィールドに説明を入力します。
    4. [作成] をクリックします。
    5. [ロールを選択] フィールドをクリックします。[すべてのロール] で、[AI Platform] > [AI Platform 管理者] の順に選択します。
    6. [別のロールを追加] をクリックします。

    7. [ロールを選択] フィールドをクリックします。[すべてのロール] で、[Cloud Storage] > [ストレージ オブジェクト管理者] を選択します。

    8. [完了] をクリックして、サービス アカウントを作成します。

      ブラウザ ウィンドウは閉じないでください。次のステップでこれを使用します。

  2. 認証に使用するサービス アカウント キーを作成します。

    1. Google Cloud コンソールで、作成したサービス アカウントのメールアドレスをクリックします。
    2. [キー] をクリックします。
    3. [鍵を追加]、[新しい鍵を作成] の順にクリックします。
    4. [作成] をクリックします。JSON キーファイルがパソコンにダウンロードされます。
    5. [閉じる] をクリックします。

  3. 環境変数 GOOGLE_APPLICATION_CREDENTIALS をサービス アカウント キーが格納された JSON ファイルのファイルパスに設定します。この変数は現在の shell セッションにのみ適用されるため、新しいセッションを開く場合は、変数を再度設定します。

Python 開発環境の設定

下記のいずれかの方法で、macOS のローカル環境または Cloud Shell のリモート環境を設定します。

macOS の場合、以下の [MACOS] タブで環境を設定することをおすすめします。[CLOUD SHELL] タブに表示される Cloud Shell は、macOS、Linux、Windows で使用できます。Cloud Shell は、AI Platform Training の機能を試すような場合には便利ですが、継続的な開発作業には適していません。

macOS

  1. Python のインストールを確認する
    Python がインストールされていることを確認します。されていない場合はインストールします。

    python -V

  2. pip のインストールを確認する
    pip は、Python のパッケージ マネージャーであり、Python の現在のバージョンに含まれています。pip --version コマンドを実行して、pip がすでにインストールされているかどうかを確認します。インストールされていない場合は、pip のインストール方法をご覧ください。

    次のコマンドを使用すると、pip をアップグレードできます。

    pip install -U pip

    詳細については、pip のドキュメントをご覧ください。

  3. virtualenv をインストールする
    virtualenv は隔離された Python 環境を作成するツールです。次のコマンドを実行して、virtualenv がすでにインストールされているかどうかを確認します。virtualenv --version。インストールされていない場合は、virtualenv をインストールします。

    pip install --user --upgrade virtualenv

    このガイド用に隔離された開発環境を作成するために、virtualenv で新しい仮想環境を作成します。たとえば、次のコマンドは、aip-env という名前の環境をアクティブにします。

    virtualenv aip-env
source aip-env/bin/activate

  4. このチュートリアルでは、仮想環境内で残りのコマンドを実行します。

    virtualenv の使用方法の詳細をご覧ください。virtualenv を終了するには、deactivate を実行します。

Cloud Shell

  1. Google Cloud Console を開きます。

    Google Cloud Console

  2. Console ウィンドウの上部にある「Cloud Shell をアクティブにする」ボタンをクリックします。

    Google Cloud Shell をアクティブにする

    コンソールの下部の新しいフレーム内で Cloud Shell セッションが開き、コマンドライン プロンプトが表示されます。シェル セッションが初期化されるまで、数秒かかる場合があります。

    Cloud Shell セッション

    Cloud Shell セッションが使用できる状態になります。

  3. 選択したプロジェクトを使用するように gcloud コマンドライン ツールを構成します。 

    gcloud config set project [selected-project-id]

    ここで、[selected-project-id] はプロジェクト ID です（ID を囲んでいる角かっこは不要です）。

Python 用 Google API クライアント ライブラリのインストール

Python 用 Google API クライアント ライブラリをインストールします。

このチュートリアルは、Python クライアント ライブラリに慣れることを目的として設計された基本的なチュートリアルです。完了すれば、次のことができるようになります。

  • AI Platform Training サービスの Python 表現を取得する。
  • その表現を使用してプロジェクト内でモデルを作成する。これにより、他のモデルやジョブ管理 API を呼び出す方法を理解しやすくなります。
このチュートリアルのオペレーションは課金されません。詳細については、料金ページをご覧ください。

必要なモジュールのインポート

Python 用 Google API クライアント ライブラリを使用してコードから AI Platform Training の REST API を呼び出す場合は、そのパッケージと OAuth2 パッケージをインポートする必要があります。このチュートリアル（そして AI Platform Training の標準的用途の大部分）では、以下のモジュールをインポートするだけで済みます。

他の使用可能なモジュールに関しては、それらのパッケージのドキュメントをご覧ください。

お好きなエディタで新しい Python ファイルを作成して、次の行を追加します。

from oauth2client.client import GoogleCredentials
from googleapiclient import discovery
from googleapiclient import errors

API の Python 表現の構築

REST API の Python 表現を取得します。呼び出すメソッドは build です。API クライアント ライブラリは、サービス ディスカバリを使用して、呼び出し時に存在するサービスに動的に接続します。また、サービス ml をカプセル化するオブジェクトを呼び出します。

ml = discovery.build('ml','v1')

パラメータとリクエスト本文の構成

サービスの呼び出しを行うには、REST API に引き渡すパラメータとリクエスト本文を作成する必要があります。呼び出しを表すメソッドに、パラメータを正規の Python パラメータとして渡します。本文は、HTTP リクエストで直接 API を呼び出す場合に使用するのと同様の JSON リソースです。

新しいブラウザタブ projects.models.create でモデルを作成する REST API を見てみましょう。

  • パスパラメータ parent に注意してください。これは、プロジェクトを識別するリクエストの URI の一部です。HTTP POST リクエストを直接作成する場合は、次の URI を使用できます。

    https://ml.googleapis.com/v1/projects/YOUR_PROJECT_ID/models

    API クライアント ライブラリを使用する場合は、URI の変数部は、API 呼び出しの文字列型パラメータとして表現されます。'projects/<var>YOUR_PROJECT_ID</var>' に設定します。API 呼び出しをよりクリーンにするために、プロジェクトを変数に保存します。

    project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

  • リクエスト本文は、モデル情報を表す JSON リソースです。モデルリソース定義では、入力として name と description（省略可能）の 2 つの値を受け入れることがわかります。JSON の代わりに Python 辞書を渡すことができ、API クライアント ライブラリが必要な変換を実行します。

    自分用の Python 辞書を作成します。

    request_dict = {'name': 'your-model-name',
               'description': 'This is a machine learning model entry.'}

リクエストの作成

Python クライアント ライブラリを使用して API の呼び出しを行うには、次の 2 つのステップがあります。最初にリクエストを作成し、次にそのリクエストを使用して呼び出しを行います。

リクエストを作成する

先ほど作成した構築済みクライアント オブジェクト（コード スニペットに正確に従っていれば ml と言う名前になります）を、API 階層のルートとして使用し、必要な API を指定します。API パス内の各コレクションは、その中のコレクションとメソッドのリストを返す関数のような働きをします。たとえば、すべての AI Platform Training API のルートは projects で、呼び出しは ml.projects() から始まります。

次のコードを使用して、リクエストを生成させます。

request = ml.projects().models().create(parent=project_id, body=request_dict)

リクエストを送信する

この前の手順で作成したリクエストは、リクエストをサービスに送信するために呼び出す、execute メソッドを公開します。

response = request.execute()

デベロッパーが、この手順を前の手順と組み合わせることは、通常のことです。

response = ml.projects().models().create(parent=project_id,
                                         body=request_dict).execute()

単純なエラーの処理

インターネット経由で API 呼び出しを行うと、さまざまな問題が発生しがちです。一般的なエラーを処理することは、良い方法です。エラーに対処する最も単純な方法は、リクエストを try ブロックに書き込んで潜在的なエラーをキャッチすることです。サービスから発生するエラーのほとんどは HTTP エラーです。これは、HttpError クラスにカプセル化されます。このエラーをキャッチするには、googleapiclient パッケージの errors モジュールを使用します。

try ブロックで request.execute() 呼び出しをラップします。同様に、print ステートメントをこのブロックに入れ、呼び出しが成功した場合にのみ response の内容の出力を試みるようにします。

try:
    response = request.execute()
    print(response)

キャッチ ブロックを追加して、HTTP エラーを処理させます。HttpError._get_reason() を使用して、response から reason テキスト フィールドを取得できます。

except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

もちろん、単純な print ステートメントは、アプリケーション用の正しいアプローチではない場合があります。

すべてのコードをまとめる

以下は完全な例です。

from googleapiclient import discovery
from googleapiclient import errors

# Store your full project ID in a variable in the format the API needs.
project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

# Build a representation of the Cloud ML API.
ml = discovery.build('ml', 'v1')

# Create a dictionary with the fields from the request body.
request_dict = {'name': 'your_model_name',
               'description': 'your_model_description'}

# Create a request to call projects.models.create.
request = ml.projects().models().create(
              parent=project_id, body=request_dict)

# Make the call.
try:
    response = request.execute()
    print(response)
except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

他のメソッドへの汎化

ここで学習した手順は、他のどんな REST API 呼び出しを行うためにも使用することができます。一部の API は 1 つのモデルの作成よりはるかに複雑な JSON リソースを必要としますが、原則は同じです。

  1. googleapiclient.discovery と googleapiclient.errors をインポートします。

  2. 検出モジュールを使用して、API の Python 表現を構築します。

  3. API 表現を、一連のネスト済みオブジェクトとして使用して必要な API を取得し、リクエストを作成します。たとえば、次のコマンドを実行します。

    request = ml.projects().models().versions().delete(
    name='projects/myproject/models/mymodel/versions/myversion')

  4. request.execute() を呼び出してリクエストを送信し、アプリケーションの例外を適切な方法で処理します。

  5. レスポンスの本文がある場合は、それを Python 辞書のように扱って、API リファレンスに指定された JSON オブジェクトで取得できます。レスポンス内のオブジェクトの多くに、一定の状況のみで存在するフィールドがあるので注意してください。キーエラーを回避するために、常時チェックする必要があります。

    response = request.execute()

some_value = response.get('some_key') or 'default_value'

次のステップ