Importação da Azure Cosmos DB

  • Artigo

Importante

O suporte para o Estúdio de ML (clássico) terminará a 31 de agosto de 2024. Recomendamos a transição para o Azure Machine Learning até essa data.

A partir de 1 de dezembro de 2021, não poderá criar novos recursos do Estúdio de ML (clássico). Até 31 de agosto de 2024, pode continuar a utilizar os recursos existentes do Estúdio de ML (clássico).

A documentação do Estúdio de ML (clássico) está a ser descontinuada e poderá não ser atualizada no futuro.

Este artigo descreve como usar o módulo de Dados de Importação em Machine Learning Studio (clássico), para importar dados da Azure Cosmos DB para uso numa experiência de aprendizagem automática.

Nota

Aplica-se a: Machine Learning Studio (clássico) apenas

Módulos semelhantes de arrasto e queda estão disponíveis em Azure Machine Learning designer.

O Azure Cosmos DB suporta o armazenamento da base de dados NoSQL, utilizando um modelo de dados flexível. As vantagens de usar as APIs SQL nesta loja de dados para machine learning incluem desempenho rápido e previsível, escala automática, distribuição global e capacidades de consulta ricas.

Juntamente com Base de Dados SQL do Azure, esta opção permite filtrar dinamicamente conjuntos de dados de entrada.

Saiba como funciona: Saiba mais sobre a Azure Cosmos DB

  • Para começar com machine learning usando dados da Azure Cosmos DB, você deve ter acesso a uma conta DB Azure Cosmos existente contendo uma coleção de documentos relacionados.

Nota

A interface de utilizador em Machine Learning Studio (clássico) ainda usa o nome DocumentDB em muitos lugares. Portanto, pode continuar a ver referências ao DocumentDB, mesmo que a API tenha sido incorporada na Azure Cosmos DB.

Como utilizar dados de importação com Azure Cosmos DB

Recomendamos vivamente que perfile os seus dados antes de importar, para garantir que o esquema é o esperado. O processo de importação digitaliza alguns números de linhas de cabeça para determinar o esquema, mas linhas posteriores podem conter colunas extras, ou dados que causam erros.

Importar dados usando o assistente

O módulo apresenta um novo assistente para o ajudar a escolher uma opção de armazenamento, selecionar entre as subscrições e contas existentes e configurar rapidamente todas as opções.

  1. Adicione o módulo de Dados de Importação à sua experiência. Pode encontrar o módulo em Entrada e Saída de Dados.

  2. Clique em Lançar Assistente de Dados de Importação e siga as instruções.

  3. Quando a configuração estiver concluída, para copiar os dados na sua experiência, clique com o botão direito no módulo e selecione Executar Selecionado.

Dica

Se necessitar de editar uma ligação de dados existente, o assistente carrega todos os detalhes de configuração anteriores. Não tens de começar de novo do zero.

Definir manualmente propriedades no módulo de dados de importação

