ibm-watson-studio-lib para R

Obter informações do projeto

Ao desenvolver código, você pode não saber os nomes exatos de ativos de dados ou conexões. As funções a seguir fornecem listas de ativos, das quais é possível selecionar os relevantes. Em todos os exemplos, é possível usar wslib$show(assets) para imprimir a lista. O índice de cada item é impresso na frente do item.

• list_connections()

  Esta função retorna uma lista das conexões.. A lista de conexões retornadas não é classificada por nenhum critério e pode ser alterada quando você chamar a função novamente. É possível transmitir um item de lista em vez de um nome para o 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()

  Essa função retorna os ativos de dados conectados. A lista de ativos de dados conectados retornados não é classificada por nenhum critério e pode ser alterada ao chamar a função novamente. É possível transmitir um item da lista em vez de um nome para a função get_connected_data

• list_stored_data()

  Esta função retorna uma lista dos ativos de dados armazenados (arquivos de dados).. A lista de ativos de dados retornados não é classificada por nenhum critério e pode ser alterada ao chamar a função novamente. É possível transmitir um item de lista em vez de um nome para as funções load_data e save_data

  Nota: uma heurística é aplicada para distinguir entre ativos de dados conectados e ativos de dados armazenados. No entanto, pode haver casos em que um ativo de dados do tipo errado aparece nas listas retornadas.

• wslib$here Ao usar este ponto de entrada, você pode recuperar metadados sobre o projeto com o qual a biblioteca está trabalhando. O ponto de entrada wslib$here fornece as seguintes funções:

  • get_name()

    Essa função retorna o nome do projeto.

  • get_description()

    Essa função retorna a descrição do projeto.

  • get_ID()

    Esta função retorna o ID do projeto.

  • get_storage()

    Esta função retorna informações de armazenamento para o projeto.

Obter token de autenticação

Algumas tarefas requerem um Token de Autenticação Por exemplo, se você quiser executar suas próprias solicitações na API Data and AI Common Core, precisará de um token de autenticação.

É possível usar a função a seguir para obter o token de acesso:

• get_current_token()

Por exemplo:

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

Essa função retorna o token de acesso usado atualmente pela biblioteca ibm-watson-studio-lib .

Buscar dados

Você pode usar as seguintes funções para buscar dados de um ativo de dados armazenado (um arquivo) em seu espaço de trabalho.

• load_data(asset_name_or_item, attachment_type_or_item = NULL)

  Esta função carrega os dados de um ativo de dados armazenado em um buffer de bytes.. A função não é recomendada para arquivos muito grandes.

  A função assume os parâmetros a seguir:

  • asset_name_or_item: (Obrigatório) Uma cadeia com o nome de um ativo de dados armazenados ou um item como aqueles retornados por list_stored_data()..

  • attachment_type_or_item: (Opcional) Tipo de anexo para carregar. Um ativo de dados pode ter mais de um anexo com dados.. Sem esse parâmetro, o tipo de conexão padrão, ou seja, data_asset , é carregado Especifique esse parâmetro se o tipo de anexo não for data_asset.. Por exemplo, se um ativo de dados de texto simples tiver um perfil anexado do Natural Language Analysis, ele poderá ser carregado como o tipo de anexo data_profile_nlu.

    Aqui está um exemplo que mostra como carregar os dados de um ativo de dados:

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

  Essa função faz download dos dados de um ativo de dados armazenado e os armazena no arquivo especificado no sistema de arquivos de seu tempo de execução. O arquivo será sobrescrito se já existir.

  A função assume os parâmetros a seguir:

  • asset_name_or_item: (Obrigatório) Uma cadeia com o nome de um ativo de dados armazenados ou um item como aqueles retornados por list_stored_data()..

  • file_name: (Opcional) O nome do arquivo no qual os dados transferidos por download estão armazenados. Ele é padronizado para o nome do anexo do ativo

  • attachment_type_or_item: (Opcional) O tipo de anexo para download. Um ativo de dados pode ter mais de um anexo com dados.. Sem esse parâmetro, o tipo de conexão padrão, ou seja, data_asset , é transferido por download Especifique esse parâmetro se o tipo de anexo não for data_asset.. Por exemplo, se um ativo de dados de texto simples tiver um perfil anexado do Natural Language Analysis, ele poderá ser transferido por download carregado como tipo de anexo data_profile_nlu.

    Aqui está um exemplo que mostra como usar o download_file para tornar seu script R customizado disponível em seu bloco de notas:

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

