Esta página foi traduzida pela API Cloud Translation.

Opções de arranque do proxy de serviço extensível

OpenAPI | gRPC

O proxy de serviço extensível (ESP) é um proxy baseado no NGINX que permite que os Cloud Endpoints ofereçam funcionalidades de gestão de APIs. Configura o ESP especificando opções quando inicia o contentor do Docker do ESP. Quando o contentor do ESP é iniciado, executa um script denominado start_esp, que escreve o ficheiro de configuração do NGINX através das opções que especificou e inicia o ESP.

Especifica as opções de arranque do ESP no comando docker run, por exemplo:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

Se estiver a implementar o ESP no Kubernetes, especifica as opções de arranque no ficheiro de manifesto de implementação no campo args, por exemplo:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

A tabela seguinte descreve as opções de arranque do ESP.

Opção curta	Opção longa	Descrição
`-s SERVICE_NAME`	`--service SERVICE_NAME`	Define o nome do serviço Endpoints.
`-R ROLLOUT_STRATEGY`	`--rollout_strategy ROLLOUT_STRATEGY`	Disponível na versão 1.7.0 e posteriores do ESP. Especifique `managed` ou `fixed`. A opção `--rollout_strategy=managed` configura o ESP para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar. Não precisa de especificar a opção `--version` quando define `--rollout_strategy` como `managed`.
`-v CONFIG_ID`	`--version CONFIG_ID`	Define o ID da configuração do serviço a ser usado pelo ESP. Consulte o artigo Obter o nome do serviço e o ID de configuração para ver as informações necessárias para definir esta opção. Quando especifica `--rollout_strategy=fixed` ou quando não inclui a opção `--rollout_strategy`, tem de incluir a opção `--version` e especificar um ID de configuração. Neste caso, sempre que implementar uma nova configuração dos Endpoints, tem de reiniciar o ESP com o novo ID de configuração.
`-p HTTP1_PORT`	`--http_port HTTP1_PORT`	Define as portas que o ESP expõe para ligações HTTP/1.x.¹
`-P HTTP2_PORT`	`--http2_port HTTP2_PORT`	Define as portas que o ESP expõe para ligações HTTP/2.¹
`-S SSL_PORT`	`--ssl_port SSL_PORT`	Define as portas que o ESP expõe para ligações HTTPS.¹
`-a BACKEND`	`--backend BACKEND`	Define o endereço do servidor de back-end da aplicação HTTP/1.x. O valor predefinido do endereço de back-end é `http://127.0.0.1:8081`. Pode especificar um prefixo de protocolo, por exemplo: `--backend=https://127.0.0.1:8000` Se não especificar um prefixo de protocolo, a predefinição é `http`. Se o servidor de back-end estiver em execução no Compute Engine num contentor, pode especificar o nome do contentor e a porta, por exemplo: `--backend=my-api-container:8000` Para especificar que o back-end aceita tráfego gRPC, adicione o prefixo `grpc://`. Por exemplo: `--backend=grpc://127.0.0.1:8000` Se o servidor de back-end estiver em execução no Compute Engine num contentor, e aceitar tráfego gRPC, pode especificar o nome do contentor e a porta, por exemplo: `--backend=grpc://my-api-container:8000`
`-N STATUS_PORT`	`--status_port STATUS_PORT`	Define a porta de estado (predefinição: `8090`).
nenhum	`--disable_cloud_trace_auto_sampling`	Por predefinição, o ESP seleciona uma amostra de cada 1000 pedidos ou 1 pedido de cada 10 segundos com o Cloud Trace. Defina esta flag para desativar essa amostragem automática. O Cloud Trace continua a poder ser ativado a partir de cabeçalhos HTTP de pedidos com contexto de rastreio, independentemente do valor desta flag. Consulte o artigo Monitorizar a sua API para mais informações.
`-n NGINX_CONFIG`	`--nginx_config NGINX_CONFIG`	Define a localização do ficheiro de configuração do NGINX personalizado. Se especificar esta opção, o ESP obtém o ficheiro de configuração especificado e, em seguida, inicia imediatamente o NGINX com o ficheiro de configuração personalizado fornecido. Consulte o artigo Usar uma configuração nginx personalizada para o GKE para mais informações.
`-k SERVICE_ACCOUNT_KEY`	`--service_account_key SERVICE_ACCOUNT_KEY`	Define o ficheiro JSON das credenciais da conta de serviço. Se forem fornecidas, o ESP usa a conta de serviço para gerar um token de acesso para chamar as APIs da infraestrutura de serviços. Só tem de especificar esta opção quando o ESP estiver a ser executado em plataformas que não sejam o Google Cloud, como o seu computador local, o Kubernetes ou outro fornecedor de nuvem. Consulte o artigo Criar uma conta de serviço para mais informações.
`-z HEALTHZ_PATH`	`--healthz HEALTHZ_PATH`	Defina um ponto final de verificação de funcionamento nas mesmas portas que o back-end da aplicação. Por exemplo, `-z healthz` faz com que o ESP devolva o código `200` para a localização `/healthz`, em vez de encaminhar o pedido para o back-end. Predefinição: não usado.
nenhum	`--dns DNS_RESOLVER`	Especifique um resolvedor de DNS. Por exemplo, o `--dns 169.254.169.254` usa o servidor de metadados da GCP como o resolvedor de DNS. Se não for especificado, o valor predefinido é `8.8.8.8`.

