ibm-watson-studio-lib for Python

获取项目或空间信息

在开发代码时，您可能不知道数据资产或连接的确切名称。 以下函数提供资产列表，您可以从中选取相关资产。 在所有示例中，您可以使用 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()
  
  assets = wslib.list_connections()
  wslib.show(assets)
  connprops = wslib.get_connection(assets[0])
  wslib.show(connprops)
  

• list_connected_data()

  此函数返回已连接的数据资产。 返回的已连接数据资产的列表未按任何条件进行排序，当您再次调用该函数时可能会发生更改。 您可以将字典项而不是名称传递到 get_connected_data 函数。

• list_stored_data()

  此函数返回存储的数据资产 (数据文件) 的列表。 返回的数据资产的列表未按任何条件进行排序，当您再次调用该函数时，可能会发生更改。 您可以将字典项而不是名称传递到 load_data 和 save_data函数。

  注: 将应用启发式方法来区分已连接的数据资产和已存储的数据资产。 但是，在某些情况下，返回的列表中可能显示了错误类型的数据资产。

• wslib.here<br> 通过使用这个入口点，你可以获取有关项目或空间的元数据。 入口点 wslib.here 提供了以下功能:

  • get_name()

    此函数返回项目或空间的名称。

  • get_description()

    此函数返回项目或空间的描述。

  • get_ID()

    此函数返回项目或空间的标识。

  • get_storage()

    此函数返回项目或空间的存储信息。

获取认证令牌

某些任务需要认证令牌。 例如，如果您想使用数据和人工智能通用核心API 来运行自己的请求，则需要认证令牌。

您可以使用以下函数来获取不记名令牌:

• get_current_token()

例如：

from ibm_watson_studio_lib import access_project_or_space
wslib = access_project_or_space()
token = wslib.auth.get_current_token()

此函数返回 ibm-watson-studio-lib 库当前使用的不记名令牌。

请注意，通过环境变量USER_ACCESS_TOKEN获取认证令牌以在笔记本、脚本和 Python 函数中使用Data and AI Common Core API的选项已弃用，并将在未来版本中删除。

访存数据

您可以使用以下函数从项目或空间中存储的数据资产 (文件) 访存数据。

• 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，请指定此参数。 例如，如果纯文本数据资产具有来自 Natural Language Analysis 的附加概要文件，那么可以将其作为附件类型 data_profile_nlu装入。

    以下示例显示了如何装入数据资产的数据:

    # Import the lib
    from ibm_watson_studio_lib import access_project_or_space
    wslib = access_project_or_space()
    
    # 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)
    

• 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，请指定此参数。 例如，如果纯文本数据资产具有来自 Natural Language Analysis 的附加概要文件，那么可以将其作为附件类型 data_profile_nlu进行下载。

    以下示例显示了如何使用 download_file 使定制 Python 脚本在 Notebook 中可用:

    # Import the lib
    from ibm_watson_studio_lib import access_project_or_space
    wslib = access_project_or_space()
    
    # 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()
    

保存数据

用于在项目存储器中保存数据的函数执行多项操作:

• 将数据存储在项目存储器中
• 将数据作为数据资产 (通过创建资产或覆盖现有资产) 添加到项目或空间，以便您可以在项目或空间的数据资产列表中查看数据。
• 将资产与存储器中的文件相关联。

您可以使用以下函数来保存数据:

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

• 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()
    
    # 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.
    # The value `input_file_copied` tells you, if the file has been copied to project # storage.
    # If the value is true, you can savely delete the local input file.
    # If the value is false, you should not delete the input file because it already
    # exists in the mounted project storage. Deleting the file
    # from the mounted project storage will corrupt the created asset.
    # The return value can be passed to load_data() to read back the data.
    

获取连接信息

您可以使用以下函数来访问给定连接的连接元数据。

• get_connection(name_or_item)

  此函数返回可用于从连接数据源访存数据的连接的属性 (元数据)。 使用 wslib.show(connprops) 来查看属性。 返回的字典中的特殊键 "." 提供有关连接资产的信息。

  该函数采用以下必需参数:

  • name_or_item: 具有连接名称的字符串或类似 list_connections()返回的项。

  请注意，当您使用 Notebook 时，可以单击 "代码片段" 窗格上的 读取数据 以生成代码，例如，将数据从连接装入到 pandas DataFrame 中。

获取已连接的数据信息

您可以使用以下函数来访问已连接数据资产的元数据。

• get_connected_data(name_or_item)

  此函数返回已连接数据资产的属性，包括底层连接的属性。 使用 wslib.show() 来查看属性。 返回的字典中的特殊键 "." 提供有关数据和连接资产的信息。

  该函数采用以下必需参数:

  • name_or_item: 具有已连接数据资产的名称的字符串或类似 list_connected_data()返回的项。

  请注意，当您使用 Notebook 时，可以单击 "代码片段" 窗格上的 读取数据 以生成代码，例如，将数据从已连接的数据资产装入到 pandas DataFrame 中。

按标识而不是名称访问资产

您最好始终通过唯一名称访问数据资产和连接。 资产名称不一定总是唯一的，当名称不明确时， ibm-watson-studio-lib 函数将产生异常。 您可以在 UI 中重命名数据资产以解决冲突。