Salvar dados

As funções para armazenar dados em seu armazenamento de projeto fazem várias coisas:

• Armazenar os dados no armazenamento do projeto
• Adicione os dados como um ativo de dados (criando um ativo ou substituindo um ativo existente) ao seu espaço de trabalho para que você possa ver os dados na lista de ativos de dados no seu espaço de trabalho.
• Associar o ativo ao arquivo no armazenamento.

É possível usar as seguintes funções para salvar dados:

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

  Essa função salva os dados na memória para o armazenamento do espaço de trabalho.

  A função assume os parâmetros a seguir:

  • asset_name_or_item: (Obrigatório) O nome do ativo ou item de lista criado que é retornado por list_stored_data(). Você pode usar o item se quiser sobrescrever um arquivo existente.

  • data: (Necessário) Os dados para fazer upload. O tipo de dados esperado é raw

  • overwrite: (Opcional) Sobrescreve os dados de um ativo de dados armazenados se ele já existir. Padroniza para "False". Se um item de ativo for transmitido em vez de um nome, o comportamento será sobrescrever o ativo

  • mime_type: (Opcional) O tipo MIME para o ativo criado. Por padrão, o tipo MIME é determinado a partir do sufixo do nome do ativo Se você usar nomes de ativos sem um sufixo, especifique o tipo MIME aqui.. Por exemplo, mime_type=application/text para dados de texto simples. Esse parâmetro é ignorado ao sobrescrever um ativo

  • file_name(Opcional) O nome do arquivo a ser usado no armazenamento do espaço de trabalho. Os dados são salvos no armazenamento associado ao espaço de trabalho. Ao criar um novo recurso, o nome do arquivo é derivado do nome do recurso, mas pode ser diferente. Se você desejar acessar o arquivo diretamente, será possível especificar um nome de arquivo Esse parâmetro é ignorado ao sobrescrever um ativo

    Aqui está um exemplo que mostra como salvar dados em um arquivo:

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

  Essa função salva os dados no sistema de arquivos em tempo de execução em um arquivo associado ao seu espaço de trabalho.

  A função assume os parâmetros a seguir:

  • file_path: (Obrigatório) O caminho para o arquivo no sistema de arquivos.

  • asset_name: (Opcional) O nome do ativo de dados que é criado. Ele assume como padrão o nome do arquivo a ser transferido por upload.

  • file_name(Opcional) O nome do arquivo que é criado no armazenamento associado ao espaço de trabalho. Ele assume como padrão o nome do arquivo a ser transferido por upload.

  • overwrite: (Opcional) Substitui um arquivo existente no armazenamento. Padroniza para "False".

  • mime_type: (Opcional) O tipo MIME para o ativo criado. Por padrão, o tipo MIME é determinado a partir do sufixo do nome do ativo Se você usar nomes de ativos sem um sufixo, especifique o tipo MIME aqui.. Por exemplo, mime_type='application/text' para dados de texto simples. Esse parâmetro é ignorado ao sobrescrever um ativo

    Aqui está um exemplo que mostra como você pode carregar um arquivo no espaço de trabalho:

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

Obter informações de conexão

É possível usar a função a seguir para acessar os metadados de conexão de uma determinada conexão

• get_connection(name_or_item)

  Essa função retorna as propriedades (metadados) de uma conexão que você pode usar para buscar dados da origem de dados de conexão. Use wslib$show(connprops) para visualizar as propriedades.. A chave especial "." no item da lista retornado fornece informações sobre o ativo de conexão..

  A função usa o seguinte parâmetro necessário:

  • name_or_item: Uma sequência com o nome de uma conexão ou um item como aqueles retornados por list_connections()

  Observe que quando você trabalha com blocos de notas, é possível clicar em Ler dados no painel Fragmentos de código para gerar código para carregar dados de uma conexão em um pandas DataFrame por exemplo.

