ibm-watson-studio-lib ( Python 用)

プロジェクト情報の取得

Copy link to section

コードの開発中に、データ資産または接続の正確な名前が分からない場合があります。 以下の機能は、資産のリストを提供します。このリストから、関連する資産を選択できます。 すべての例で、 wslib.show(assets) を使用してリストを整形印刷できます。 各項目の索引は、項目の前に印刷されます。

• list_connections()

  この関数は接続のリストを返す。 返される接続のリストは、どの基準によってもソートされず、関数を再度呼び出すと変更される可能性があります。 名前の代わりに辞書項目を get_connection 関数に渡すことができます。

  次に例を示します。

  # Import the lib
  from ibm_watson_studio_lib import access_project_or_space
  wslib = access_project_or_space({"token":"<ProjectToken>"})
  
  assets = wslib.list_connections()
  wslib.show(assets)
  connprops = wslib.get_connection(assets[0])
  wslib.show(connprops)
  Copy to clipboardクリップボードにコピーされました

• list_connected_data()

  この関数は、接続されているデータ資産を返します。 返される接続済みデータ資産のリストは、どの基準によってもソートされず、関数を再度呼び出したときに変更される可能性があります。 名前の代わりに辞書項目を get_connected_data 関数に渡すことができます。

• list_stored_data()

  この関数は、保管されているデータ資産 (データ・ファイル) のリストを返します。 返されるデータ資産のリストは、どの基準によってもソートされず、関数を再度呼び出すと変更される可能性があります。 名前の代わりに辞書項目を load_data 関数と save_data関数に渡すことができます。

  注: ヒューリスティックは、接続されたデータ資産と保管されたデータ資産を区別するために適用されます。 ただし、返されるリストに誤った種類のデータ資産が表示される場合があります。

• wslib.here< ¥ br>

  このエントリー・ポイントを使用して、lib が処理しているプロジェクトに関するメタデータを取得できます。 エントリー・ポイント wslib.here は、以下の機能を提供します。

  • get_name()

    この関数は、プロジェクトの名前を返します。

  • get_description()

    この関数は、プロジェクトの説明を返します。

  • get_ID()

    この関数は、プロジェクトの ID を返します。

  • get_storage()

    この関数は、プロジェクトのストレージ情報を返します。

認証トークンの取得

Copy link to section

一部のタスクでは認証トークンが必要です。 例えば、Data and AI Common Core APIに対して独自のリクエストを実行したい場合、認証トークンが必要になる。

以下の関数を使用して、ベアラー・トークンを取得できます。

• get_current_token()

次に例を示します。

from ibm_watson_studio_lib import access_project_or_space
wslib = access_project_or_space({"token":"<ProjectToken>"})
token = wslib.auth.get_current_token()
Copy to clipboardクリップボードにコピーされました

この関数は、 ibm-watson-studio-lib ライブラリーによって現在使用されているベアラー・トークンを返します。

データの取り出し

Copy link to section

以下の関数を使用して、プロジェクト内の保管データ資産 (ファイル) からデータを取り出すことができます。

• load_data(asset_name_or_item, attachment_type_or_item=None)

  この関数は、保管されたデータ資産のデータを BytesIO バッファーにロードします。 この機能は、非常に大きなファイルの場合は推奨されません。

  この関数は、以下のパラメーターを取ります。

  • asset_name_or_item: (必須) 保管されているデータ資産の名前を含むストリング、または list_stored_data()によって返されるような項目。

  • attachment_type_or_item: (オプション) ロードする添付ファイルのタイプ。 データ資産には、データを含む複数の添付ファイルを含めることができます。 このパラメーターを指定しない場合、デフォルトの接続タイプ、つまり data_asset がロードされます。 添付ファイル・タイプが data_assetでない場合は、このパラメーターを指定します。 例えば、プレーン・テキスト・データ資産に自然言語分析からのプロファイルが添付されている場合、これは添付ファイル・タイプ data_profile_nluとしてロードできます。

    以下に、データ資産のデータをロードする方法を示す例を示します。

    # Import the lib
    from ibm_watson_studio_lib import access_project_or_space
    wslib = access_project_or_space({"token":"<ProjectToken>"})
    
    # Fetch the data from a file
    my_file = wslib.load_data("MyFile.csv")
    
    # Read the CSV data file into a pandas DataFrame
    my_file.seek(0)
    import pandas as pd
    pd.read_csv(my_file, nrows=10)
    Copy to clipboardクリップボードにコピーされました