¹ Estas portas são opcionais e têm de ser distintas. Se não especificar nenhuma opção de porta, o ESP aceita ligações HTTP/1.x na porta 8080. Para ligações HTTPS, o ESP espera que os segredos TLS estejam localizados em /etc/nginx/ssl/nginx.crt e /etc/nginx/ssl/nginx.key.

Exemplos de invocações da linha de comandos

Os exemplos seguintes mostram como usar alguns dos argumentos da linha de comandos:

Para iniciar o ESP para processar pedidos recebidos na porta HTTP/1.x 80 e na porta HTTPS 443 e enviar os pedidos para o back-end da API em 127.0.0.1:8000:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1
     --service=echo-api.endpoints.example-project-12345.cloud.goog \
        --rollout_strategy=managed \
        --http_port=80 \
        --ssl_port=443 \
        --backend=127.0.0.1:8000

Para iniciar o ESP com uma configuração NGINX personalizada através do ficheiro de credenciais da conta de serviço para obter a configuração do serviço e estabelecer ligação ao controlo de serviços:

sudo docker run \
    --detach \
    --volume=$HOME/Downloads:/esp \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=echo-api.endpoints.example-project-12345.cloud.goog \
    --rollout_strategy=managed \
    --service_account_key=/esp/serviceaccount.json \
    --nginx_config=/esp/nginx.conf

Tenha em atenção que tem de usar as flags do Docker --volume ou --mount para montar o ficheiro JSON que contém a chave privada para a conta de serviço e o ficheiro de configuração do NGINX personalizado como volumes no contentor do Docker do ESP. O exemplo anterior mapeia o diretório $HOME/Downloads no computador local para o diretório esp no contentor. Quando guarda o ficheiro de chave privada da conta de serviço, este é normalmente transferido para o diretório Downloads. Se quiser, pode copiar o ficheiro de chave privada para outro diretório. Consulte o artigo Faça a gestão de dados no Docker para mais informações.

Adicionar compatibilidade com CORS ao ESP

Consulte o artigo Compatibilidade com CORS para ver uma descrição das opções de compatibilidade com CORS disponíveis. Esta secção descreve a utilização de flags de arranque do ESP para suportar o CORS.

Para ativar a compatibilidade com CORS no ESP, inclua a opção --cors_preset e defina-a como basic ou cors_with_regex. Quando inclui --cors_preset=basic ou --cors_preset=cors_with_regex, o ESP:

Assume que todos os caminhos de localização têm a mesma política de CORS.
Responde a pedidos simples e a pedidos de pré-envio HTTP OPTIONS.
Coloca em cache o resultado do pedido de verificação prévia OPTIONS durante um máximo de 20 dias (1728000 segundos).

Define os cabeçalhos das respostas para os seguintes valores:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
Access-Control-Expose-Headers: Content-Length,Content-Range

Para substituir o valor predefinido de Access-Control-Allow-Origin, especifique uma das seguintes opções:

Opção	Descrição
`--cors_allow_origin`	Use com `--cors_preset=basic` para definir `Access-Control-Allow-Origin` para uma origem específica. Exemplo: `--cors_preset=basic --cors_allow_origin=http://example.com`
`--cors_allow_origin_regex`	Use com `--cors_preset=cors_with_regex`. Permite usar uma expressão regular para definir `Access-Control-Allow-Origin`. Exemplo: `--cors_preset=cors_with_regex --cors_allow_origin_regex=^https?://.+\.example\.com$` A expressão regular no exemplo anterior permite uma origem com `http` ou `https` e qualquer subdomínio de `example.com`.

Depois de definir --cors_preset=basic ou --cors_preset=cors_with_regex para ativar o CORS, pode substituir os valores predefinidos dos outros cabeçalhos de resposta especificando uma ou mais das seguintes opções:

Opção	Descrição
`--cors_allow_methods`	Define `Access-Control-Allow-Methods` para os métodos HTTP especificados. Especifique os métodos HTTP como uma string com cada método HTTP separado por uma vírgula. Exemplo: `--cors_preset=basic --cors_allow_methods=GET,POST,PUT,OPTIONS`
`--cors_allow_headers`	Define `Access-Control-Allow-Headers` para os cabeçalhos HTTP especificados. Especifique os cabeçalhos HTTP como uma string com cada cabeçalho HTTP separado por uma vírgula. Exemplo: `--cors_preset=basic --cors_allow_headers=Origin,Content-Type,Accept`
`--cors_allow_credentials`	Inclui o cabeçalho `Access-Control-Allow-Credentials` com o valor `true` nas respostas. Por predefinição, o cabeçalho `Access-Control-Allow-Credentials` não está incluído nas respostas. Exemplo: `--cors_preset=basic --cors_allow_credentials`
`--cors_expose_headers`	Define `Access-Control-Expose-Headers` para os cabeçalhos especificados. Especifique que cabeçalhos podem ser expostos como parte da resposta como uma string com cada cabeçalho separado por uma vírgula. Exemplo: `--cors_preset=basic --cors_expose_headers=Content-Length`

Se as opções de arranque do CORS do ESP não se adequarem às necessidades da sua aplicação, pode criar um ficheiro nginx.conf personalizado com a compatibilidade com o CORS de que a sua aplicação precisa. Para mais informações, consulte o artigo Criar um nginx.conf personalizado para suportar CORS.

O que se segue?

Saiba mais acerca do:

Implementar o ESP e o back-end da API em Google Cloud
Executar o ESP localmente ou noutra plataforma
O script start_esp no GitHub