Os seguintes passos descrevem como configurar manualmente a fonte de importação.

  1. Adicione o módulo de Dados de Importação à sua experiência. Pode encontrar este módulo na categoria entrada e saída de dados .

  2. Para obter informações, selecione Azure DocumentDB.

    Pode ser necessário fornecer informações de ligação para a base de dados de documentos.

    Dica

    Procure o nome da opção no Machine Learning Studio (clássico) para mudar mais tarde. A funcionalidade de importação não foi afetada pela alteração do nome.

  3. Para o URL endpoint, no Portal Azure, clique em Chaves e copie o conteúdo do campo URI no topo da página.

  4. Para identificação da base de dados, cole o nome da base de dados para utilizar.

    Para obter o nome da base de dados no Portal Azure, clique em Document Explorer. Pode ver a lista de bases de dados e coleções neste painel.

  5. Para a chave DocumentDB, cole numa chave de acesso para a conta.

    Para localizar as teclas, clique em Teclas e, em seguida, copie o conteúdo dos campos CHAVE PRIMÁRIO ou CHAVE SECUNDÁRIA .

  6. Para o ID de recolha, digite o nome da coleção como indicado na base de dados cosmosdb especificada.

  7. Defina uma consulta SQL e condição de filtro nos dados, utilizando as opções de SQL de consulta e SQL de consulta.

    Para SQL consulta, digite uma consulta que define os dados a recuperar da recolha. Recomendamos que utilize o Explorador de Consultas para criar e testar previamente as suas consultas cosmosDB.

    Para SQL parâmetros de consulta, forneça uma expressão no formato JSON que possa ser usada para filtrar dinamicamente os dados devolvidos. Normalmente, fornece-se o valor real do valor do parâmetro ao executar a experiência como parte de um serviço Web.

    Se utilizar um parâmetro, deve definir o nome variável do filtro como parte da cláusula WHERE especificada na caixa de texto de consulta SQL.

    Se não especificar uma expressão de filtro, por predefinição, o valor é definido como "{}", e todos os registos são devolvidos.

    Consulte a secção de Notas Técnicas para exemplos, questões conhecidas e conselhos adicionais sobre SQL consultas no CosmosDB.

  8. Selecione a opção De resultados em cache Utilizar se pretender reutilizar os resultados existentes.

    Se desmarcar esta opção, os dados são lidos a partir da fonte cada vez que a experiência é executada, independentemente de os dados forem os mesmos ou não.

    Machine Learning não pode comparar os dados em cache com os dados da sua conta CosmosDB. Portanto, não há forma de realizar atualizações incrementais a partir de Machine Learning.

    Se quiser re importar apenas quando os dados forem alterando, deve definir essa lógica noutra aplicação, como a Azure Data Factory. Para obter mais informações, consulte os dados de e para a Azure Cosmos DB utilizando a Azure Data Factory.

  9. Executar a experiência, ou selecione apenas o módulo de Dados de Importação e clique em Executar selecionado.

Resultados

Depois de ter executado o módulo ou experiência, pode clicar com o botão direito na saída do módulo para visualizar os resultados em formato tabular.

Para capturar uma imagem instantânea destes dados no seu espaço de trabalho Machine Learning como conjunto de dados, pode clicar corretamente na saída do módulo e selecionar Guardar Como Conjunto de Dados. No entanto, ao fazê-lo, apenas os dados disponíveis no momento da importação. Se se espera que os dados mudem frequentemente, reencaqüentemente os Dados de Importação , se necessário.

Exemplos

Para uma análise detalhada de como usar a Azure Cosmos DB como fonte de dados para a aprendizagem automática, consulte a Galeria Azure AI.

Notas técnicas

Esta secção contém opções de configuração avançadas e respostas a perguntas comumente feitas.

Exemplos de consultas simples e parametrizadas

Suponha que queira usar apenas os dados em vulcões com elevações abaixo dos 3000 metros.

Consulta simples

Cole a seguinte consulta na caixa de texto de consulta SQL:Select * from volcanodb where volcanodb.Elevation < 10000

Neste caso, o valor da expressão do filtro é definido como "{}", e todos os registos são devolvidos.

Consulta parametrizada

Para obter apenas os dados do vulcão relacionados com um país específico, você pode especificar o valor do país como um parâmetro passado para a consulta no tempo de execução. Isto requer estas alterações:

  1. Na caixa de texto de consulta SQL, definir uma variável para aplicar ao Country campo como parte da consulta SQL:

    Select * from volcanodb where volcanodb.Country = @param1

  2. Na caixa de texto de parâmetros de consulta SQL, especifique o nome do parâmetro e o seu valor no formato JSON, como este:

    {"@param1":"Turkey"}

Recursos

Se não tiver uma loja de documentos existente, consulte estes artigos para começar.

Migração de dados e sintaxe de consulta ajudam

Para amostras de consultas numa loja de dados JSON, descarregue a folha de fraude de consulta Azure Cosmos DB.

