プロジェクト情報の入手

コード開発中に、データ資産や接続の正確な名前を知らないかもしれない。 以下の機能は資産のリストを提供し、そこから関連するものを選ぶことができます。 すべての例で、'wslib$show(assets)を使ってリストをプリティ・プリントすることができる。 各項目のインデックスが項目の前に印刷される。

• list_connections()

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

  # Import the lib
  library("ibmWatsonStudioLib")
  wslib <- access_project_or_space(list("token"="<ProjectToken>"))
  
  assets <- wslib$list_connections()
  wslib$show(assets)
  connprops <- wslib$get_connection(assets[0])
  

• 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()

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

認証トークンの取得

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

ベアラートークンを取得するには、以下の関数を使用します：

• get_current_token()

次に例を示します。

library("ibmWatsonStudioLib")
wslib <- access_project_or_space(list("token"="<ProjectToken>"))
token <- wslib$auth$get_current_token()

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

データの取り出し

以下の関数を使用すると、プロジェクトに保存されているデータ資産（ファイル）からデータを取得できます。

• load_data(asset_name_or_item, attachment_type_or_item = NULL)

  この関数は、保存されているデータ資産のデータをバイトバッファにロードします。 この機能は非常に大きなファイルにはお勧めできません。

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

  • asset_name_or_item: (必須) 格納されたデータ資産の名前を表す文字列か、'list_stored_data() で返されるような項目。

  • attachment_type_or_item: （オプション）ロードする添付ファイルのタイプ。 データ資産には、データを添付した複数の添付ファイルを持つことができます。 このパラメータを指定しないと、デフォルトの添付ファイルタイプである「data_asset」がロードされる。 添付ファイルのタイプが'data_assetでない場合、このパラメータを指定する。 たとえば、プレーンテキストのデータ資産に自然言語解析のプロファイルが添付されている場合、これを添付ファイルのタイプ「data_profile_nlu」として読み込むことができます。

    以下は、データ資産のデータをロードする方法を示す例です：

    # Import the lib
    library("ibmWatsonStudioLib")
    wslib <- access_project_or_space(list("token"="<ProjectToken>"))
    
    # Fetch the data from a file
    my_file <- wslib$load_data("MyFile.csv")
    
    # Read the CSV data file into a data frame
    df <-  read.csv(text = rawToChar(my_file))
    head(df)
    

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

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

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

  • asset_name_or_item: (必須) 格納されたデータ資産の名前を表す文字列か、'list_stored_data() で返されるような項目。

  • file_name: （オプション）ダウンロードしたデータの保存先ファイル名。 デフォルトはアセットの添付ファイル名です。

  • attachment_type_or_item: （オプション）ダウンロードする添付ファイルの種類。 データ資産には、データを添付した複数の添付ファイルを持つことができます。 このパラメータを指定しないと、デフォルトの添付ファイルタイプである「data_asset」がダウンロードされる。 添付ファイルのタイプが'data_assetでない場合、このパラメータを指定する。 たとえば、プレーンテキストのデータ資産に自然言語解析のプロファイルが添付されている場合、このプロファイルは添付ファイルのタイプ「data_profile_nlu」としてダウンローディングして読み込むことができます。

    ここでは、'download_fileを使ってカスタムRスクリプトをノートブックで利用できるようにする方法を例示する：

    # Import the lib
    library("ibmWatsonStudioLib")
    wslib <- access_project_or_space(list("token"="<ProjectToken>"))
    
    # Let's assume you have a R script "helpers.R" with helper functions on your local machine.
    # Upload the script to your project using the Data Panel on the right.
    
    # Download the script to the file system of your runtime
    wslib$download_file("helpers.R")
    
    # Source the script to use the contained functions, e.g. ‘my_func’, in your notebook.
    source("helpers.R")
    my_func()
    

データの保存

プロジェクト・ストレージにデータを保存する関数は、複数のことを行う：

• プロジェクト・ストレージにデータを保存する
• データをデータアセットとしてプロジェクトに追加し（アセットを作成するか、既存のアセットを上書きする）、プロジェクトのデータアセットリストでデータを確認できるようにします。
• アセットとストレージ内のファイルを関連付けます。