• download_file(asset_name_or_item, file_name=None, attachment_type_or_item=None)

  この関数は、保管されたデータ資産のデータをダウンロードし、ランタイムのファイル・システム内の指定されたファイルに保管します。 このファイルが既に存在している場合は、上書きされます。

  この関数は、以下のパラメーターを取ります。

  • asset_name_or_item: (必須) 保管されているデータ資産の名前を含むストリング、または list_stored_data()によって返されるような項目。

  • file_name: (オプション) ダウンロードされたデータが保管されるファイルの名前。 デフォルトでは、資産の添付ファイル名になります。

  • attachment_type_or_item: (オプション) ダウンロードする添付ファイルのタイプ。 データ資産には、データを含む複数の添付ファイルを含めることができます。 このパラメーターを指定しない場合、デフォルトの添付ファイル・タイプ ( data_asset ) がダウンロードされます。 添付ファイル・タイプが data_assetでない場合は、このパラメーターを指定します。 例えば、プレーン・テキスト・データ資産に自然言語分析のプロファイルが添付されている場合、これは添付ファイル・タイプ data_profile_nluとしてダウンロードできます。

    download_file を使用してカスタム Python スクリプトをノートブックで使用可能にする方法を示す例を以下に示します。

    # Import the lib
    from ibm_watson_studio_lib import access_project_or_space
    wslib = access_project_or_space({"token":"<ProjectToken>"})
    
    # Let's assume you have a Python script "helpers.py" with helper functions on your local machine.
    # Upload the script to your project using the Data Panel on the right of the opened notebook.
    
    # Download the script to the file system of your runtime
    wslib.download_file("helpers.py")
    
    # import the required functions to use them in your notebook
    from helpers import my_func
    my_func()
    Copy to clipboardクリップボードにコピーされました

データの保存

Copy link to section

プロジェクト・ストレージにデータを保存する機能は、以下のように複数のことを行います。

• プロジェクト・ストレージへのデータの保管
• プロジェクト内のデータ資産リストにデータを表示できるように、データ資産としてデータを追加します (資産を作成するか、既存の資産を上書きします)。
• ストレージ内のファイルに資産を関連付けます。

以下の関数を使用して、データを保存できます。

• save_data(asset_name_or_item, data, overwrite=None, mime_type=None, file_name=None)

  この関数は、メモリー内のデータをプロジェクト・ストレージに保存します。

  この関数は、以下のパラメーターを取ります。

  • asset_name_or_item: (必須) list_stored_data()によって返される作成済みの資産またはリスト項目の名前。 既存のファイルを上書きする場合は、この項目を使用できます。

  • data: (必須) アップロードするデータ。 これは、タイプ bytes-like-objectの任意のオブジェクト (例えば、バイト・バッファー) にすることができます。

  • overwrite: (オプション) 保管データ資産のデータが既に存在する場合は、そのデータを上書きします。 デフォルトでは、これは false に設定されています。 名前の代わりにアセット・アイテムが渡された場合の動作は、アセットを上書きすることです。

  • mime_type: (オプション) 作成されたアセットの MIME タイプ。 デフォルトでは、MIME タイプはアセット名の接尾部から決定されます。 接尾部なしで資産名を使用する場合は、ここで MIME タイプを指定します。 例えば、プレーン・テキスト・データの場合は mime_type=application/text です。 アセットを上書きする場合、このパラメーターは無視されます。

  • file_name: (オプション) プロジェクト・ストレージで使用されるファイル名。 データは、プロジェクトに関連付けられたストレージに保存されます。 新規アセットの作成時に、ファイル名はアセット名から派生しますが、異なる場合があります。 ファイルに直接アクセスする場合は、ファイル名を指定できます。 アセットを上書きする場合、このパラメーターは無視されます。

    以下に、データをファイルに保存する方法を示す例を示します。

    # Import the lib
    from ibm_watson_studio_lib import access_project_or_space
    wslib = access_project_or_space({"token":"<ProjectToken>"})
    
    # let's assume you have the pandas DataFrame pandas_df which contains the data
    # you want to save as a csv file
    wslib.save_data("my_asset_name.csv", pandas_df.to_csv(index=False).encode())
    
    # the function returns a dict which contains the asset_name, asset_id, file_name and additional information upon successful saving of the data
    Copy to clipboardクリップボードにコピーされました

