获取项目信息

在开发代码时，您可能不知道数据资产或连接的确切名称。 以下功能提供了资产列表，您可以从中选择相关资产。 在所有示例中，您都可以使用 "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> 通过使用这个入口点，你可以检索库正在运行的项目的元数据。 入口点 "wslib$here提供以下功能：

  • get_name()

    此函数返回项目的名称。

  • get_description()

    此函数返回项目的描述。

  • get_ID()

    此函数返回项目的 ID。

  • get_storage()

    该函数返回项目的存储信息。

获取身份验证令牌

有些任务需要验证令牌。 例如，如果您想针对数据和人工智能通用核心 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()返回的项目。

  请注意，在使用笔记本时，可以单击代码片段面板上的 "读取数据"，生成将数据从连接加载到 pandasDataFrame代码。

获取连接数据信息

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

• get_connected_data(name_or_item)

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

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

  • name_or_item：包含连接数据资产名称的字符串，或类似于 "list_connected_data()返回的项目。

  请注意，在使用笔记本时，可以单击代码片段面板上的 "读取数据"来生成代码，以便将数据从连接的数据资产加载到 pandasDataFrame中。

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

  此函数采用以下参数：

  • storage_path：（必填）存储文件的路径。
  • asset_name：（可选）创建资产的名称。 默认为文件名。
  • mime_type：（可选）创建资产的 MIME 类型。 默认情况下，MIME 类型由资产名称后缀决定。 如果您的文件名没有文件扩展名，或者您想设置不同的 MIME 类型，请使用此参数指定 MIME 类型。
  注意：您可以多次将一个文件注册为不同的数据资产。 在项目中删除其中一个资产也会删除存储中的文件，这意味着对该文件的其他资产引用可能会中断。

星火支持

入口点 "wslib$spark提供了使用 Spark 访问存储文件的功能。

入口点 "wslib$spark提供以下功能：

• provide_spark_context(sc)

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

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

  • sc：SparkContext。 它在笔记本运行时提供。

    下面的示例展示了如何设置 Spark 支持：

    library(ibmWatsonStudioLib)
    wslib <- access_project_or_space(list("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提供对任何类型资产的通用只读访问。 对于选定的资产类型，有专门的功能提供更多数据。

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

• 名为 "list_<something>的函数返回一个命名列表。 每个包含的列表代表一个资产，并包含一小组属性（元数据），用于识别该资产。
• 名为 "get_<something>的函数会返回一个包含资产属性的单一命名列表。

使用 "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：（可选）传递给数据和人工智能通用核心 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