データを保存するには、以下の機能を使用できます：

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

  メモリー内のデータをプロジェクト・ストレージに保存する機能。

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

  • asset_name_or_item: (必須) 'list_stored_data() が返す、作成されたアセットまたはリスト項目の名前。 この項目は、既存のファイルを上書きしたい場合に使用します。

  • data: (必須) アップロードするデータ。 期待されるデータ型は 'raw です。

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

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

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

    以下は、データをファイルに保存する方法を示す例である：

    # Import the lib
    library("ibmWatsonStudioLib")
    wslib <- access_project_or_space(list("token"="<ProjectToken>"))
    
    # let's assume you have a data frame df which contains the data
    # you want to save as a csv file
    csv <- capture.output(write.csv(df, row.names=FALSE), type="output")
    csv_raw <- charToRaw(paste0(csv, collapse='\n'))
    wslib$save_data("my_asset_name.csv", csv_raw)
    
    # the function returns a list which contains the asset_name, asset_id, file_name and additional information upon successful saving of the data
    

• upload_file(file_path, asset_name = NULL, file_name = NULL, overwrite = FALSE, mime_type = NULL)

  この関数は、ランタイムのファイルシステムにあるデータを、プロジェクトに関連付けられたファイルに保存する。

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

  • file_path: （必須）ファイルシステム内のファイルへのパス。

  • asset_name: （オプション）作成されるデータ資産の名前。 デフォルトはアップロードするファイル名です。

  • file_name: （オプション）プロジェクトに関連付けられたストレージに作成されるファイル名。 デフォルトはアップロードするファイル名です。

  • overwrite: （オプション）ストレージ内の既存のファイルを上書きする。 デフォルトは False です。

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

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

    # Import the lib
    library("ibmWatsonStudioLib")
    wslib <- access_project_or_space(list("token"="<ProjectToken>"))
    
    # Let's assume you have downloaded a file and want to save it
    # in your project.
    download.file("https://some/url/data_file.csv", "data_file.csv")
    wslib$upload_file("data_file.csv")
    
    # The function returns a list which contains the asset_name, asset_id, file_name and additional information upon successful saving of the data.
    

接続情報の取得

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

• get_connection(name_or_item)

  この関数は、接続データソースからデータを取得するために使用できる、接続のプロパティ（メタデータ）を返します。 プロパティを見るには「wslib$show(connprops)使う。 返されたリスト項目の特別なキー「"."」は、接続アセットに関する情報を提供します。

  この関数は以下の必須パラメータを取る：

  • name_or_item: 接続名の文字列か、'list_connections() が返すような項目。

  ノートブックで作業する場合、Code snippetsパネルでRead dataをクリックすると、例えば接続からpandasDataFrameにデータをロードするコードを生成することができます。

接続データ情報の取得

次の関数を使用して、接続されているデータ資産のメタデータにアクセスできます。

• get_connected_data(name_or_item)

  この関数は、基礎となる接続のプロパティを含む、接続されたデータ資産のプロパティを返します。 プロパティを見るには「wslib$show()使う。 返されたリストの特別なキー「"."」は、データと接続資産に関する情報を提供する。

  この関数は以下の必須パラメータを取る：

  • name_or_item: 接続されているデータ資産の名前を表す文字列か、'list_connected_data() が返すような項目。

  ノートブックで作業する場合、Code snippetsパネルでRead dataをクリックすると、接続されたデータアセットからpandasDataFrameなどにデータをロードするコードを生成できることに注意してください。

名前ではなくIDでアセットにアクセス

データ資産や接続には、常に一意な名前でアクセスすることが望ましい。 アセット名は必ずしも一意であるとは限らず、'ibm-watson-studio-lib関数は名前があいまいな場合に例外を発生させる。 コンフリクトを解消するには、UIでデータ・アセットの名前を変更します。

一意のIDでアセットにアクセスすることは可能ですが、IDは現在のプロジェクトでのみ有効であり、別のプロジェクトに移したときにコードが壊れてしまうため、お勧めしません。 これは、例えば、プロジェクトがエクスポートされ、再インポートされたときに起こる可能性があります。 例えば、'list_connections()ように、対応するリスト関数を使用することで、接続、接続済み、または保存されたデータ資産のIDを取得することができます。

エントリーポイント「wslib$by_id」は以下の機能を提供する：

• get_connection(asset_id)

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