• upload_file(file_path, asset_name=None, file_name=None, overwrite=False, mime_type=None) この関数は、ランタイムのファイル・システム内のデータを、プロジェクトに関連付けられたファイルに保存します。 この関数は、以下のパラメーターを取ります。

  • file_path: (必須) ファイル・システム内のファイルへのパス。

  • asset_name: (オプション) 作成されるデータ・アセットの名前。 デフォルトでは、アップロードするファイルの名前になります。

  • file_name: (オプション) プロジェクトに関連付けられたストレージ内に作成されるファイルの名前。 デフォルトでは、アップロードするファイルの名前になります。

  • overwrite: (オプション) ストレージ内の既存のファイルを上書きします。 デフォルトは false です。

  • mime_type: (オプション) 作成されたアセットの MIME タイプ。 デフォルトでは、MIME タイプはアセット名の接尾部から決定されます。 接尾部なしで資産名を使用する場合は、ここで MIME タイプを指定します。 例えば、プレーン・テキスト・データの場合は mime_type='application/text' です。 アセットを上書きする場合、このパラメーターは無視されます。

    ファイルをプロジェクトにアップロードする方法を示す例を以下に示します。

    # Import the lib
    from ibm_watson_studio_lib import access_project_or_space
    wslib = access_project_or_space({"token":"<ProjectToken>"})
    
    # Let's assume you have downloaded a file and want to save it
    # in your project.
    import urllib.request
    urllib.request.urlretrieve("https://some/url/data_file.csv", "data_file.csv")
    wslib.upload_file("data_file.csv")
    
    # The function returns a dictionary which contains the asset_name, asset_id, file_name and additional information upon successful saving of the data.
    Copy to clipboardクリップボードにコピーされました

接続情報の取得

Copy link to section

以下の関数を使用して、特定の接続の接続メタデータにアクセスできます。

• get_connection(name_or_item)

  この関数は、接続データ・ソースからデータを取り出すために使用できる接続のプロパティー (メタデータ) を返します。 プロパティーを表示するには、 wslib.show(connprops) を使用します。 返されたディクショナリー内の特殊キー "." は、接続資産に関する情報を提供します。

  この関数は、以下の必須パラメーターを取ります。

  • name_or_item: 接続の名前を含むストリング、または list_connections()によって返される項目などの項目。

  ノートブックで作業する場合は、「コード・スニペット」ペインの 「データの読み取り」 をクリックして、接続からパンダ DataFrame などにデータをロードするコードを生成できます。

接続されたデータ情報の取得

Copy link to section

以下の機能を使用して、接続されたデータ資産のメタデータにアクセスできます。

• get_connected_data(name_or_item)

  この関数は、基礎となる接続のプロパティーを含む、接続されたデータ資産のプロパティーを返します。 プロパティーを表示するには、 wslib.show() を使用します。 返されたディクショナリー内の特殊キー "." は、データおよび接続資産に関する情報を提供します。

  この関数は、以下の必須パラメーターを取ります。

  • name_or_item: 接続されたデータ資産の名前を含むストリング、または list_connected_data()によって返されるような項目。

  ノートブックで作業する場合は、「コード・スニペット」ペインの 「データの読み取り」 をクリックして、接続されたデータ資産から pandas DataFrame などにデータをロードするコードを生成できます。

名前ではなく ID で資産にアクセスする

Copy link to section

データ資産および接続には、常に固有の名前でアクセスすることをお勧めします。 アセット名は常に固有であるとは限りません。名前があいまいな場合は、 ibm-watson-studio-lib 関数によって例外が発生します。 競合を解決するために、UI でデータ資産の名前を変更できます。

固有 ID による資産へのアクセスは可能ですが、ID が現行プロジェクトでのみ有効であり、別のプロジェクトに転送されるとコードが中断されるため、推奨されません。 これは、例えば、プロジェクトがエクスポートされて再インポートされた場合に発生する可能性があります。 接続、接続、または保管されているデータ資産の ID は、対応するリスト関数 ( list_connections()など) を使用して取得できます。

