Como implantar um app Node.js independente

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Neste tópico, explicamos como implantar um aplicativo Node.js do seu sistema local na Apigee Edge. Neste tópico, discutiremos como usar uma ferramenta de linha de comando chamada apigeetool para implantar aplicativos Node.js na Apigee Edge.

Sobre a implantação do código Node.js no Apigee Edge

É possível implantar um aplicativo atual da API Node.js, incluindo todos os módulos Node.js dependentes, do seu sistema local no Apigee Edge usando um utilitário de linha de comando chamado apigeetool. O utilitário agrupa o aplicativo e as dependências dele automaticamente em um proxy de API e o implanta no Edge.

Por exemplo, digamos que você tenha usado o Express para criar um aplicativo da Web em Node.js. O aplicativo é executado como um servidor HTTP que detecta solicitações HTTP, processa essas solicitações, retorna dados e assim por diante. Quando você usa o apigeetool para implantar um aplicativo Node.js no Edge, ele é encapsulado em um proxy e executado no contexto da plataforma Edge. Depois, é possível chamar o aplicativo usando o novo URL de proxy e agregar valor a ele "preparando-o" com recursos padrão do Edge, como segurança OAuth, políticas de cota, políticas de proteção contra ameaças, fluxos condicionais, armazenamento em cache e muitos outros.

O que a Apigeetool faz?

Quando você executa o utilitário apigeetool com a opção deploynodeapp, ele:

  • Gera um pacote de configurações de proxy de API para hospedar o aplicativo Node.js.
  • Empacota o aplicativo Node.js com qualquer pacote do Node.js instalado com os módulos empacotados de nós (NPM, na sigla em inglês).
  • Importa o pacote de configuração do proxy de API para a organização especificada no Apigee Edge usando a API de gerenciamento de borda.
  • Implanta o proxy de API em um ambiente.
  • Executa o aplicativo Node.js no Apigee Edge e o disponibiliza pela rede.

Como se preparar para usar o apigeetool

Antes de começar, você precisa instalar o utilitário apigeetool.

É possível instalar a apigeetool por meio do npm ou clonando e vinculando o código do GitHub.

Instalação pelo npm

O módulo apigeetool e as dependências dele foram projetados para Node.js e estão disponíveis por meio do npm usando o seguinte comando:

$ sudo npm install -g apigeetool

Normalmente, a opção -g coloca módulos em: /usr/local/lib/node_modules/apigeetool em máquinas baseadas em *nix.

Instalação pelo GitHub

Faça o download ou clone as APIs Platform Tools no GitHub. Consulte o arquivo README no diretório raiz do repositório para conferir instruções de instalação.

$ git clone https://github.com/apigee/apigeetool-node.git

Quando concluir a instalação, verifique se o executável apigeetool está no seu caminho. Para testar, digite:

$ apigeetool -h

Como implantar um aplicativo Node.js no Edge com o apigeetool

Observação: antes de implantar, você precisa saber o nome da organização do Apigee Edge, o nome de usuário e a senha da sua conta do Apigee Edge. Você precisa dessas informações para formar corretamente o comando apigeetool.

Para implantar um aplicativo Node.js usando apigeetool:

  1. Em uma janela de terminal, cd o diretório raiz do aplicativo Node.js.
  2. Execute o utilitário apigeetool com o comando deploynodeapp:

    $ apigeetool deploynodeapp -n {A name for your new proxy} -d {The root directory of your Node.js app} -m {The name of the main Node.js file} -o {Your org name on Edge} -e {The environment to deploy to} -b {The base URL for your proxy} -u {Your Edge email address} -p {Your Edge password}
    
    Por exemplo:

    $ apigeetool deploynodeapp -n myNodeApp -d . -m server.js -o myorg -e test -b /myNodeApp -u ntesla -p myPassword
    
  3. Verifique a saída na janela de terminal. Ele vai ter esta aparência:

    Importing new application myNodeApp
    Imported new app revision 1
    Deploying revision 1
      Deployed.
    Proxy: "myNodeApp" Revision 1
      Environment: test BasePath: /myNodeApp
      Status: deployed
    

    Se aparecer "Status: implantado", é isso. Tudo correu bem. Seu app Node.js está encapsulado em um proxy de API, implantado no Edge e está em execução e aguardando para processar solicitações. Está pronto para ser testado.

  4. Teste o proxy. Por exemplo:

    $ curl http://myorg-test.apigee.net/myNodeApp
    Hello, My Node App!
    
  5. Se quiser, faça login na sua conta do Apigee Edge e acesse a página "Proxies de API" na interface de gerenciamento. Seu novo proxy vai aparecer listado lá.

