Crie uma app Node.js no ambiente flexível do App Engine

Crie uma app Node.js no ambiente flexível do App Engine

ID da região

O REGION_ID é um código abreviado que a Google atribui com base na região que seleciona quando cria a sua app. O código não corresponde a um país ou uma província, embora alguns IDs de regiões possam parecer semelhantes aos códigos de países e províncias usados frequentemente. Para apps criadas após fevereiro de 2020, REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criadas antes desta data, o ID da região é opcional no URL.

Saiba mais acerca dos IDs de regiões.

OK

Nota: se estiver a implementar um novo serviço Web Node.js no Google Cloud, recomendamos que comece com o Cloud Run.

Este início rápido demonstra como criar e implementar uma app que apresenta uma mensagem curta. Pode usar a aplicação de exemplo neste início rápido para qualquer versão suportada do Node.js, especificando a versão do tempo de execução e o sistema operativo no ficheiro app.yaml.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Funções necessárias

Para receber as autorizações de que precisa para concluir este início rápido, peça ao seu administrador que lhe conceda as seguintes funções do IAM:

• Administrador do App Engine (roles/appengine.appAdmin) no projeto
• Editor do Cloud Build (roles/cloudbuild.builds.editor) no projeto
• Administrador de objetos de armazenamento (roles/storage.objectAdmin) no projeto
• Visualizador de registos (roles/logging.viewer) no projeto
• Utilizador da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço
• Peça ao seu administrador para conceder as seguintes funções à conta de serviço predefinida do App Engine:
  • Leitor do Artifact Registry (roles/artifactregistry.reader) no projeto
  • Conta de serviço do Cloud Build (roles/cloudbuild.builds.builder) no projeto
  • Visualizador de objetos do Storage (roles/storage.objectViewer) no projeto

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Pré-requisitos adicionais

1. Inicialize a app do App Engine com o seu projeto e escolha a respetiva região:

   gcloud app create --project=[YOUR_PROJECT_ID]
   

   Quando lhe for pedido, selecione a região onde quer localizar a sua aplicação do App Engine.

   Aviso: não pode alterar a região de uma app depois de a definir.

2. Instale o seguinte na sua máquina local:

   • Transfira e instale o Git.
   • Prepare o seu ambiente para o desenvolvimento de Node.js.

Localizações do App Engine

O App Engine é regional, o que significa que a infraestrutura que executa as suas apps está localizada numa região específica e é gerida pela Google para estar disponível de forma redundante em todas as zonas dessa região.

O cumprimento dos requisitos de latência, disponibilidade ou durabilidade são fatores principais para selecionar a região onde as suas apps são executadas. Geralmente, pode selecionar a região mais próxima dos utilizadores da sua app, mas deve considerar as localizações onde o App Engine está disponível, bem como as localizações dos outrosGoogle Cloud produtos e serviços que a sua app usa. A utilização de serviços em várias localizações pode afetar a latência da sua app, bem como os respetivos preços.

Não pode alterar a região de uma app depois de a definir.

Nota: duas localizações, denominadas europe-west e us-central nos comandos do App Engine e na Google Cloud consola, são denominadas europe-west1 e us-central1, respetivamente, noutras partes da documentação da Google.

Se já tiver criado uma aplicação do App Engine, pode ver a respetiva região através de uma das seguintes ações:

• Execute o comando gcloud app describe.

• Abra o painel de controlo do App Engine na Google Cloud consola. A região aparece junto à parte superior da página.

OK

Este início rápido demonstra uma aplicação Node.js simples escrita com a estrutura Express.js.

Importante: Para ter a melhor experiência no Windows, atualize para a versão mais recente do gestor de pacotes Node.js (npm) executando npm install -g npm. A versão mais recente npm instala dependências numa estrutura de diretório simples, pelo que é improvável que as instalações entrem em conflito com o comprimento máximo do caminho do Windows de 255 carateres. Se preferir continuar a usar uma versão mais antiga do npm, pode reduzir o comprimento dos caminhos movendo o seu projeto para a raiz do disco, por exemplo, C:\.

Transfira a app Hello World

Criámos uma app Hello World para o App Engine para que possa rapidamente experimentar a implementação de uma app no Google Cloud.

1. Clone o repositório da app de exemplo Hello World para a sua máquina local.

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples
   

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

2. Altere para o diretório que contém o exemplo de código.

      cd nodejs-docs-samples/appengine/hello-world/flexible/
   

Execute o Hello World na sua máquina local

1. Instale as dependências para este projeto.

   npm install
   

   Em alternativa, se estiver a usar o Yarn.

   yarn install
   

2. Execute o guião de início.

   npm start
   

   Em alternativa, se estiver a usar o Yarn.

   yarn start
   

3. Veja a sua app no navegador de Internet.

   • Se estiver a usar o Cloud Shell, na barra de ferramentas, clique em Pré-visualização Web e selecione Pré-visualizar na porta 8080.

   • Se não estiver a usar o Cloud Shell, introduza o seguinte endereço:

   http://localhost:8080

A mensagem Hello World da app de exemplo é apresentada na página. Na janela de terminal, prima Ctrl+C para sair do servidor Web.

Implemente e execute o Hello World no App Engine

Para implementar a sua app no ambiente flexível do App Engine:

