ibm-watson-studio-lib 用于 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()

  此函数返回存储的数据资产（数据文件）列表。 返回的数据资产列表未按任何标准排序，且在再次调用该函数时可能发生变化。 你可以向 和 save_dataload_data 函数传递字典项而非名称。

  注： 采用启发式方法区分关联数据资产与存储数据资产。 然而，某些情况下，返回列表中可能会出现错误类型的数据资产。

• wslib.here<\br>

  通过使用此入口点，您可以获取该库正在处理的项目或空间的相关元数据。 该入口点 wslib.here 提供以下功能：

  • get_name()

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

  • get_description()

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

  • get_ID()

    此函数返回项目或空间的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 库当前使用的承载令牌。

访存数据

您可以使用以下函数从工作区中的存储数据资产（文件）中获取数据。

• 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()
    
    # 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.，请指定此参数。 例如，如果一个纯文本数据资产附带了来自自然语言分析的配置文件，则该文件可作为附件类型下载 data_profile_nlu。

    以下示例展示了如何使用 download_file 使您的自定义 Python 脚本在笔记本中可用：

    # 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(). 返回的项。

  请注意，在处理笔记本时，您可以点击代码片段窗格中的 "读取数据 "按钮，生成代码将数据从连接中加载到pandas数据框（ DataFrame ）中。

获取联网数据信息

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

• get_connected_data(name_or_item)

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

  该函数需要以下必填参数：

  • name_or_item：要么是一个包含已连接数据资产名称的字符串，要么是类似由 list_connected_data(). 返回的项目。

  请注意，在处理笔记本时，您可点击代码片段窗格中的 "读取数据 "按钮，生成代码将连接数据资产中的数据加载到pandas数据框（ DataFrame ）中。

通过ID而非名称访问资产

您应始终通过唯一名称访问数据资产和连接。 资产名称未必总是唯一的，当名称存在歧义时，相关 ibm-watson-studio-lib 函数将抛出异常。 您可以在用户界面中重命名数据资产以解决冲突。

通过唯一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() 的说明，请参见。

使用已挂载的项目存储

运行时环境会将数据资产作为普通文件提供在挂载的文件系统中，使用入口点 wslib.mount。 例如，项目或空间存储被挂载到笔记本的运行时环境中。 在这种情况下，直接从文件中读取数据而非复制内容，可以更高效地访问数据资产。

如果函数 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在项目存储中，而无需同步项目资源。

项目或空间存储已挂载至笔记本运行时环境，通常需通过入口点及 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 1 MB
  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])