エントリー・ポイント wslib.by_id は、以下の機能を提供します。

• get_connection(asset_id)

  この関数は、接続資産 ID によって接続にアクセスします。

• get_connected_data(asset_id)

  この関数は、接続されたデータ資産 ID によって接続されたデータ資産にアクセスします。

• load_data(asset_id, attachment_type_or_item=None)

  この関数は、資産 ID を渡すことによって、保管されているデータ資産のデータをロードします。 渡すことができるその他のパラメーターの説明については、「 load_data() 」を参照してください。

• save_data(asset_id, data, overwrite=None, mime_type=None, file_name=None)

  この関数は、資産 ID を渡すことにより、保管データ資産にデータを保存します。 これは overwrite=Trueを暗黙指定します。 渡すことができるその他のパラメーターの説明については、「 save_data() 」を参照してください。

• download_file(asset_id, file_name=None, attachment_type_or_item=None)

  この関数は、資産 ID を渡すことによって、保管されているデータ資産のデータをダウンロードします。 渡すことができるその他のパラメーターの説明については、「 download_file() 」を参照してください。

プロジェクト・ストレージへの直接アクセス

Copy link to section

エントリー・ポイント wslib.storageを使用してプロジェクト資産を同期することなく、プロジェクト・ストレージからデータをフェッチし、プロジェクト・ストレージにデータを保管することができます。

エントリー・ポイント wslib.storage は、以下の機能を提供します。

• fetch_data(filename)

  この関数は、ファイル内のデータを BytesIO バッファーとして返します。 ファイルをデータ資産として登録する必要はありません。

  この関数は、以下の必須パラメーターを取ります。

  • filename: プロジェクト・ストレージにあるファイルの名前。

• store_data(filename, data, overwrite=False)

  この関数は、メモリー内のデータをストレージに保存しますが、新しいデータ資産は作成しません。 この関数は、ファイル名、ファイル・パス、および追加情報を含む辞書を戻します。 情報を印刷するには、 wslib.show() を使用します。

  この関数は、以下のパラメーターを取ります。

  • filename: (必須) プロジェクト・ストレージ内のファイルの名前。
  • data: (必須) バイトのようなオブジェクトとして保存するデータ。
  • overwrite: (オプション) ストレージ内のファイルのデータが既に存在する場合は、そのデータを上書きします。 デフォルトでは、これは false に設定されています。

• download_file(storage_filename, local_filename=None)

  この関数は、ストレージ内のファイルにデータをダウンロードし、指定されたローカル・ファイルに保管します。 ローカル・ファイルは、既に存在している場合は上書きされます。

  この関数は、以下のパラメーターを取ります。

  • storage_filename: (必須) ダウンロードするストレージ内のファイルの名前。
  • local_filename: (オプション) ファイルのダウンロード先となるランタイムのローカル・ファイル・システム内のファイルの名前。 ストレージ・ファイル名を使用するには、このパラメーターを省略します。

• register_asset(storage_path, asset_name=None, mime_type=None)

  この関数は、プロジェクト内のデータ資産としてストレージ内のファイルを登録します。 同じ名前のデータ資産が既に存在する場合、この操作は失敗します。

  save_data() でアップロードできない非常に大きなファイルがある場合、この関数を使用できます。例えば、UI 経由でプロジェクトのIBM Cloud Object Storageバケットに大きなファイルを直接アップロードし、'register_asset() を使用してデータ・アセットとして登録することができます。

  この関数は、以下のパラメーターを取ります。

  • storage_path: (必須) ストレージ内のファイルのパス。
  • asset_name: (オプション) 作成されたアセットの名前。 デフォルトはファイル名です。
  • mime_type: (オプション) 作成されたアセットの MIME タイプ。 デフォルトでは、MIME タイプはアセット名の接尾部から決定されます。 ファイル名にファイル拡張子がない場合、または別の MIME タイプを設定する場合は、このパラメーターを使用して MIME タイプを指定します。
  注: 1 つのファイルを別のデータ資産として複数回登録することができます。 プロジェクト内のこれらの資産の 1 つを削除すると、ストレージ内のファイルも削除されます。これは、ファイルへの他の資産参照が破損する可能性があることを意味します。

Spark サポート

Copy link to section

