Tutoriais hospedados dos Destinos

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

Os tutoriais a seguir explicam como implantar aplicativos Node.js no Edge usando Destinos hospedados, um ambiente de execução Node.js nativo hospedado pela Apigee.

Os tutoriais percorrem as seguintes tarefas:

Implantar um app Node.js em destinos hospedados usando a interface do usuário do Edge

Neste tutorial, você implantará um app Node.js simples nos destinos hospedados usando a IU do Edge. Ao concluir o tutorial, você entenderá a estrutura básica e o conteúdo de um proxy de destinos hospedados e como acessar arquivos de registro de implantação e criação.

Fazer login

  1. Acesse: apigee.com/edge.
  2. Insira suas credenciais de login da Apigee para fazer login.

Criar um proxy

  1. No menu de navegação lateral, selecione Desenvolver > Proxies de API.
  2. Clique em + Proxy.
  3. Na página "Criar proxy", selecione Destino hospedado.
  4. Clique em Next.
  5. No campo "Proxy Name", insira hello-hosted-targets.
  6. Verifique se a opção Exemplo"Hello World" está selecionada.
  7. Clique em Next.
  8. Na página "Segurança", selecione Passar (nenhum) para a autorização.
  9. Clique em Next.
  10. Clique em Next.
  11. Na página "Criar", verifique se o ambiente de teste está selecionado. Observe que o tipo de proxy é Hosted Targets.
  12. Clique em Build and Deploy. A implantação do proxy pode levar alguns instantes para ser concluída.
  13. Depois que o proxy for implantado, clique em Ver proxy hello-hosting-targets na parte inferior da página.
  14. Chame o proxy de API. A maneira mais fácil de fazer isso é acessar a guia Trace, iniciar uma sessão do Trace e clicar em Send. Você receberá um status 200 com a seguinte resposta:
    {"date":"2018-09-26T14:23:04.550Z","msg":"Hello, World!"}

Examinar o proxy

  1. Na IU do Edge, clique na guia Desenvolver.
  2. No Navegador, selecione default em "Target Endpoints".
  3. No editor de código, observe que há um elemento filho <HostedTarget/> vazio no elemento <TargetEndpoint>. Essa tag vazia é obrigatória. Ele informa ao Edge que o destino do proxy é um aplicativo implantado no ambiente de Hosted Destinos.

  4. No navegador, observe o conteúdo na seção Scripts. Os arquivos do app Node.js estão listados sob o rótulo hospedado.

  5. Na interface do Edge, examine os arquivos listados em host em Scripts:
    • O arquivo app.yaml contém informações de configuração. Por exemplo, é possível adicionar variáveis de ambiente que vão estar disponíveis para o aplicativo Node.js no ambiente de execução. Não é necessário modificar o arquivo para este exemplo.
    • O index.js é o arquivo principal do app Node.js.
    • Se o app tiver alguma dependência de módulo, ela precisará ser listada em package.json.

Ver arquivos de registro

Os arquivos de registros do aplicativo podem ser úteis para depurar problemas que ocorrem durante a fase de build e também durante a execução.

  1. Na IU do Edge, clique na guia Desenvolver.
  2. Para ver o registro do build, clique em Registros da versão.
  3. Para ver o registro de implantação, clique em Registros do ambiente de execução.

    Consulte também Como acessar arquivos de registros.

Resumo

  • Você implantou um aplicativo Node.js simples no ambiente de destinos hospedados e o testou na IU do Edge.
  • Você aprendeu que um proxy de destinos hospedados exige uma tag vazia especial no endpoint de destino chamada <HostedTarget/>.
  • Você aprendeu que o Edge carrega dependências de módulo automaticamente e que as dependências precisam ser listadas no arquivo package.json.
  • e a verificar os arquivos de registro de build e ambiente de execução.

Implantar o Node.js do seu sistema no Edge

Nesta seção, explicamos como implantar um aplicativo Node.js autônomo do seu sistema local em destinos hospedados usando o apigeetool. O utilitário apigeetool agrupa o app Node.js em um novo proxy de destinos hospedados e o implanta no Edge.

Instalar o apigeetool

O apigeetool é a maneira recomendada para os desenvolvedores implantarem código de proxy no Edge. Para instalar o apigeetool, execute o seguinte comando do NPM:

