Consumir um aplicativo implantado em Clusters de Big Data do SQL Server usando um serviço Web RESTful

Aplica-se a: SQL Server 2019 (15.x)

Este artigo descreve como consumir um aplicativo implantado em um cluster de Big Data do SQL Server usando um serviço Web RESTful.

Importante

O complemento Clusters de Big Data do Microsoft SQL Server 2019 será desativado. O suporte para Clusters de Big Data do SQL Server 2019 será encerrado em 28 de fevereiro de 2025. Todos os usuários existentes do SQL Server 2019 com Software Assurance terão suporte total na plataforma e o software continuará a ser mantido por meio de atualizações cumulativas do SQL Server até esse momento. Para obter mais informações, confira a postagem no blog de anúncio e as opções de Big Data na plataforma do Microsoft SQL Server.

Prerequisites

• Cluster de Big Data do SQL Server
• CLI de Dados do Azure (azdata)
• Um aplicativo implantado usando azdata ou a Extensão de implantação de aplicativo

Observação

Quando o arquivo de especificação YAML do aplicativo especifica um agendamento, o aplicativo será disparado por meio de um trabalho cron. Se o cluster de Big Data for implantado no OpenShift, o início do trabalho cron exigirá recursos adicionais. Confira os detalhes sobre considerações de segurança no OpenShift para obter instruções específicas.

Funcionalidades

Depois de implantar um aplicativo em seu Clusters de Big Data do SQL Server 2019, você pode acessar e consumir esse aplicativo usando um serviço Web RESTful. Isso permite a integração desse aplicativo usando outros aplicativos ou serviços (por exemplo, um aplicativo móvel ou site). A tabela a seguir descreve os comandos de implantação do aplicativo que você pode usar com azdata para obter informações sobre o serviço Web RESTful para seu aplicativo.

Comando	Descrição
azdata app describe	Descrever o aplicativo.

Obtenha ajuda com o parâmetro --help como no seguinte exemplo:

azdata app describe --help

As seções a seguir descrevem como recuperar um ponto de extremidade para um aplicativo e como trabalhar com o serviço Web RESTful para integração de aplicativos.

Recuperar o ponto de extremidade

Os Clusters de Big Data fornecem pontos de extremidade que você pode acessar e consumir o aplicativo usando um serviço Web RESTful. O principal objetivo é facilitar a interação com outros aplicativos Web ou móveis e ser mais proativo para essas arquiteturas de microsserviços. O comando azdata app describe fornece informações detalhadas sobre o aplicativo, incluindo o ponto de extremidade no cluster. Normalmente, isso é usado por um desenvolvedor de aplicativos para criar um aplicativo usando o cliente do Swagger e usando o serviço Web para interagir com o aplicativo de maneira semelhante ao RESTful.

Descreva seu aplicativo executando um comando semelhante ao seguinte exemplo:

azdata app describe --name add-app --version v1

{
  "input_param_defs": [
    {
      "name": "x",
      "type": "int"
    },
    {
      "name": "y",
      "type": "int"
    }
  ],
  "links": {
    "app": "https://10.1.1.3:30080/app/addpy/v1",
    "swagger": "https://10.1.1.3:30080/app/addpy/v1/swagger.json"
  },
  "name": "add-app",
  "output_param_defs": [
    {
      "name": "result",
      "type": "int"
    }
  ],
  "state": "Ready",
  "version": "v1"
}

Observe o endereço IP (neste exemplo, 10.1.1.3) e o número da porta (30080) na saída.

Uma das outras maneiras de obter essas informações é clicar com o botão direito do mouse em Gerenciar no servidor no Azure Data Studio, em que você encontrará os pontos de extremidade dos serviços listados.

Gerar um token de acesso JWT

Para acessar o serviço Web RESTful do aplicativo que você implantou, primeiro é preciso gerar um token de acesso JWT. A URL para o token de acesso depende da versão do cluster de Big Data.

Versão	URL
GDR1	https://[IP]:[PORT]/docs/swagger.json
CU1 e posteriores	https://[IP]:[PORT]/api/v1/swagger.json

Considerando a saída do exemplo anterior, a versão CU4 e o endereço IP do controlador (10.1.1.3 no exemplo) e o número da porta (30080), a URL seria assim:

   https://10.1.1.3 :30080/api/v1/swagger.json

Para obter informações sobre a versão, confira Histórico de versões.

Abra a URL adequada em seu navegador usando o endereço IP e a porta que você recuperou executando o comando describe acima. Entre com as mesmas credenciais usadas para o azdata login.

Cole o conteúdo de swagger.json no Editor de Swagger para entender quais métodos estão disponíveis:

Observe que o app é o método GET e para obter o token usaria o método POST. Como a autenticação para aplicativos usa tokens JWT, você precisará obter um token usando sua ferramenta favorita a fim de fazer uma chamada POST para o método token. Com o mesmo exemplo, a URL para obter o token JWT se pareceria com o seguinte:

   https://10.1.1.3 :30080/api/v1/token

Veja um exemplo de como fazer exatamente isso no Postman:

A saída dessa solicitação fornecerá um access_token JWT, que será necessário para chamar a URL e executar o aplicativo.

Executar o aplicativo usando o serviço Web RESTful

Há várias maneiras de consumir um aplicativo nos Clusters de Big Data do SQL Server: você pode optar por usar o comando azdata app run. Esta seção demonstrará como usar ferramentas para desenvolvedores comuns, como o Postman, para executar o aplicativo.

Você pode abrir a URL para o swagger que foi retornado quando você executou azdata app describe --name [appname] --version [version] em seu navegador, que deve ser semelhante a https://[IP]:[PORT]/app/[appname]/[version]/swagger.json.

Observação

Você precisará fazer login com as mesmas credenciais usadas para azdata login. Com o mesmo exemplo, o comando ficaria assim:

   azdata app describe --name add-app --version v1

O conteúdo do swagger.json que você pode colar no Editor de Swagger. Você verá que o serviço Web expõe o método run e, nos bastidores, ele passou pelo proxy de aplicativo, que é uma API Web que autentica usuários e roteia as solicitações para os aplicativos. Observe que a URL base é exibida na parte superior. Você pode usar a ferramenta de sua escolha para chamar o método run (https://[IP]:30778/api/app/[appname]/[version]/run), passando os parâmetros no corpo da solicitação POST como JSON.

Neste exemplo, usaremos o Postman. Antes de fazer a chamada, você precisará definir a Authorization como Bearer Token e colar o token recuperado anteriormente. Isso definirá um cabeçalho em sua solicitação. Veja a captura de tela abaixo.

Depois disso, no corpo da solicitação, passe os parâmetros para o aplicativo que você está chamando e defina content-type como application/json:

Ao enviar a solicitação, você receberá a mesma saída de quando executou o aplicativo por meio de azdata app run:

Você chamou o aplicativo com êxito usando o serviço Web. Você pode seguir etapas semelhantes para integrar esse serviço Web ao seu aplicativo.

Próximas etapas

Explore como Monitorar aplicativos em clusters de Big Data para obter mais informações. Confira também mais amostras em Amostras de implantação de aplicativo.

Para saber mais sobre Clusters de Big Data do SQL Server, confira O que são Clusters de Big Data do SQL Server 2019.