エントリー・ポイント wslib.spark は、Spark を使用してストレージ内のファイルにアクセスする機能を提供します。 使用可能な関数に関するヘルプ情報を取得するには、 help(wslib.spark.API)を使用します。

エントリー・ポイント wslib.spark は、以下の機能を提供します。

• provide_spark_context(sc)

  この機能を使用して、Spark サポートを有効にします。

  この関数は、以下の必須パラメーターを取ります。

  • sc: SparkContext。 これは、ノートブック・ランタイムで提供されます。

  以下の例は、Spark サポートをセットアップする方法を示しています。

  from ibm_watson_studio_lib import access_project_or_space
  wslib = access_project_or_space({"token":"<ProjectToken>"})
  wslib.spark.provide_spark_context(sc)
  Copy to clipboardクリップボードにコピーされました

• get_data_url(asset_name)

  この関数は、 Hadoopを介して Spark からストレージ内のファイルにアクセスするための URL を返します。

  この関数は、以下の必須パラメーターを取ります。

  • asset_name: アセットの名前です。

• storage.get_data_url(file_name)

  この関数は、 Hadoopを介して Spark からストレージ内のファイルにアクセスするための URL を返します。 この関数は、アセット名ではなくファイル名を予期しています。

  この関数は、以下の必須パラメーターを取ります。

  • file_name: プロジェクト・ストレージ内のファイルの名前。

プロジェクト資産の参照

Copy link to section

エントリー・ポイント wslib.assets は、あらゆるタイプの資産への汎用読み取り専用アクセスを提供します。 選択した資産タイプには、追加データを提供する専用機能があります。 使用可能な関数のヘルプを表示するには、 help(wslib.assets.API)を使用します。

以下の命名規則が適用されます。

• list_<something> という名前の関数は、 Python 辞書のリストを返します。 各ディクショナリーは 1 つの資産を表し、資産を識別するプロパティー (メタデータ) の小さなセットが含まれています。
• get_<something> という名前の関数は、資産のプロパティーを含む単一の Python 辞書を返します。

辞書または辞書のリストを整形印刷するには、 wslib.show()を使用します。

これらの関数は、パラメーターとして資産の名前、またはリストの項目のいずれかを予期します。 デフォルトでは、関数は使用可能な資産プロパティーのサブセットのみを返します。 パラメーター raw=Trueを設定すると、アセット・プロパティーの完全なセットを取得できます。

エントリー・ポイント wslib.assets は、以下の機能を提供します。

• list_assets(asset_type, name=None, query=None, selector=None, raw=False)

  この関数は、指定された制約に関して、指定されたタイプのすべての資産をリストします。

  この関数は、以下のパラメーターを取ります。

  • asset_type: (必須) リストする資産のタイプ (例: data_asset)。 使用可能な資産タイプのリストについては、 list_asset_types() を参照してください。 プロジェクト内の使用可能なすべての資産のリストには、資産タイプ asset を使用します。
  • name: (オプション) リストするアセットの名前です。 同じ名前の資産が複数存在する場合は、このパラメーターを使用します。 name と queryのいずれかのみを指定できます。
  • query: （オプション）アセットを検索するためにData and AI Common Core APIに渡されるクエリー文字列。 name と queryのいずれかのみを指定できます。
  • selector: (オプション) 候補アセット辞書項目に対するカスタム・フィルター機能。 セレクター関数が Trueを返す場合、その資産は、返される資産リストに含まれます。
  • raw: (オプション) 使用可能なすべてのメタデータを返します。 デフォルトでは、このパラメーターは False に設定され、プロパティーのサブセットのみが返されます。

  list_assets 関数の使用例:

  # Import the lib
  from ibm_watson_studio_lib import access_project_or_space
  wslib = access_project_or_space({"token":"<ProjectToken>"})
  
  # List all assets in the project
  all_assets = wslib.assets.list_assets("asset")
  wslib.show(all_assets)
  
  # List all data assets with name 'MyFile.csv'
  assets_by_name = wslib.assets.list_assets("data_asset", name="MyFile.csv")
  
  # List all data assets whose name starts with "MyF"
  assets_by_query = wslib.assets.list_assets("data_asset", query="asset.name:(MyF*)")
  
  # List all data assets which are larger than 1MB
  sizeFilter = lambda x: x['metadata']['size'] > 1000000
  large_assets = wslib.assets.list_assets("data_asset", selector=sizeFilter, raw=True)
  
  # List all notebooks
  notebooks = wslib.assets.list_assets("notebook")
  Copy to clipboardクリップボードにコピーされましたShow more

