获取项目信息

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

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

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

保存数据

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

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

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

• 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
    

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

获取连接信息

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

• 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 中重命名数据资产以解决冲突。

可以使用唯一标识访问资产，但建议不要使用唯一标识，因为标识仅在当前项目中有效，并且在传输到其他项目时将中断代码。 例如，在导出和重新导入项目时，可能会发生此情况。 您可以使用相应的列表函数 (例如 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.storage同步项目资产。

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

• fetch_data(filename)

  此函数将文件中的数据作为 BytesIO 缓冲区返回。 该文件不需要注册为数据资产。

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

  • filename:projectstorage 中文件的名称。

• 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() 上传的超大文件，可以使用此函数。您可以将大文件直接上传到项目的IBM Cloud Object Storage桶，例如通过用户界面，然后使用 "register_asset()将其注册为数据资产。

  此函数采用以下参数：

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

Spark 支持

入口点 wslib.spark 提供了通过 Spark 访问存储器中文件的功能。 要获取有关可用功能的帮助信息，请使用 help(wslib.spark.API)。

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

• provide_spark_context(sc)

  使用此功能来启用 Spark 支持。

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

  • sc: SparkContext。 它在 Notebook 运行时中提供。

  以下示例显示如何设置 Spark 支持:

  from ibm_watson_studio_lib import access_project_or_space
  wslib = access_project_or_space({"token":"<ProjectToken>"})
  wslib.spark.provide_spark_context(sc)
  

• get_data_url(asset_name)

  此函数返回一个 URL ，以通过 Hadoop从 Spark 访问存储器中的文件。

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

  • asset_name: 资产的名称。

• storage.get_data_url(file_name)

  此函数返回一个 URL ，以通过 Hadoop从 Spark 访问存储器中的文件。 该函数需要文件名而不是资产名称。

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

  • file_name: 项目存储器中文件的名称。

浏览项目资产

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

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

父主题: 使用 ibm-watson-studio-lib