Como a apigeetool lida com arquivos e módulos dependentes

Se o aplicativo Node.js depender dos módulos instalados, a apigeetool vai compactar a pasta node_modules e adicioná-la ao pacote de proxy para processá-los. Nenhuma outra ação é necessária. O mesmo vale para qualquer diretório que contenha código-fonte adicional. O utilitário apigeetool os compacta e os implanta com o pacote.

Não é possível editar arquivos nesses diretórios compactados no editor da interface de gerenciamento do Edge. Se precisar alterá-los, você poderá exportar o projeto, editar os arquivos localmente e reimplantá-los usando a Apigeetool ou importando o projeto exportado usando a interface de gerenciamento. Consulte também "Como exportar e importar um proxy com o código Node.js".

Informações básicas de uso do apigeetool

Para informações básicas de uso sobre os parâmetros de entrada do utilitário apigeetool, insira:

$ apigeetool deploynodeapp -h

  Usage: deploynodeapp -n [name] -o [organization] -e [environment]
  -d [directory name] -m [main script file]
  -u [username] -p [password]
  -b [base path] -l [apigee API url] -z [zip file] -i -h
  -o Apigee organization name
  -e Apigee environment name
  -n Apigee proxy name
  -d Apigee proxy directory
  -m Main script name: Should be at the top level of the directory
  -u Apigee user name
  -p Apigee password
  -b Base path (optional, defaults to /)
  -L Apigee API URL (optional, defaults to https://api.enterprise.apigee.com)
  -z ZIP file to save (optional for debugging)
  -i import only, do not deploy
  -R Resolve Node.js modules on Apigee Edge. Equivalent to running npm install on your project. 
  -U Uploads Node.js modules to Apigee Edge. 
  -h Print this message

Como criar um novo proxy com arquivos Node.js atuais

Outra maneira de integrar um aplicativo Node.js existente a um proxy de API é adicionar o aplicativo ao criar o proxy. É possível fazer isso inteiramente na interface de gerenciamento e na caixa de diálogo "New API Proxy".

  1. Na página de resumo do proxy de API, clique em +Proxy de API.
  2. Na caixa de diálogo "Novo proxy de API", selecione Node.js existente.
  3. Use o botão Escolher arquivos para selecionar um ou mais arquivos Node.js a serem importados.
  4. Dê um nome ao proxy. Neste exemplo, estamos chamando de hellonode.
  5. Adicione a versão /v1 ao caminho base do projeto. O controle de versões da API é uma prática recomendada.
  6. Clique em Build.
  7. Clique em Desenvolver para entrar na visualização de desenvolvimento.
  8. Abra o arquivo TargetEndpoint no editor de código.
  9. Verifique se o elemento <ScriptTarget> especifica o arquivo Node.js principal da seguinte maneira:


    <ScriptTarget>
            <ResourceURL>node://server.js</ResourceURL>
            <Properties/>
    </ScriptTarget>
    
  10. Clique em Salvar.

Adicionar e invocar novos arquivos de recursos do Node.js

Outra maneira de adicionar o código Node.js a um proxy é adicioná-lo diretamente, seja por meio da IU ou fazendo upload dele a partir do seu sistema de arquivos local. Também é possível especificar qual arquivo Node.js é o principal, que é o arquivo que o Edge invoca quando o proxy é implantado.

Como adicionar novos arquivos Node.js por meio da IU

A IU de gerenciamento permite adicionar outros arquivos de origem Node.js a um proxy que está na plataforma Edge. Você pode criá-los diretamente na interface ou importá-los do sistema de arquivos. Primeiro, vamos ver como fazer isso na IU.

Para criar um novo arquivo de recurso do Node.js:

  1. Na visualização "Desenvolver", selecione Novo script no menu "Novo".
  2. Na caixa de diálogo "Adicionar script", selecione o tipo de arquivo e dê um nome ao script.
  3. Clique em Adicionar.

O novo arquivo Node.js em branco é aberto no editor. Recorte e cole seu código no arquivo. O arquivo também aparece na seção "Scripts" do Navigator.

[[{"type":"media","view_mode":"media_large","fid":"2431","attributestiralt":"","class":"media-image","height":"312","typeof":"foaf:Image","width":"417"}}]]