npm install -g apigeetool

Criar o app Node.js

Para facilitar, o código para um aplicativo Node.js simples é fornecido a você.

  1. Crie um diretório para o app Node.js. Chame o diretório node-hosting-express.
  2. cd para o novo diretório.
  3. Crie um arquivo chamado index.js e copie o código para ele.
  4. var express = require('express')
    var app = express()
    
    app.get('/', function(req, res) {
        res.json({
            hello: "Hello World!"
        })
    })
    
    app.get('/hello/:name', function(req, res) {
        var name = req.params.name
        res.json({
            hello: "hello " + name
        })
    })
    
    var server = app.listen(process.env.PORT || 9000, function() {
        console.log('Listening on port %d', server.address().port)
    })
    
  5. Crie um arquivo chamado package.json e copie o código a seguir para ele. Observe que o módulo expresso está listado como uma dependência.
  6. {
        "name": "hello-world",
        "version": "1.0.0",
        "main": "index.js",
        "scripts": {
            "start": "node index.js --use_strict"
        },
        "author": "",
        "license": "",
        "dependencies": {
            "express": "^4.16.0"
        }
    }
    
  7. Crie um arquivo chamado app.yaml e copie este código para ele:
  8. runtime: node
    runtimeVersion: 8
    application: my-express-app
    env:
      - name: NODE_ENV
        value: production
      - name: LOG_LEVEL
        value: 3
    
  9. Verifique se o diretório é semelhante a este:
    ls
    app.yaml index.js package.json
    

Análise da estrutura de diretórios necessária para o código do app

Seu aplicativo Node.js precisa ter a mesma estrutura de um aplicativo Node.js padrão. No entanto, certifique-se de seguir estes requisitos antes de implantar com apigeetool no Edge:

  • O arquivo de manifesto app.yaml é obrigatório e precisa existir no diretório raiz do seu app. Para saber mais sobre esse arquivo, consulte o arquivo de manifesto.
  • Um arquivo package.json é obrigatório. Ele precisa listar todas as dependências exigidas pelo app.
  • Uma pasta node_modules não é necessária. O Edge executa a instalação do npm para você quando o app Node.js é implantado. Ele recebe as dependências do package.json. A única ocasião em que você precisará fornecer explicitamente node_modules é se tiver módulos personalizados que não estejam disponíveis por meio do npm.

Como implantar o proxy

  1. Em um terminal, cd para acessar o diretório raiz do aplicativo Node.js.
  2. Execute apigeetool com o comando deployhostingtarget com o comando:
  3. apigeetool deployhostedtarget -o org -e env -n proxy-name -b /node-hosted-express -u username

    em que -n é o nome que você quer dar ao novo proxy. Ele precisa ser exclusivo na organização. Os caracteres que você pode usar no nome são restritos ao seguinte: a-z0-9._\-$%

    Exemplo:

    apigeetool deployhostedtarget -o myorg -e test -n node-hosted-express -b /node-hosted-express -u jdoe@apigee.com

    Para mais informações sobre como usar o apigeetool, consulte https://github.com/apigee/apigeetool-node.

Como testar o proxy

Teste o proxy com um comando cURL, com um cliente REST como o Postman ou na interface do usuário do Edge na ferramenta Trace. Confira um exemplo de comando cURL.

curl http://myorg-test.apigee.net/node-hosted-express
     {"date":1506992197427,"msg":"hello-world"}

Como conseguir os registros da versão

Os registros da versão mostram a saída relacionada à implantação e à criação do app Node.js. Consulte também Arquivos de registros.

apigeetool getlogs -u username -o org -e env --hosted-build -n proxy-name

Exemplo:

apigeetool getlogs -u jdoe@apigee.com -o myorg -e test --hosted-build -n node-hosted-express

Como encontrar os registros do ambiente de execução

Os registros do ambiente de execução mostram a saída relacionada ao app em execução. Os registros do ambiente de execução têm o escopo definido para o ambiente e retornam os registros da revisão de proxy implantada no momento. Consulte também Arquivos de registros.

apigeetool getlogs -u username -o org -e env --hosted-runtime -n proxy-name

Exemplo:

apigeetool getlogs -u jdoe@apigee.com -o myorg -e test --hosted-runtime -n node-hosted-express

Como visualizar o proxy na interface do Edge

