CURL chega ao N1QL: Consulta de dados JSON externos

O JSON é uma forma útil de transmitir dados. Agora, o N1QL pode consultá-lo graças a uma atualização CURL no Couchbase 5.0. Veja como se conectar a vários pontos de extremidade para fazer exatamente isso.

N1QL tem muitas funções que permitem que você execute uma operação específica. Uma dessas funções que foi adicionada ao novo DP do Couchbase 5.0 é o CURL.

O CURL permite que você use o N1QL para interagir com pontos de extremidade JSON externos, ou seja, APIs Rest que retornam resultados e dados no formato JSON. Essa função permitirá que o N1QL tenha um conjunto conservador de funcionalidades curl incorporadas à linguagem. A interação consiste principalmente na transferência de dados de e para um servidor usando os protocolos http e https. Em resumo, a função CURL no N1QL fornece a você, usuário, um subconjunto da funcionalidade curl padrão (https://curl.haxx.se/docs/manpage.html) em uma linguagem de consulta.

Para recuperar dados de diferentes servidores (como Google Maps, Yahoo Finance etc.), podemos emitir solicitações GET ou HTTP POST usando a função CURL. Isso pode ser visto no diagrama abaixo.

Definição da função

CURL (URL, [opções])

O primeiro argumento é o URL, que representa qualquer URL que aponte para um ponto de extremidade JSON. Somente URLs com o protocolo http:// ou https:// são compatíveis. O redirecionamento está desativado.

Os argumentos de entrada para a função CURL() podem ser tanto valores estáticos quanto expressões N1QL que podem ser avaliadas.

Mais adiante neste artigo, veremos exemplos que consultam a API Geocode do Google, a API Yahoo Finance, a pesquisa de texto completo do Couchbase e a API do Github. O segundo argumento é uma lista de opções. Esse é um objeto JSON que contém uma lista de opções curl e seus valores correspondentes.

Oferecemos suporte a uma variedade de opções que permitem que você interaja com qualquer endpoint de forma eficaz. Em geral, elas podem ser categorizadas em opções relacionadas à segurança e opções gerais. Uma tabela com as opções compatíveis é fornecida no final do artigo.

Recursos/aprimoramentos de segurança para CURL

Com a adição da função CURL, para evitar vulnerabilidades de segurança e controlar e minimizar os riscos associados a ela, várias medidas de segurança foram implementadas.

Uso de certificados CA com a função CURL do N1QL

Os certificados usados pela função N1QL CURL devem ser armazenados em cada nó de consulta dentro do cluster no diretório n1qlcerts. O local onde esse diretório precisa ser criado pelo usuário depende do local da instalação do couchbase. (É específico do sistema operacional). Os exemplos a seguir assumem o local de instalação padrão e mostram onde o diretório n1qlcerts foi criado.

Para os locais de instalação não padrão, o caminho relativo - "../var/lib/couchbase/n1qlcerts directory" do diretório bin no qual o cbq-engine é executado precisa ser criado.

Esse diretório deve ser criado para cada nó de consulta.

Depois que esse diretório tiver sido criado, adicione o certificado a ser usado pelo CURL. Para usar esse certificado, usamos a opção cacert e passamos o nome do certificado.

Por exemplo, se n1qlcerts/user1.pem for o nome do certificado, use a opção cacert -

"cacert": "user1.pem"

Somente os nomes são válidos, os caminhos são inválidos e a passagem de um deles causará um erro. CURL() gera um erro no caso de certificados inválidos e expirados.

OBSERVAÇÃO: o diretório n1qlcerts e seu conteúdo precisam ser replicados para cada nó de consulta dentro do cluster.

Cabeçalhos e agentes de usuário personalizados

CURL() é executado no nó de consulta em um cluster. Isso permite que a função obtenha acesso a todos os pontos de extremidade REST que são acessíveis por meio do serviço de consulta (já que é onde a função é executada). Para evitar o acesso a esses pontos de extremidade inseguros, um cabeçalho personalizado, que não pode ser alterado pelo usuário, é adicionado a todas as solicitações enviadas usando a função curl do N1QL. Ele tem o formato "X-N1QL-User-Agent: couchbase/n1ql/1.7.0-N1QL".

Um agente de usuário também é sempre definido por padrão. Isso pode ser redefinido usando a opção -user-agent. O valor definido por padrão é "couchbase/n1ql/1.7.0-N1QL".

Esses dois valores foram projetados para permitir que os pontos de extremidade internos e externos verifiquem o cabeçalho/agente de usuário e não permitam o acesso em seu código e neguem o acesso à função. A única ressalva ao usar isso, no entanto, é que ainda não podemos proteger contra qualquer software que não verifique esse cabeçalho e as versões existentes do software instalado localmente (software Couchbase e não Couchbase). Para esses casos, o recurso de lista branca do curl foi adicionado (veja abaixo).

Criação de uma Whitelist para restringir o acesso ao CURL.

Uma lista de permissões é um documento JSON que lista os endpoints REST e URLs permitidos para a função CURL() acessar. Os próprios URLs precisam corresponder a um prefixo. O documento da lista branca é criado dentro do diretório n1qlcerts (para saber o local, veja acima) e é denominado curl_whitelist.json (esse nome é fixo e não pode ser alterado pelo usuário). O arquivo (curl_whitelist.json) precisa ser criado pelo administrador (ou por um usuário com acesso à máquina em que o couchbase está instalado).

Se a lista branca não estiver configurada (..../n1qlcerts/curl_whitelist.json doesnt exist) ou se ela existir, mas estiver vazia, a função CURL não poderá ser usada.

Qualquer lista de permissões precisa ter os seguintes campos -

Se o campo all_access for falso, então o uso da função CURL foi totalmente restrito. Para poder usar CURL() com qualquer endpoint no N1QL, o administrador precisa definir allowed_urls e disallowed_urls de acordo. Para permitir o acesso a todas as urls, podemos definir all_access como true. Isso basicamente nos dá acesso total ao CURL.

Digamos, por exemplo, que desejamos permitir o acesso a todos os pontos de extremidade da API do Google Maps, mas restringir o acesso a todos os outros pontos de extremidade. O conteúdo da lista de permissões será o seguinte.

Curl_whitelist.json

Qualquer url em CURL() prefixado por https://maps.googleapis.com/ será permitido.

OBSERVAÇÃO: a lista de permissões precisa ser replicada para cada nó de consulta dentro do cluster.

Acesso baseado em função à função CURL

Um aspecto importante que vale a pena mencionar aqui é que o CURL foi projetado de forma que não possa ser invocado arbitrariamente. Para evitar a injeção de dados de uma fonte externa usando a instrução UPDATE, foi adicionada uma nova função QUERY_EXTERNAL_ACCESS. Somente um usuário atribuído a essa função tem acesso à função CURL. Por padrão, essa associação de função está vazia. A função CURL só pode ser acessada por um FULL_ADMIN ou por qualquer usuário ao qual tenha sido concedida a função QUERY_EXTERNAL_ACCESS pelo FULL_ADMIN. Para versões anteriores do couchbase que não suportam o controle de acesso baseado em função, pode ser usado um bucket protegido por senha. Também para a funcionalidade CURL(), internamente há suporte para um conjunto específico de cifras SSL (MEDIUM ou HIGH). Isso depende da COUCHBASE_SSL_CIPHER_LIST.

Restringir o tamanho do resultado para CURL()

Uma preocupação importante com o uso da função CURL() é quando um usuário cria um arquivo muito longo, com mais de 64 MB, e tenta ler a partir dele. Como os dados são carregados na memória, se o tamanho do resultado não for limitado, o serviço de consulta poderá falhar. Devido a essa possibilidade, o tamanho máximo do resultado para os dados que podem ser retornados por CURL() é de 64 MB (67.108.864 bytes). O usuário pode restringir a quantidade de memória para os resultados CURL usando o parâmetro limite de resultados O valor mínimo (padrão) para a opção result-cap é 20MB (20 971 520 bytes).

Por exemplo, se a consulta definir result-cap como 20 MB - "result-cap":20971520, qualquer resposta que tenha um tamanho maior retornará um erro.

Interação com diferentes desfechos

Vamos ver como consultar diferentes pontos de extremidade usando a função CURL no N1QL.

API de geocodificação do Google Maps

A API de geocodificação do Google Maps permite que você converta endereços estáticos em coordenadas e vice-versa usando uma solicitação HTTP. (Para obter mais informações, consulte https://developers.google.com/maps/documentation/geocoding/intro )

Digamos que você queira pesquisar Santa Cruz na Espanha usando sua chave da API do Google Dev. Para fazer isso, você pode usar a seguinte consulta:

Solicitação de cachos

Consulta correspondente

Essa consulta recupera o endereço e os limites de localização geográfica do endereço, Santa Cruz, ES. Usamos o endereço, os componentes e os principais parâmetros da API REST de geocodificação do Google Maps. A opção "data" representa a opção curl data que representa dados HTTP POST. No entanto, como essa é uma solicitação get, definimos a opção "get" como true. Você pode fornecer valores para todos os parâmetros REST dentro da opção data.

Agora vamos procurar por Half Moon Bay

API do Yahoo Finance

A API do Yahoo Finance permite que você use a linguagem de consulta do Yahoo (YQL) para buscar cotações de ações (como visto em http://meumobi.github.io/stocks%20apis/2016/03/13/get-realtime-stock-quotes-yahoo-finance-api.html ). Abaixo está a instrução YQL SELECT para acessar o estoque da Hortonworks Inc (HDP).

Para obter os resultados em JSON, você pode usar o seguinte URL:

https://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20yahoo.finance.quotes%20where%20symbol%20in%20(%22HDP%22)&format=json&diagnostics=true&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys&callback=

Solicitação de cachos

Consulta correspondente

Para essa consulta, o valor da opção de dados contém os parâmetros REST do Yahoo, q (para a consulta YQL), formato (para retornar dados em JSON) e alguns outros parâmetros.

Pesquisa de texto completo do Couchbase

A Pesquisa de texto completo do Couchbase permite que você aplique a pesquisa difusa aos dados armazenados no Couchbase. Para obter mais informações, consulte https://www.couchbase.com/blog/couchbase-4.5-developer-preview-couchbase-fts/.

Suponha que você crie um índice FTS chamado beers no bucket de amostras de cerveja no Couchbase. Agora você pode pesquisar o tipo de cerveja pale ale usando esse índice, usando a função CURL no N1QL. É importante observar que o FTS atualmente aceita HTTP POST em vez de GET. Para especificar explicitamente o método de solicitação POST, use a opção request.

Solicitação de cachos

Consulta correspondente

Fornecemos várias opções nessa consulta. A opção de cabeçalho permite que você passe um cabeçalho personalizado para o servidor. Content-Type : application/json informa ao servidor que os dados são fornecidos no formato JSON. Se tivermos um bucket protegido por senha no Couchbase, precisaremos passar suas credenciais com a consulta. A opção user pode ser usada para passar um nome de usuário e uma senha separados por dois pontos. A opção request especifica que o método de solicitação POST é usado.

Se você quiser recuperar apenas os documentos da amostra de cerveja que são retornados pela pesquisa acima, poderá escrever uma consulta N1QL JOIN da seguinte forma.

Isso recuperará os IDs dos documentos retornados pela consulta FTS que pesquisa pale ale, juntamente com o total de ocorrências e todos os detalhes do documento correspondente em beer-sample.

API do Github

A API do Github é um pouco diferente das APIs anteriores, pois retorna vários resultados na forma de uma matriz JSON de valores de resultados. Isso pode ser tratado como vários documentos. Consulte os documentos da API do Github em https://developer.github.com/v3/ para obter mais detalhes sobre o que pode ser consultado.

Digamos que você queira descobrir todos os repositórios vinculados a uma conta do Github. A consulta a seguir faz isso

Solicitação de cachos

Consulta correspondente

Se a conta tiver três repositórios, a consulta fornecerá três resultados (aqui eu adicionei o limite 1). A palavra-chave RAW é usada para retornar a matriz de documentos que a consulta retorna, sem um objeto de invólucro. Um ponto que você notará é que a opção de cabeçalho contém o User-Agent com um nome de usuário do github. Isso agora é obrigatório para todas as solicitações de API do Github.

Agora, a partir dessa lista, digamos que você queira saber qual é a url do clone para cada um desses repositórios. A consulta a seguir faz isso

Resumo

Como você pode ver nos exemplos acima, usando a função CURL, os usuários do N1QL agora podem interagir com qualquer API externa que retorne resultados no formato JSON. Isso abre muitas possibilidades. Por exemplo, se o Couchbase contiver dados correspondentes a diferentes hotéis, você poderá usar a API do Google Maps para encontrar locais próximos a cada um dos hotéis correspondentes.

Para ter um ambiente seguro com a adição do CURL(), vários aprimoramentos de segurança foram adicionados. A seguir, uma pequena lista

• O CURL é executado no nó de consulta em um cluster.
• A função CURL está desativada por padrão.
• O CURL suporta apenas HTTP e HTTPS. Todos os outros protocolos estão desativados.
• Não é permitido o redirecionamento de URLs.
• O cabeçalho personalizado para N1QL CURL é "X-N1QL-User-Agent: couchbase/n1ql/1.7.0-N1QL".
• O agente de usuário é "couchbase/n1ql/1.7.0-N1QL".
• Restringe a quantidade de memória para os resultados do CURL usando o limite de resultados. O limite mínimo de resultados será de 20 MB e o limite máximo de resultados será de 64 MB.
• A função FULL_ADMIN permitirá o acesso ao CURL. A função QUERY_EXTERNAL_ACCESS pode ser atribuída a um usuário pelo FULL ADMIN. Isso permitirá que o usuário use a funcionalidade CURL.
• Os certificados devem ser armazenados no computador local - cada nó de consulta em um cluster. Use ..../Couchbase/var/lib/couchbase/n1qlcerts para armazenar certificados. Use cacert para passar o "nome" do certificado a ser usado. Somente os nomes são válidos, os caminhos são inválidos. (A passagem de um caminho causará um erro).
• O CURL gera um erro no caso de certificados inválidos/expirados.
• O usuário pode colocar os pontos de extremidade na "lista branca".

A implementação do CURL no N1QL usa a API libcurl da Golang - https://github.com/andelf/go-curl

Lista de opções disponíveis

Opções de segurança

Outras opções relacionadas à transferência