• get_connected_data(asset_id)

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

• load_data(asset_id, attachment_type_or_item = NULL)

  この関数は、アセット ID を渡して、保存されているデータ資産のデータをロードします。 他に渡せるパラメータについては、'load_data()を参照のこと。

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

  この関数は、アセット ID を渡して、保存されているデータ・アセットにデータを保存します。 これは「overwrite=TRUE意味する。 その他に渡せるパラメータについては、'save_data()を参照のこと。

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

  この関数は、アセット ID を渡して、保存されているデータ資産のデータをダウンロードします。 他に渡せるパラメータについては「download_file()参照のこと。

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

エントリーポイント wslib$storage を使用することで、プロジェクト資産を同期させることなく、プロジェク トストレージからデータを取得し、プロジェクトストレージにデータを保存することができます。

エントリーポイント「wslib$storage」は以下の機能を提供する：

• fetch_data(filename)

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

  この関数は以下の必須パラメータを取る：

  • filename: プロジェクト内のファイル名。

• store_data(filename, data, overwrite = FALSE)

  この機能は、メモリ上のデータをストレージに保存しますが、新しいデータ資産を作成するわけではありません。 この関数は、ファイル名、ファイルパス、および追加情報を含むリストを返します。 情報を印刷するには「Use wslib$show()使う。

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

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

• download_file(storage_filename, local_filename = NULL)

  この関数は、ストレージ内のファイルのデータをダウンロードし、指定されたローカルファイルに格納する。 ローカルファイルがすでに存在する場合は上書きされる。

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

  • storage_filename: （必須）ダウンロードするストレージ内のファイル名。
  • local_filename: （オプション）ファイルをダウンロードするランタイムのローカル・ファイル・システム内のファイル名。 ストレージファイル名を使用する場合は、このパラメータを省略する。

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

  この関数は、ストレージ内のファイルをプロジェクト内のデータ資産として登録します。 同じ名前のデータ資産が既に存在する場合、この操作は失敗します。 save_data() でアップロードできない非常に大きなファイルがある場合、この関数を使用できます。例えば、UI 経由でプロジェクトのIBM Cloud Object Storageバケットに大きなファイルを直接アップロードし、'register_asset() を使用してデータ・アセットとして登録することができます。

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

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

スパーク・サポート

エントリーポイント「wslib$spark」は、Sparkでストレージ内のファイルにアクセスするための関数を提供する。

エントリーポイント「wslib$spark」は以下の機能を提供する：

• provide_spark_context(sc)

  スパークのサポートを有効にするには、この機能を使用します。

  この関数は以下の必須パラメータを取る：

  • sc：SparkContext。 これはノートブックのランタイムで提供される。

    次の例では、Sparkサポートを設定する方法を示します：

    library(ibmWatsonStudioLib)
    wslib <- access_project_or_space(list("token"="<ProjectToken>"))
    wslib$spark$provide_spark_context(sc)
    

• get_data_url(asset_name)

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

  この関数は以下の必須パラメータを取る：

  • asset_name: アセットの名前。

• storage.get_data_url(file_name)

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

  この関数は以下の必須パラメータを取る：

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

プロジェクト資産の閲覧

エントリーポイント「wslib$assets」は、あらゆるタイプのアセットへの汎用的な読み取り専用アクセスを提供する。 特定の資産タイプについては、追加データを提供する専用機能がある。

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

• list_<something>という名前の関数は、名前付きリストのリストを返す。 各リストは1つのアセットを表し、アセットを識別するプロパティ（メタデータ）の小さなセットが含まれています。
• get_<something>という名前の関数は、アセットのプロパティを1つの名前付きリストとして返します。

リストまたは名前付きリストのリストをプリティ・プリントするには、'wslib$show() を使う。

これらの関数は、アセット名かリストからの項目をパラメータとして受け取ります。 デフォルトでは、関数は利用可能なアセットプロパティのサブセットのみを返します。 パラメータ 'raw_info=TRUE を設定することで、アセットプロパティのフルセットを取得することができます。

エントリーポイント「wslib$assets」は以下の機能を提供する：

