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

---

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

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

目標

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

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

注: このチュートリアルのコードサンプルでは Python 2.7 を使用しています。AI Platform Training で使用するために、Python 2.7 または Python 3 を選択できます。トレーニング用の Python のバージョンを指定する方法をご覧ください。

費用

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

始める前に

GCP プロジェクトの設定

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the AI Platform Training & Prediction and Compute Engine APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the AI Platform Training & Prediction and Compute Engine APIs.

   Enable the APIs

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

認証の設定

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

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

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

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

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

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

      注: 選択したロールにより、サービス アカウントがリソースにアクセスできるようになります。これらのロールは、Google Cloud コンソールを使用して表示、変更できます。本番環境アプリを開発している場合は、AI Platform 管理者やストレージ オブジェクト管理者よりも権限が少ないロールの指定をおすすめします。詳しくは、AI Platform Training のアクセス制御をご覧ください。

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

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

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

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

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

   例: Linux または macOS

   [PATH] は、サービス アカウント キーが含まれる JSON ファイルのファイルパスに置き換えます。

   export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

   次に例を示します。

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   例: Windows

   [PATH] はサービス アカウント キーが格納されている JSON ファイルのパスに置き換え、[FILE_NAME] はファイル名に置き換えます。

   PowerShell を使用する場合:

   $env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

   次に例を示します。

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"

   コマンド プロンプトを使用する場合:

   set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

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 をアクティブにする」ボタンをクリックします。

   

   コンソールの下部の新しいフレーム内で 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 2.7 を使用しています。AI Platform Training で使用するために、Python 2.7 または Python 3 を選択できます。トレーニング用の Python のバージョンを指定する方法をご覧ください。

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

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

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

• OAuth2 の GoogleCredentials
• Python 用 Google API クライアント ライブラリの discovery
• Python 用 Google API クライアント ライブラリの errors

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

お好きなエディタで新しい 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 つの値を取ります（description は省略可能です）。 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'

次のステップ

• Google Cloud に関するリファレンス アーキテクチャ、図、ベスト プラクティスを確認する。Cloud Architecture Center を確認します。
• AI Platform Training API をよく理解する。
• モデルとジョブの管理の概要で、モデルの管理方法を学習する。