可以使用唯一标识访问资产，但建议不要使用此标识，因为标识仅在当前项目或空间中有效，并且在传输到其他项目或空间时将中断代码。 例如，在导出和重新导入项目时，或者在将 Notebook 或资产从项目提升到空间时，可能会发生此情况。 您可以使用相应的列表函数 (例如， list_connections()) 来获取已连接或已存储的数据资产的标识。

入口点 wslib.by_id 提供了以下功能:

• get_connection(asset_id)

  此函数通过连接资产标识访问连接。

• get_connected_data(asset_id)

  此函数通过已连接的数据资产标识访问已连接的数据资产。

• load_data(asset_id, attachment_type_or_item=None)

  此函数通过传递资产标识来装入存储的数据资产的数据。 请参阅 load_data() ，以获取您可以传递的其他参数的描述。

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

  此函数通过传递资产标识将数据保存到存储的数据资产。 这意味着 overwrite=True。 请参阅 save_data() ，以获取您可以传递的其他参数的描述。

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

  此函数通过传递资产标识来下载存储的数据资产的数据。 请参阅 download_file() ，以获取您可以传递的其他参数的描述。

使用已安装的项目存储器

运行代码的运行时可以使用入口点 wslib.mount将数据资产作为已安装文件系统中的纯文本文件提供。 例如，项目或空间存储器安装在 Notebook 运行时中。 在这种情况下，通过直接从文件中读取而不是复制内容，可以更有效地访问数据资产。

如果 mount.is_available() 函数返回 True ，那么可以使用以下函数。 如果此函数返回 False ，并且未安装包含数据资产的文件系统，那么您可以使用 访存数据 和 保存数据中描述的函数来处理数据。

• is_available()

  此功能检查项目存储器是否可用作本地文件系统中的安装。

• get_base_dir()

  此函数返回本地文件系统中数据资产文件夹的绝对路径。

• get_data_path(asset_name_or_item)

  此函数返回本地文件系统中数据资产引用的文件的绝对路径。

  该函数采用以下参数:

  • name_or_item: (必需) 具有已存储数据资产的名称的字符串或类似 list_stored_data()返回的项的字符串。

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

  此函数将本地安装中的文件注册为项目或空间中的数据资产。 如果具有相同名称的数据资产已存在，那么此操作将失败。

  此函数采用以下参数：

  • file_path: (必需) 本地安装的项目或空间存储器中文件的绝对路径。
  • asset_name: (可选) 已创建资产的名称。 它缺省为文件名。
  • mime_type: (可选) 所创建资产的 MIME 类型。 缺省情况下， MIME 类型由资产名称后缀确定。 如果文件名没有文件扩展名，或者如果要设置其他 MIME 类型，请使用此参数来指定 MIME 类型。

  以下示例显示如何将已安装项目存储器中的文件注册为资产:

  # Import the lib
  from ibm_watson_studio_lib import access_project_or_space
  wslib = access_project_or_space()
  
  # Let's assume you have a really large file that you cannot
  # upload to your project via 'save_data()' or 'upload_file()',
  # because those methods require the data to fit into memory.
  my_large_file = "my_large_file.csv"
  
  # Move the file to the data assets folder in the
  # mounted project storage:
  data_asset_folder = wslib.mount.get_base_dir()
  import os, shutil
  target_path = os.path.join(data_asset_folder, my_large_file)
  shutil.move(my_large_file, target_path)
  
  # Register the file as data asset
  wslib.mount.register_asset(target_path, asset_name="LargeFile.csv")
  
  # the function returns a dict which contains the asset_name, asset_id, file_name and additional information upon successful creation of the data asset.
  

  注: 您可以多次将文件注册为不同的数据资产。 删除项目界面中的其中一个资产还会删除存储器中的文件，这意味着对该文件的其他资产引用可能会中断。

直接访问项目存储器

您可以从项目存储器中访存数据，并将数据存储在项目存储器中，而无需使用入口点 wslib.storage同步项目资产。

在 Cloud Pak for Data中，项目或空间存储器安装在 Notebook 运行时中，您通常将使用入口点 wslib.mount 和文件系统操作来访问存储器。

入口点 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)

  此函数将存储器中的文件注册为项目或空间中的数据资产。 如果具有相同名称的数据资产已存在，那么此操作将失败。

  此函数采用以下参数：

  • storage_path: (必需) 存储器中文件的路径。
  • asset_name: (可选) 已创建资产的名称。 它缺省为文件名。
  • mime_type: (可选) 所创建资产的 MIME 类型。 缺省情况下， MIME 类型由资产名称后缀确定。 如果文件名没有文件扩展名，或者如果要设置其他 MIME 类型，请使用此参数来指定 MIME 类型。
  注: 您可以多次将文件注册为不同的数据资产。 删除项目中的其中一个资产还会删除存储器中的文件，这意味着对该文件的其他资产引用可能会中断。

浏览项目资产

入口点 wslib.assets 提供对任何类型的资产的通用只读访问。 对于所选资产类型，有提供其他数据的专用功能。 要获取有关可用功能的帮助，请使用 help(wslib.assets.API)。

适用的命名约定如下所示：

• 名为 list_<something> 的函数返回 Python 字典列表。 每个字典都表示一个资产，并包含标识该资产的一小部分属性 (元数据)。
• 名为 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：（可选）传递给数据和人工智能通用核心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()
  
  # List all assets in the project or space
  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")
  

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

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