Obter informações de dados conectados

É possível usar a função a seguir para acessar os metadados de um ativo de dados conectado.

• get_connected_data(name_or_item)

  Esta função retorna as propriedades de um ativo de dados conectado, incluindo as propriedades da conexão subjacente.. Use wslib$show() para visualizar as propriedades.. A chave especial "." na lista retornada fornece informações sobre dados e ativos de conexão.

  A função usa o seguinte parâmetro necessário:

  • name_or_item: uma sequência com o nome de um ativo de dados conectado ou um item como aqueles retornados por list_connected_data().

  Observe que ao trabalhar com blocos de notas, é possível clicar em Ler dados no painel Fragmentos de código para gerar código para carregar dados de um ativo de dados conectado em um pandas DataFrame por exemplo.

Acessar ativo por ID em vez de nome

Você deve, de preferência, sempre acessar ativos de dados e conexões por um nome exclusivo. Os nomes de ativos não são necessariamente sempre exclusivos e as funções do ibm-watson-studio-lib levantarão uma exceção quando um nome for ambíguo É possível renomear ativos de dados na UI para resolver o conflito.

É possível acessar os ativos por uma ID exclusiva, mas não é recomendável, pois as IDs são válidas apenas no espaço de trabalho atual e quebrarão o código quando transferidas para um espaço de trabalho diferente. Isso pode acontecer, por exemplo, quando projetos são exportados e reimportados. É possível obter o ID de um ativo de conexão, conectado ou armazenado usando a função de lista correspondente, por exemplo, list_connections().

O ponto de entrada wslib$by_id fornece as seguintes funções:

• get_connection(asset_id)

  Esta função acessa uma conexão pelo ID do ativo de conexão..

• get_connected_data(asset_id)

  Essa função acessa um ativo de dados conectado pelo ID do ativo de dados conectado..

• load_data(asset_id, attachment_type_or_item = NULL)

  Essa função carrega os dados de um ativo de dados armazenado passando o ID do ativo. Consulte load_data() para obter uma descrição dos outros parâmetros que você pode transmitir.

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

  Essa função salva dados em um ativo de dados armazenado passando o ID do ativo. Isso implica em overwrite=TRUE Consulte save_data() para obter uma descrição dos outros parâmetros que você pode transmitir

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

  Essa função faz download dos dados de um ativo de dados armazenado passando o ID do ativo. Consulte download_file() para obter uma descrição dos outros parâmetros que você pode transmitir

Acessar armazenamento de projeto diretamente

É possível buscar dados do armazenamento de projetos e armazenar dados no armazenamento de projetos sem sincronizar os ativos do projeto usando o ponto de entrada wslib$storage.

O ponto de entrada wslib$storage fornece as seguintes funções:

• fetch_data(filename)

  Esta função retorna os dados em um arquivo como um buffer de bytes O arquivo não precisa ser registrado como ativo de dados..

  A função usa o seguinte parâmetro necessário:

  • filename: O nome do arquivo no projeto.

• store_data(filename, data, overwrite = FALSE)

  Essa função salva dados na memória para o armazenamento, mas não cria um novo ativo de dados A função retorna uma lista que contém o nome do arquivo, caminho do arquivo e informações adicionais. Use Use wslib$show() para imprimir as informações..

  A função assume os parâmetros a seguir:

  • filenamenome do arquivo no armazenamento do espaço de trabalho: (Obrigatório) O nome do arquivo no armazenamento do espaço de trabalho.
  • data: (Necessário) Os dados para salvar como um objeto bruto.
  • overwrite: (Opcional) Substitui os dados de um arquivo no armazenamento se ele já existir. Por padrão, isso é configurado como false

