Como implantar um app Node.js independente

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

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

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

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

Por exemplo, digamos que você usou 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 apigeetool para implantar um aplicativo Node.js no Edge, ele é envolvido em um proxy e executado no contexto da plataforma Edge. Em seguida, você pode chamar o aplicativo pelo novo URL do proxy e adicionar valor a ele 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 muito mais.

O que o apigeetool faz?

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

  • Gera um pacote de configuração de proxy da API para armazenar o aplicativo Node.js.
  • Empacotar o aplicativo Node.js com todos os pacotes Node.js instalados com o NPM (Node Packaged Modules).
  • Importa o pacote de configuração de proxy da API para a organização especificada no Apigee Edge usando a API de gerenciamento do Edge.
  • 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, instale o utilitário apigeetool.

Você pode instalar o apigeetool pelo npm ou clonando e vinculando o código do GitHub.

Instalação do npm

O módulo apigeetool e as dependências dele foram criados para Node.js e estão disponíveis pelo 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 do GitHub

Faça o download ou clone as ferramentas da plataforma da API do GitHub. Consulte o arquivo README no diretório raiz do repositório para ver as 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, o nome de usuário e a senha da 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 seu 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. Confira a saída na janela do terminal. Ele vai ficar mais ou menos assim:

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

    Se você vir "Status: deployed", é isso. Deu tudo certo. O app Node.js é encapsulado em um proxy de API, implantado no Edge e está em execução e aguardando para processar solicitações. Ele 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. O novo proxy vai aparecer lá.

Como o apigeetool lida com arquivos e módulos dependentes

Se o aplicativo Node.js depender de módulos instalados, o apigeetool vai processá-los compactando a pasta node_modules e adicionando-a ao pacote de proxy. Não é necessário fazer mais nada. O mesmo vale para qualquer diretório que contenha código-fonte adicional. O utilitário apigeetool as compacta e implanta com o pacote.

Não é possível editar arquivos nesses diretórios compactados no editor da interface de gerenciamento do Edge. Se você precisar fazer mudanças, exporte seu projeto, edite os arquivos localmente e reimplante usando o apigeetool ou importe o projeto exportado usando a IU de gerenciamento. Consulte também "Como exportar e importar um proxy com 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, digite:

$ 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 existentes

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

  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 Choose Files para selecionar um ou mais arquivos do Node.js para importar.
  4. Dê um nome ao proxy. Neste exemplo, vamos chamá-lo de hellonode.
  5. Adicione a versão /v1 ao caminho base do projeto. Criar versões da API é uma prática recomendada.
  6. Clique em Build.
  7. Clique em Develop para acessar a visualização Develop.
  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.

Como adicionar e invocar novos arquivos de recurso do Node.js

Outra maneira de adicionar código do Node.js a um proxy é diretamente, seja pela interface ou fazendo upload 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 interface

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

Para criar um novo arquivo de recurso Node.js:

  1. Na visualização "Develop", selecione New Script no menu "New".
  2. Na caixa de diálogo "Add script", selecione o tipo de arquivo Node e nomeie o script.
  3. Clique em Adicionar.

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

[[{"type":"media","view_mode":"media_large","fid":"2431","attributes delesalt":"","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 "Develop", selecione New Script no menu "New".
  2. Na caixa de diálogo "Adicionar script", clique em Importar script.
  3. Use a ferramenta de arquivos para selecionar o arquivo Node.js.
  4. O nome do arquivo é adicionado à caixa de diálogo, mas você pode mudar isso.
  5. Clique em Adicionar. O arquivo aparecerá na seção "Scripts" do navegador e será aberto no editor.
  6. Clique em Salvar.

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

Como invocar um arquivo Node.js importado

Não é possível 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 arquivo é o principal do Node.js, faça o seguinte:

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

Neste ponto, você pode invocar o arquivo com qualquer caminho de proxy usado antes. Por exemplo, analisamos o exemplo Hello World!, em que o caminho base v1/hello é especificado. No entanto, é possível mudar o caminho de base editando o endpoint do proxy.

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

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

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

Exportar e importar um proxy com código Node.js

Depois de implantar um proxy que contém código Node.js no Edge, é possível exportar o proxy de volta para o sistema, trabalhar nele e, em seguida, reimportar para o Edge usando a interface de gerenciamento. Esse tipo de técnica de desenvolvimento de ida e volta é muito usado.

  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 salvo no seu sistema.

É possível importar o pacote de proxy de volta para o Edge selecionando Importar para uma nova revisão no mesmo menu.

Também é possível usar a API para implantar proxies. Consulte Implantar proxies na linha de comando para mais detalhes.

Próximas etapas

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