Como importar arquivos Node.js do seu sistema de arquivos

Para import um arquivo Node.js do seu sistema de arquivos para o proxy:

  1. Na visualização "Desenvolver", selecione Novo script no menu "Novo".
  2. Na caixa de diálogo "Adicionar script", clique em Importar script.
  3. Use a ferramenta de arquivos para selecionar seu arquivo Node.js.
  4. O nome do arquivo é adicionado à caixa de diálogo, mas você pode alterá-lo, se quiser.
  5. Clique em Adicionar. O arquivo aparece na seção "Scripts" do navegador e é aberto no editor.
  6. Clique em Salvar.

Se você quiser invocar o arquivo importado, é necessário realizar uma etapa extra, conforme explicado na próxima seção.

Como invocar um arquivo Node.js importado

Não é possível simplesmente invocar um arquivo Node.js recém-importado ou criado. O motivo é que o Edge exige que um arquivo Node.js seja o arquivo main. O arquivo principal é especificado no elemento <ScriptTarget> da definição do endpoint de destino. Para especificar qual é o arquivo Node.js principal, faça o seguinte:

  1. Em "Pontos de destino de destino", no navegador, clique no nome do endpoint de destino, que geralmente é chamado de padrão.
  2. No editor de código, edite o elemento <ScriptTarget> alterando o <ResourceURL> para refletir o nome do arquivo que você quer que seja o arquivo Node.js principal. Por exemplo, se você quiser que um arquivo chamado hello-world.js seja o arquivo principal, insira: node://hello-world.js no elemento ResourceURL.
  3. Clique em Salvar.

Nesse ponto, você pode invocar o arquivo com qualquer caminho de proxy que tenha usado antes. Estivemos no exemplo do Hello World!, em que o caminho base v1/hello é especificado. Mas você pode mudar o caminho base editando o endpoint do proxy.

  1. Em "Endpoints de proxy" no Navegador, clique no nome do endpoint de proxy (geralmente chamado de padrão).
  2. No editor de código, edite o elemento <HttpProxyConnection> alterando <BasePath> para o nome que você quiser. Por exemplo, se o <BasePath> atual for v1/hello e você quiser que seja v1/my-node-file, mude o elemento <BasePath> da seguinte forma:

    <BasePath>/v1/my-node-file</BasePath>
  3. Clique em Salvar.
  4. Invoque o proxy usando o novo caminho base, desta maneira:

    $ curl http://myorg-test.apigee.net/v1/my-node-file
    Hello, World!
    

Como exportar e importar um proxy com o código Node.js

Depois de implantar um proxy com o código Node.js no Edge, você poderá exportar o proxy de volta para o sistema, trabalhar nele e importá-lo novamente para o Edge usando a IU de gerenciamento. Esse tipo de técnica de desenvolvimento de ida e volta é muito usada.

  1. Na página de resumo do proxy de API, clique em Desenvolver.
  2. Na página "Desenvolver", selecione Fazer o download da revisão atual.
  3. Descompacte o arquivo transferido por download no seu sistema.

Para importar o pacote de proxy de volta para o Edge, selecione Import Into New Revision no mesmo menu.

Também é possível usar a API para implantar proxies. Para mais detalhes, consulte Como implantar proxies a partir da linha de comando.

Próximas etapas

No próximo tópico, Como adicionar o Node.js a um proxy de API atual, explicamos como adicionar um app Node.js a um proxy atual no seu sistema de arquivos e implantá-lo no Edge.