Após a implantação bem-sucedida, é possível visualizar e editar seu proxy na parte de proxies de API da interface do usuário do Edge.

Como migrar um proxy Node.js para um proxy de destinos hospedados

Nesta seção, explicamos como migrar manualmente um proxy da API Edge que usa a implementação de destino tradicional do Node.js para destinos hospedados. Ele também explica como implantar o proxy depois de realizar as etapas de migração.

As etapas de migração preservam a estrutura, as políticas, os fluxos e outros elementos de configuração do proxy da API. Faça a migração em quatro etapas, conforme descrito abaixo, e implante o proxy migrado com o apigeetool.

Etapa 1: ajustar a estrutura de arquivos proxy

Para ajustar a estrutura de arquivos, o proxy de API precisa estar no seu sistema de arquivos local. Se o proxy estiver implantado no Edge, você precisará fazer o download dele antes de continuar. Na configuração tradicional, o "pacote" de proxy de borda que inclui o código Node.js segue essa estrutura de arquivos. O código do aplicativo Node.js é colocado no diretório resources/node:

apiproxy/
    policies/
    proxies/
    targets/
    resources/
      node/
        Your application code


Para destinos hospedados, coloque o diretório raiz do seu app Node.js em um diretório chamado resources/hosted. Basta criar um novo diretório chamado resources/hosting e mover o conteúdo de resources/node para ele. Em seguida, você pode excluir o diretório resources/node.

apiproxy/
     policies/
     proxies/
     targets/
     resources/
       hosted/
         Your application code

Etapa 2: adicionar o arquivo de manifesto

Crie um arquivo de manifesto chamado app.yaml e coloque-o no diretório apiproxy/resources/hosted.

Veja a seguir um exemplo de arquivo app.yaml. Ele especifica que o ambiente de execução é Node.js (obrigatório). Ela também cria uma variável de ambiente no ambiente de execução (uma variável que pode ser acessada pelo app Node.js). A variável de ambiente é opcional e é mostrada apenas como um exemplo. Para mais detalhes e exemplos, consulte Arquivo de manifesto.

runtime: node
  env:
    - name: NODE_ENV
      value: production


O exemplo a seguir mostra uma estrutura de projeto do Node.js que está no local correto no proxy para a implantação de destinos hospedados:

apiproxy/
   resources/
      hosted/
        index.js
        node_modules/
        app.yaml
        package.json

Etapa 3: verificar se você tem um arquivo package.json

Nos proxies Node.js de borda tradicionais, o package.json era opcional. No entanto, para destinos hospedados, você precisa fornecer um no diretório apiproxy/resources/hosted. Especifique qualquer dependência necessária para o app nesse arquivo.

Etapa 4: modificar o endpoint de destino do proxy

Um proxy Node.js tradicional exige que uma tag chamada <ScriptTarget> esteja presente no arquivo de endpoint de destino (normalmente /apiproxy/targets/default.xml). Para destinos hospedados, você precisa adicionar uma tag vazia chamada <HostedTarget/>. Se houver uma tag ScriptTarget no arquivo, basta removê-la. Exemplo:

    <?xml version="1.0" encoding="UTF-8"?>
    <TargetEndpoint name="default">
       <Description />
       <FaultRules />
       <PreFlow name="PreFlow">
          <Request />
          <Response />
       </PreFlow>
       <PostFlow name="PostFlow">
          <Request />
          <Response />
       </PostFlow>
       <Flows />
       <HostedTarget />
    </TargetEndpoint>
    

Como implantar o proxy

Agora é possível implantar o proxy usando o comando apigeetool deployproxy.

  1. cd para o diretório raiz do proxy: /apiproxy
  2. Use este comando para implantar o proxy:
  3. apigeetool deployproxy -u username -o org -e env -n proxy-name -d .

    Exemplo:

    apigeetool deployproxy -u jdoe -o docs -e test -n hello-world -d .

Para mais informações sobre como usar o apigeetool, consulte: https://github.com/apigee/apigeetool-node/blob/master/README.md (em inglês).

Como testar o proxy

Teste o proxy com um comando cURL, com um cliente REST como o Postman ou na interface do usuário do Edge na ferramenta Trace. Confira um exemplo de comando cURL:

curl http://myorg-test.apigee.net/hello-world
Hello,World!