Se precisar de enviar conteúdo para a Azure Cosmos DB, recomendamos a ferramenta de migração Azure Cosmos DB. Valida, carrega e indexa os seus dados. A ferramenta suporta múltiplas fontes, incluindo MongoDB, Amazon DynamoDB, HBase, SQL Server bases de dados e ficheiros CSV.

Usando consultas sem esquemas

Se os dados forem consistentes e previsíveis, pode utilizar uma sintaxe simples SQL, como SELECT * FROM <document collection>. Isto chama-se consulta sem esquema porque não nomeou os atributos exatos para devolver. Tal consulta devolveria todos os campos e todas as linhas da coleção especificada.

No entanto, não especificar um esquema pode levar a resultados inesperados ou a um erro de tempo de execução se os documentos tiverem esquemas inconsistentes. Isto porque o módulo de Dados de Importação tenta inferir o esquema com base num número pré-determinado de linhas da seguinte forma:

  1. Quando não são especificados atributos, o módulo digitaliza a primeira linha na base de dados CosmosDB.
  2. O módulo cria nomes de colunas com base em atributos e adivinha quais os tipos de dados da coluna que devem basear-se na linha de exemplo.
  3. Se as linhas posteriores contiverem quaisquer atributos novos ou diferentes, é gerado um erro de tempo de execução.

Por isso, recomendamos que especifique sempre os atributos e valores para devolver da loja de dados CosmosDB. Por exemplo, em vez de utilizar a SELECT * sintaxe, recomendamos que nomeie todos os atributos recuperados pela consulta, como este:

SELECT MyTable.Gender, MyTable.Age, MyTable.Name FROM <document collection>

Parâmetros do módulo

A tabela a seguir inclui apenas os parâmetros para o módulo de Dados de Importação que são aplicáveis à opção Azure Cosmos DB.

Name Intervalo Tipo Necessário Predefinição Description
Origem de dados lista HTTP obrigatório nenhum A fonte de dados pode ser HTTP, FTP, HTTPS ou FTPS anónimos, um ficheiro no armazenamento Azure BLOB, uma tabela Azure, uma Base de Dados SQL do Azure, uma tabela Hive, um ponto final OData ou Azure Cosmos dB.
URL de ponto final qualquer string obrigatório nenhum Forneça o URI para o servidor DB Azure Cosmos
ID da base de dados qualquer string obrigatório nenhum Fornecer o nome da base de dados DB Azure Cosmos
Chave DocumentDB qualquer SecureString obrigatório nenhum Forneça uma chave API válida para a conta DB Azure Cosmos
ID da coleção qualquer string obrigatório nenhum Forneça o nome de uma coleção na base de dados DB da Azure Cosmos
Consulta SQL qualquer string obrigatório nenhum Uma consulta SQL especificando registos para regressar da loja de dados Azure Cosmos DB

Saídas

Nome Tipo Description
Conjunto de dados de resultados Tabela de Dados Dataset com dados descarregados

Exceções

Exceção Description
Erro 0003 Uma exceção ocorre se uma ou mais entradas forem nulas ou vazias.
Erro 0029 Uma exceção ocorre quando um URI inválido é passado.
Erro 0002 Ocorre uma exceção se um ou mais parâmetros não puderem ser analisados ou convertidos do tipo especificado para o tipo exigido pelo método-alvo.
Erro 0048 Uma exceção ocorre quando não é possível abrir um ficheiro.
Erro 0049 Uma exceção ocorre quando não é possível analisar um ficheiro.

Para obter uma lista de erros específicos dos módulos Studio (clássicos), consulte Machine Learning Códigos de Erro.

Para obter uma lista de exceções da API, consulte Machine Learning CÓDIGOs de Erro da API REST.

Ver também

Importar Dados
Dados de Exportação
Importar a partir do URL da Web através de HTTP
Importação da Consulta de Colmeia
Importar a partir da Base de Dados SQL do Azure
Importação de Azure Blob Armazenamento
Importação de Fornecedores de Feed de Dados
Importação de Bases de Dados SQL Server de Instalações