• download_file(storage_filename, local_filename = NULL)

  Esta função faz download dos dados em um arquivo no armazenamento e os armazena no arquivo local especificado. O arquivo local será sobrescrito se já existir.

  A função assume os parâmetros a seguir:

  • storage_filename: (Obrigatório) O nome do arquivo no armazenamento para download.
  • local_filename: (Opcional) O nome do arquivo no sistema de arquivos local de seu tempo de execução para o qual o arquivo foi transferido por download. Omita esse parâmetro para usar o nome de arquivo do armazenamento

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

  Essa função registra o arquivo no armazenamento como um ativo de dados no seu espaço de trabalho. Esta operação falhará se um ativo de dados com o mesmo nome já existir. Você pode usar essa função se tiver arquivos muito grandes que não podem ser carregados por meio de save_data(). Você pode fazer upload de arquivos grandes diretamente para o bucket do IBM Cloud Object Storage do seu projeto, por exemplo, por meio da interface do usuário, e depois registrá-los como ativos de dados usando ' register_asset().

  A função assume os parâmetros a seguir:

  • storage_path: (Obrigatório) O caminho do arquivo no armazenamento.
  • asset_name: (Opcional) O nome do ativo criado. Ele é padronizado para o nome de arquivo
  • mime_type: (Opcional) O tipo MIME para o ativo criado. Por padrão, o tipo MIME é determinado a partir do sufixo do nome do ativo Use este parâmetro para especificar um tipo MIME se o nome do arquivo não tiver uma extensão de arquivo ou se você desejar configurar um tipo MIME diferente
  Nota: é possível registrar um arquivo várias vezes como um ativo de dados diferente.. Excluir um desses ativos no projeto também exclui o arquivo no armazenamento, o que significa que outras referências do ativo para o arquivo podem ser quebradas.

Suporte do Spark:

O ponto de entrada wslib$spark fornece funções para acessar arquivos no armazenamento com Spark.

O ponto de entrada wslib$spark fornece as seguintes funções:

• provide_spark_context(sc)

  Use esta função para ativar o suporte do Spark

  A função usa o seguinte parâmetro necessário:

  • sc: O SparkContext Ele é fornecido no tempo de execução do bloco de anotações.

    O exemplo a seguir mostra como configurar o suporte do Spark:

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

• get_data_url(asset_name)

  Essa função retorna um URL para acessar um arquivo no armazenamento do Spark via Hadoop.

  A função usa o seguinte parâmetro necessário:

  • asset_name: O nome do ativo.

• storage.get_data_url(file_name)

  Essa função retorna um URL para acessar um arquivo no armazenamento do Spark via Hadoop. A função espera o nome do arquivo, e não o nome do ativo.

  A função usa o seguinte parâmetro necessário:

  • file_name: o nome de um arquivo no armazenamento de projeto..

Procurar ativos do projeto

O ponto de entrada wslib$assets fornece acesso genérico somente leitura a ativos de qualquer tipo. Para os tipos de ativos selecionados, há funções dedicadas que fornecem dados adicionais

As seguintes convenções de nomenclatura se aplicam:

• As funções denominadas list_<something> retornam uma lista de listas nomeadas Cada lista contida representa um ativo e inclui um pequeno conjunto de propriedades (metadados) que identifica o ativo.
• As funções denominadas get_<something> retornarão uma única lista nomeada com as propriedades para o ativo

Para imprimir uma lista ou lista de listas nomeadas, use wslib$show().

As funções esperam o nome de um ativo ou um item de uma lista como o parâmetro. Por padrão, as funções retornam apenas um subconjunto das propriedades do ativo disponíveis Ao configurar o parâmetro raw_info=TRUE, é possível obter o conjunto completo de propriedades do ativo

