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

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

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

目標

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

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

料金

このチュートリアルの操作のために課金されることはありません。詳細については、料金ページをご覧ください。

始める前に

GCP プロジェクトの設定

  1. Google アカウントにログインします。

    Google アカウントをまだお持ちでない場合は、新しいアカウントを登録します。

  2. GCP プロジェクトを選択または作成します。

    [リソースの管理] ページに移動

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

    課金を有効にする方法について

  4. AI Platform(「Cloud Machine Learning Engine」)と Compute Engine API を有効にします。

    APIを有効にする

  5. Cloud SDK をインストールして初期化します。

認証の設定

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

  1. 認証に使用するサービス アカウントキーを作成します。
    1. GCP Console で、[サービス アカウントキーの作成] ページに移動します。

      [サービス アカウントキーの作成] ページに移動
    2. [サービス アカウント] プルダウン リストから [新しいサービス アカウント] を選択します。
    3. [サービス アカウント名] フィールドに名前を入力します。
    4. [役割] プルダウン リストから、[Machine Learning Engine] > [ML Engine 管理者]、および [ストレージ] > [ストレージのオブジェクト管理者] を選択します。

      : [役割] フィールドの設定に応じて、サービス アカウントによるリソースへのアクセスが承認されます。このフィールドは、GCP Console を使用すると、後で表示や変更ができます。本番環境のアプリを開発している場合は、[Machine Learning Engine] > [ML Engine 管理者][ストレージ] > [ストレージのオブジェクト管理者] よりも詳細な権限を指定する必要があります。詳しくは、AI Platform のアクセス制御をご覧ください。
    5. [作成] をクリックします。キーを含む JSON ファイルがパソコンにダウンロードされます。
  2. 環境変数 GOOGLE_APPLICATION_CREDENTIALS をサービス アカウントキーが格納された JSON ファイルのファイルパスに設定します。この変数は現在の shell セッションにのみ適用されるため、新しいセッションを開く場合は、変数を再度設定します。

Python 開発環境の設定

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

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

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 --version を実行して、virtualenv がインストール済みかどうかを確認します。インストールされていない場合は、次のコマンドで virtualenv をインストールします。

    pip install --user --upgrade virtualenv

    このガイド用の隔離された開発環境を作成するために、virtualenv で新しい仮想環境を作成します。たとえば、次のコマンドを実行すると、cmle-env という名前の環境が有効になります。

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

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

Cloud Shell

  1. Google Cloud Platform Console を開きます。

    Google Cloud Platform Console

  2. コンソール ウィンドウの上部にある [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 サービスの Python 表現を取得する。
  • その表現を使用して自分のプロジェクトでモデルを作成する。これにより、他のモデルやジョブ管理 API を呼び出す方法を理解しやすくなります。
このチュートリアルの操作のために課金されることはありません。詳細については、料金ページをご覧ください。

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

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

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

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

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

API の Python 表現を構築する

REST API の Python 表現を取得します。API クライアント ライブラリは、サービス ディスカバリを使用して呼び出し時のサービスに動的に接続することから、呼び出しには build メソッドを使用します。また、サービス 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 リソースです。モデルリソース定義は、入力として namedescription の 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 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 モジュールを使用します。

request.execute() の呼び出しを try ブロックの中に入れます。同様に、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.discoverygoogleapiclient.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'
    

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

TensorFlow 用 AI Platform