1. Implemente a app Hello World executando o seguinte comando a partir do diretório hello-world/flexible/:

   gcloud app deploy

   Saiba mais acerca das sinalizações opcionais.

   Sinalizadores de comandos gcloud comuns

   • Inclua a flag --version para especificar um ID que identifique exclusivamente essa versão da sua app. Caso contrário, é gerado um ID para si. Exemplo: --version [YOUR_VERSION_ID]
   • Inclua a flag --project para especificar um ID do projeto Google Cloud alternativo ao que inicializou como predefinição na ferramenta gcloud. Exemplo: --project [YOUR_PROJECT_ID]

   Exemplo:

   gcloud app deploy --version pre-prod-5 --project my-sample-app

   Para saber como implementar a sua app a partir da linha de comandos, consulte o artigo Testar e implementar a sua app . Para ver uma lista de todas as flags de comando, consulte a gcloud app deploy referência.

   OK
   Nota: Durante a implementação, o npm install é usado por predefinição para instalar dependências, a menos que exista um ficheiro yarn.lock e não esteja listado na secção skip_files do ficheiro app.yaml. Nesse caso, é usado o yarn install --production. Para fazer com que a compilação regresse à versão anterior, npm install elimine o ficheiro yarn.lock ou adicione yarn.lock à secção skip_files do ficheiro app.yaml.

2. Inicie o navegador para ver a app em https://PROJECT_ID.REGION_ID.r.appspot.com

   gcloud app browse

   onde PROJECT_ID representa o seu Google Cloud ID do projeto.

Desta vez, a página que apresenta a mensagem Hello World é fornecida por um servidor Web em execução numa instância do App Engine.

Parabéns! Implementou a sua primeira app do App Engine no ambiente flexível do App Engine!

Se encontrou erros ao implementar a sua aplicação, consulte as sugestões de resolução de problemas.

Consulte as secções seguintes para obter informações sobre a limpeza, bem como links para possíveis passos seguintes que pode seguir.

Limpar

Para evitar incorrer em custos, pode eliminar o seu Google Cloud projeto para parar a faturação de todos os recursos usados nesse projeto.

Atenção: a eliminação de um projeto tem os seguintes efeitos:
• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

O que se segue?

Conheça toda a plataforma

Agora que já sabe como é desenvolver e implementar apps do App Engine, pode explorar o resto do Google Cloud. Já tem a CLI do Google Cloud instalada, o que lhe dá as ferramentas para interagir com produtos como o Cloud SQL, o Cloud Storage, o Firestore e muito mais.

Saiba mais sobre o ambiente flexível do App Engine

Seguem-se alguns tópicos para continuar a aprender sobre o App Engine:

• Uma vista geral do App Engine
• Encaminhamento de pedidos
• Processamento de pedidos
• Gerir instâncias

Revisão do código Olá, mundo

O Hello World é a app do App Engine mais simples possível, uma vez que contém apenas um serviço, tem apenas uma versão e todo o código está localizado no diretório raiz da app. Esta secção descreve detalhadamente cada um dos ficheiros da app.

app.js

O ficheiro app.js contém o código JavaScript para iniciar um servidor e responder a pedidos.

O código seguinte responde a pedidos de clientes Web apresentando a mensagem "Hello World" através de um servidor que é executado na porta 8080.

const express = require('express');

const app = express();

app.get('/', (req, res) => {
  res.status(200).send('Hello, world!').end();
});

// Start the server
const PORT = parseInt(process.env.PORT) || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

app.yaml

O ficheiro app.yaml descreve a seguinte configuração para a sua app:

• Define env: flex, indicando que a sua app usa o ambiente flexível do App Engine.

• Especifica o tempo de execução usado pela app.

  runtime: nodejs
  env: flex
  runtime_config:
    operating_system: ubuntu24
  # This sample incurs costs to run on the App Engine flexible environment.
  # The settings below are to reduce costs during testing and are not appropriate
  # for production use. For more information, see:
  # https://cloud.google.com/appengine/docs/flexible/nodejs/configuring-your-app-with-app-yaml
  manual_scaling:
    instances: 1
  resources:
    cpu: 1
    memory_gb: 0.5
    disk_size_gb: 10
  

  • Para mais informações sobre como funciona o tempo de execução do Node.js, consulte o artigo O tempo de execução do Node.js.

  • Para mais detalhes sobre como criar a sua app para tirar partido das versões e dos serviços, consulte o artigo Uma vista geral do App Engine.

  • Para mais detalhes acerca das definições de configuração do App Engine, consulte o artigo Configurar a sua app com o ficheiro app.yaml.

  package.json

  package.json é usado para especificar dependências de apps, a versão do nó e o arranque da app.

  {
    "name": "appengine-hello-world",
    "description": "Simple Hello World Node.js sample for Google App Engine Flexible Environment.",
    "version": "0.0.2",
    "private": true,
    "license": "Apache-2.0",
    "author": "Google Inc.",
    "repository": {
      "type": "git",
      "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
    },
    "engines": {
      "node": ">=16.0.0"
    },
    "scripts": {
      "start": "node app.js",
      "test": "c8 mocha -p -j 2 --exit test/*.test.js"
    },
    "dependencies": {
      "express": "^4.17.1"
    },
    "devDependencies": {
      "c8": "^10.0.0",
      "mocha": "^10.0.0",
      "supertest": "^7.0.0"
    }
  }
  

  No exemplo anterior, o ficheiro package.json especifica que a app usa a versão 18 e posterior do Node.js e depende do express. Para mais detalhes sobre como instalar e executar a sua app, consulte a documentação de tempo de execução do Node.js.