O ponto de entrada wslib$assets fornece as seguintes funções:

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

  Esta função lista todos os ativos para o tipo fornecido com relação às restrições fornecidas

  A função assume os parâmetros a seguir:

  • asset_type: (Obrigatório) O tipo dos ativos a serem listados, por exemplo data_asset. Consulte list_asset_types() para obter uma lista dos tipos de ativos disponíveis.. Use o tipo de ativo asset para obter a lista de todos os ativos disponíveis no espaço de trabalho.

  • name: (Opcional) O nome do ativo a ser listado Use esse parâmetro se mais de um ativo com o mesmo nome existir.. É possível especificar apenas name e query

  • query: (Opcional) Uma string de consulta que é passada para a API Data and AI Common Core para pesquisar ativos. É possível especificar apenas name e query

  • selector: (Opcional) Uma função de filtro customizado nos itens da lista de ativos candidatos Se a função seletora retornar TRUE, o ativo será incluído na lista de ativos retornados.

  • raw_info: (Opcional) Retorna todos os metadados disponíveis. Por padrão, o parâmetro é configurado para FALSE , e apenas um subconjunto das propriedades é retornado

    Exemplos de uso da função 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)

  Esta função lista todos os tipos de ativos disponíveis..

  A função pode usar o seguinte parâmetro:

  • raw_info: (Opcional) Retorna o conjunto completo de metadados. Por padrão, o parâmetro é FALSE e apenas um subconjunto das propriedades é retornado

• list_datasource_types(raw_info = FALSE)

  Esta função lista todos os tipos de origem de dados disponíveis

  A função pode usar o seguinte parâmetro:

  • raw_info: (Opcional) Retorna o conjunto completo de metadados. Por padrão, o parâmetro é FALSE e apenas um subconjunto das propriedades é retornado

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

  A função retorna os metadados de um ativo.

  A função assume os parâmetros a seguir:

  • name_or_item: (Necessário) O nome do ativo ou um item como aqueles retornados por list_assets()

  • asset_type: (Opcional) O tipo do ativo Se o parâmetro name_or_item contiver uma sequência para o nome do ativo, a configuração asset_type será necessária..

  • raw_info: (Opcional) Retorna o conjunto completo de metadados. Por padrão, o parâmetro é FALSE e apenas um subconjunto das propriedades é retornado

    Exemplo de uso das funções list_assets e 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)

  Essa função retorna os metadados de uma conexão.

  A função assume os parâmetros a seguir:

  • name_or_item: (Obrigatório) O nome da conexão ou um item como aqueles retornados por list_connections()
  • with_datasourcetype: (Opcional) Retorna informações adicionais sobre o tipo de origem de dados da conexão.
  • raw_info: (Opcional) Retorna o conjunto completo de metadados. Por padrão, o parâmetro é FALSE e apenas um subconjunto das propriedades é retornado

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

  Essa função retorna os metadados de um ativo de dados conectado.

  A função assume os parâmetros a seguir:

  • name_or_item: (Necessário) O nome do ativo de dados conectado ou um item como aqueles retornados por list_connected_data()
  • with_datasourcetype: (Opcional) Retorna informações adicionais sobre o tipo de origem de dados do ativo de dados conectado associado.
  • raw_info: (Opcional) Retorna o conjunto completo de metadados. Por padrão, o parâmetro é FALSE e apenas um subconjunto das propriedades é retornado

• get_stored_data(name_or_item, raw_info = FALSE)

  Esta função retorna os metadados de um ativo de dados armazenado..

  A função assume os parâmetros a seguir:

  • name_or_item: (Necessário) O nome do ativo de dados armazenados ou um item como aqueles retornados por list_stored_data()
  • raw_info: (Opcional) Retorna o conjunto completo de metadados. Por padrão, o parâmetro é FALSE e apenas um subconjunto das propriedades é retornado

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

  Esta função retorna uma lista dos anexos de um ativo..

  A função assume os parâmetros a seguir:

  • name_or_item_or_asset: (necessário) O nome do ativo ou um item como aqueles retornados por list_stored_data() ou get_asset().

  • asset_type: (Opcional) O tipo do ativo Ele é padronizado como data_asset.

  • raw_info: (Opcional) Retorna o conjunto completo de metadados. Por padrão, o parâmetro é FALSE e apenas um subconjunto das propriedades é retornado

    Exemplo de uso da função list_attachments para ler um anexo de um ativo de dados armazenado:

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