• list_assets(asset_type, name = NULL, query = NULL, selector = NULL, raw_info = FALSE)

  この関数は、与えられた制約に関して、与えられたタイプのすべての資産をリストアップします。

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

  • asset_type data_asset: （必須）リストアップする資産のタイプ。 利用可能なアセットタイプのリストは「list_asset_types()参照。 プロジェクトで利用可能なすべてのアセットのリストには、アセットタイプ「asset」を使用します。

  • name: (オプション) リストするアセット名。 同じ名前のアセットが複数存在する場合は、このパラメータを使用します。 指定できるのは「name」と「queryどちらかだけです。

  • query: （オプション）アセットを検索するためにData and AI Common Core APIに渡されるクエリー文字列。 指定できるのは「name」と「queryどちらかだけです。

  • selector: (オプション) 候補資産リスト項目に対するカスタムフィルター関数。 セレクタ関数が'TRUEを返した場合、そのアセットは返されたアセットリストに含まれます。

  • raw_info: （オプション）利用可能なすべてのメタデータを返す。 デフォルトでは、パラメータは「FALSE」に設定され、プロパティのサブセットのみが返される。

    list_assets関数の使用例：

    # Import the lib
    library("ibmWatsonStudioLib")
    wslib <- access_project_or_space(list("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 <- function(asset) asset$metadata$size > 1000000
    large_assets <- wslib$assets$list_assets("data_asset", selector = sizeFilter, raw_info = TRUE)
    wslib$show(large_assets)
    
    # List all notebooks
    notebooks <- wslib$assets$list_assets("notebook")
    

• list_asset_types(raw_info = FALSE)

  この機能は、利用可能なすべての資産タイプを一覧表示します。

  この関数は以下のパラメータを取ることができる：

  • raw_info: （オプション）メタデータのフルセットを返す。 デフォルトでは、パラメータは「FALSEであり、プロパティのサブセットのみが返される。

• list_datasource_types(raw_info = FALSE)

  この関数は、利用可能なすべてのデータ・ソース・タイプを一覧表示します。

  この関数は以下のパラメータを取ることができる：

  • raw_info: （オプション）メタデータのフルセットを返す。 デフォルトでは、パラメータは「FALSEであり、プロパティのサブセットのみが返される。

• get_asset(name_or_item, asset_type=None, raw_info = FALSE)

  この関数は、アセットのメタデータを返します。

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

  • name_or_item: （必須）資産の名前、または'list_assets()で返されるような項目。

  • asset_type: （オプション）資産のタイプ。 パラメータ 'name_or_itemにアセット名の文字列が含まれている場合は、'asset_type設定が必要です。

  • raw_info: （オプション）メタデータのフルセットを返す。 デフォルトでは、パラメータは「FALSEであり、プロパティのサブセットのみが返される。

    list_assets」と「get_asset関数の使用例：

    notebooks <- wslib$assets$list_assets("notebook")
    wslib$show(notebooks)
    
    notebook <- wslib$assets$get_asset(notebooks[[1]])
    wslib$show(notebook)
    

• get_connection(name_or_item, with_datasourcetype=False, raw_info = FALSE)

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

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

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

• get_connected_data(name_or_item, with_datasourcetype=False, raw_info = FALSE)

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

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

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

• get_stored_data(name_or_item, raw_info = FALSE)

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

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

  • name_or_item: （必須）保存されたデータ資産の名前、または'list_stored_data()で返されるような項目。
  • raw_info: （オプション）メタデータのフルセットを返す。 デフォルトでは、パラメータは「FALSEであり、プロパティのサブセットのみが返される。

• list_attachments(name_or_item_or_asset, asset_type=None, raw_info = FALSE)

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

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

  • name_or_item_or_asset: (必須) 'list_stored_data()または'get_asset()で返されるようなアセットまたはアイテムの名前。

  • asset_type: （オプション）資産のタイプ。 デフォルトは「data_assetである。

  • raw_info: （オプション）メタデータのフルセットを返す。 デフォルトでは、パラメータは「FALSEであり、プロパティのサブセットのみが返される。

    list_attachments関数を使用して、保存されているデータ資産の添付ファイルを読み取る例：

    assets <- wslib$list_stored_data()
    wslib$show(assets)
    
    asset <- assets[[1]]
    attachments <- wslib$assets$list_attachments(asset)
    wslib$show(attachments)
    buffer <- wslib$load_data(asset, attachments[[1]])
    

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