• list_asset_types(raw=False)

  この関数は、使用可能なすべての資産タイプをリストします。

  この関数は、以下のパラメーターを取ることができます。

  • raw: (オプション) メタデータの完全セットを返します。 デフォルトでは、このパラメーターは False であり、プロパティーのサブセットのみが返されます。

• list_datasource_types(raw=False)

  この関数は、使用可能なすべてのデータ・ソース・タイプをリストします。

  この関数は、以下のパラメーターを取ることができます。

  • raw: (オプション) メタデータの完全セットを返します。 デフォルトでは、このパラメーターは False であり、プロパティーのサブセットのみが返されます。

• get_asset(name_or_item, asset_type=None, raw=False)

  この関数は、資産のメタデータを返します。

  この関数は、以下のパラメーターを取ります。

  • name_or_item: (必須) 資産の名前、または list_assets() によって返される項目のような項目の名前
  • asset_type: (オプション) 資産のタイプです。 パラメーター name_or_item に資産の名前のストリングが含まれている場合は、 asset_type を設定する必要があります。
  • raw: (オプション) メタデータの完全セットを返します。 デフォルトでは、このパラメーターは False であり、プロパティーのサブセットのみが返されます。

  list_assets 関数と get_asset 関数の使用例:

  notebooks = wslib.assets.list_assets('notebook')
  wslib.show(notebooks)
  
  notebook = wslib.assets.get_asset(notebooks[0])
  wslib.show(notebook)
  Copy to clipboardクリップボードにコピーされました

• get_connection(name_or_item, with_datasourcetype=False, raw=False)

  この関数は、接続のメタデータを返します。

  この関数は、以下のパラメーターを取ります。

  • name_or_item: (必須) 接続の名前、または list_connections() によって返される項目などの項目。
  • with_datasourcetype: (オプション) 接続のデータ・ソース・タイプに関する追加情報を返します。
  • raw: (オプション) メタデータの完全セットを返します。 デフォルトでは、このパラメーターは False であり、プロパティーのサブセットのみが返されます。

• get_connected_data(name_or_item, with_datasourcetype=False, raw=False)

  この関数は、接続されているデータ資産のメタデータを返します。

  この関数は、以下のパラメーターを取ります。

  • name_or_item: (必須) 接続されたデータ資産の名前、または list_connected_data() によって返されるような項目の名前
  • with_datasourcetype: (オプション) 関連付けられた接続済みデータ資産のデータ・ソース・タイプに関する追加情報を返します。
  • raw: (オプション) メタデータの完全セットを返します。 デフォルトでは、このパラメーターは False であり、プロパティーのサブセットのみが返されます。

• get_stored_data(name_or_item, raw=False)

  この関数は、保管されているデータ資産のメタデータを返します。

  この関数は、以下のパラメーターを取ります。

  • name_or_item: (必須) 保管されているデータ資産の名前、または list_stored_data() によって返されるような項目の名前
  • raw: (オプション) メタデータの完全セットを返します。 デフォルトでは、このパラメーターは False であり、プロパティーのサブセットのみが返されます。

• list_attachments(name_or_item_or_asset, asset_type=None, raw=False)

  この関数は、資産の添付ファイルのリストを返します。

  この関数は、以下のパラメーターを取ります。

  • name_or_item_or_asset: (必須) 資産の名前、または list_stored_data() または get_asset()によって返される項目のような項目の名前。
  • asset_type: (オプション) 資産のタイプです。 デフォルトでは、タイプ data_assetに設定されます。
  • raw: (オプション) メタデータの完全セットを返します。 デフォルトでは、このパラメーターは False であり、プロパティーのサブセットのみが返されます。

  list_attachments 関数を使用して、保管されているデータ資産の添付ファイルを読み取る例を以下に示します。

  assets = wslib.list_stored_data()
  wslib.show(assets)
  
  asset = assets[0]
  attachments = wslib.assets.list_attachments(asset)
  wslib.show(attachments)
  buffer = wslib.load_data(asset, attachments[0])
  Copy to clipboardクリップボードにコピーされました

親トピック: ibm-watson-studio-lib の使用