Vista geral dos mapas de URLs

Google Cloud Os balanceadores de carga de aplicações e a malha de serviços na nuvem usam um Google Cloud recurso de configuração denominado mapa de URLs para encaminhar pedidos HTTP(S) para serviços de back-end ou contentores de back-end.

Por exemplo, com um balanceador de carga da aplicação externo, pode usar um único mapa de URLs para encaminhar pedidos para diferentes destinos com base nas regras configuradas no mapa de URLs:

• Os pedidos de https://example.com/video vão para um serviço de back-end.
• Os pedidos de https://example.com/audio são encaminhados para um serviço de back-end diferente.

• Os pedidos para https://example.com/images são encaminhados para um contentor de back-end do Cloud Storage.

• Os pedidos de qualquer outra combinação de anfitrião e caminho são encaminhados para um serviço de back-end predefinido.

Os mapas de URLs são usados com os seguintes Google Cloud produtos:

• Balanceador de carga de aplicações externo (modos global, regional e clássico)
• Balanceador de carga de aplicações interno (modos regional e entre regiões)
• Cloud Service Mesh, quando o Cloud Service Mesh é implementado com as APIs de balanceamento de carga

Existem dois tipos de recursos de mapa de URLs disponíveis: global e regional.

• Os urlMaps globais são usados por balanceadores de carga de aplicações externos globais, balanceadores de carga de aplicações clássicos, balanceadores de carga de aplicações internos entre regiões e a malha de serviços do Google Cloud.

• Os regionUrlMaps são usados por balanceadores de carga de aplicações externos regionais, balanceadores de carga de aplicações internos regionais e o Cloud Service Mesh.

O tipo de recurso que usa depende do esquema de balanceamento de carga do produto.

Produto	Esquema de balanceamento de carga	Tipo de recurso do mapa de URL	Destinos suportados
Balanceador de carga de aplicações externo global	EXTERNAL_MANAGED	Global	Serviços de back-end, contentores de back-end
Balanceador de carga de aplicações clássico	EXTERNAL	Global	Serviços de back-end, contentores de back-end
Balanceador de carga de aplicações externo regional	EXTERNAL_MANAGED	Regional	Serviços de back-end
Balanceador de carga de aplicações interno entre regiões	INTERNAL_MANAGED	Global	Serviços de back-end
Balanceador de carga de aplicações interno regional	INTERNAL_MANAGED	Regional	Serviços de back-end
Cloud Service Mesh	INTERNAL_SELF_MANAGED	Global	Serviços de back-end
Cloud Service Mesh	INTERNAL_SELF_MANAGED	Regional	Serviços de back-end

Nem todas as funcionalidades do mapa de URLs estão disponíveis para todos os produtos. Os mapas de URLs usados com balanceadores de carga de aplicações externos globais, balanceadores de carga de aplicações externos regionais, balanceadores de carga de aplicações internos e a malha de serviços da nuvem também suportam várias funcionalidades avançadas de gestão de tráfego. Para mais informações acerca destas diferenças, consulte o artigo Comparação de funcionalidades do equilibrador de carga: encaminhamento e gestão de tráfego. Além disso, os mapas de URLs regionais podem ser um recurso designado como um serviço nas aplicações do App Hub.

Como funcionam os mapas de URLs

Quando um pedido chega ao balanceador de carga, este encaminha o pedido para um serviço de back-end ou um contentor de back-end específico com base nas regras definidas no mapa de URLs.

Um serviço de back-end representa uma coleção de back-ends, que são instâncias de uma aplicação ou um microsserviço. Um contentor de back-end é um contentor do Cloud Storage, que é usado frequentemente para alojar conteúdo estático, como imagens.

Para balanceadores de carga de aplicações externos regionais, balanceadores de carga de aplicações internos e Cloud Service Mesh, os destinos possíveis são os seguintes:

• Serviço de back-end predefinido
• Serviço de back-end não predefinido

Além disso, os balanceadores de carga de aplicações externos globais suportam o seguinte:

• Segmento de back-end predefinido
• Contentor de back-end não predefinido

Por exemplo, suponha que tem a seguinte configuração:

• Um endereço IP:
  • Todos os pedidos à sua organização são enviados para o mesmo endereço IP e o mesmo equilibrador de carga.
  • O tráfego é direcionado para diferentes serviços de back-end com base no URL do pedido.
• Dois domínios:
  • example.net tem vídeos de formação.
  • example.org aloja o Website da sua organização.
• Quatro conjuntos de servidores:
  • Um aloja o Website da sua organização (serviço de back-end: org-site).
  • Um aloja o Website de vídeos de formação geral (serviço de back-end: video-site).
  • Um aloja vídeos de formação em alta definição (HD) (serviço de back-end: video-hd).
  • Um aloja vídeos de formação em definição padrão (SD) (serviço de back-end: video-sd).

Quer que aconteça o seguinte:

• Pedidos para example.org (ou qualquer domínio que não seja example.net) para aceder ao serviço de back-end org-site.
• Pedidos para example.net que não correspondem a caminhos mais específicos para aceder ao serviço de back-end video-site.
• Pedidos para example.net/video/hd/* para aceder ao serviço de back-end video-hd.
• Pedidos para example.net/video/sd/* para aceder ao serviço de back-end video-sd.

Um --path-rule para /video/* corresponde a URIs como /video/test1 e /video/test2. No entanto, esta regra de caminho não corresponde ao caminho /video.

Se o equilibrador de carga receber um pedido com /../ no URL, o equilibrador de carga transforma o URL removendo o segmento do caminho antes de .. e responde com o URL transformado. Por exemplo, quando é enviado um pedido para http://example.net/video/../abc, o balanceador de carga responde com um redirecionamento 302 para http://example.net/abc. A maioria dos clientes reage, em seguida, emitindo um pedido para o URL devolvido pelo balanceador de carga (neste caso, http://example.net/abc). Este redirecionamento 302 não é registado no Cloud Logging.

O mapa de URLs permite-lhe configurar este tipo de encaminhamento com base no anfitrião e no caminho.

Exemplo de configuração do serviço de back-end (clique para aumentar).

Nomenclatura do balanceador de carga

Para balanceadores de carga de aplicações, o nome do balanceador de carga é sempre igual ao nome do mapa de URLs. O comportamento de cada Google Cloud interface é o seguinte:

• Google Cloud consola. Se criar um Application Load Balancer através da Google Cloud consola, o mapa de URLs é automaticamente atribuído ao mesmo nome que introduziu para o nome do balanceador de carga.
• CLI do Google Cloud ou API. Se criar um balanceador de carga de aplicações através da CLI gcloud ou da API, introduz um nome à sua escolha ao criar o mapa de URLs. Em seguida, este nome do mapa de URLs é refletido na Google Cloud consola como o nome do balanceador de carga.

Para saber como funciona a nomenclatura dos balanceadores de carga de rede de proxy e dos balanceadores de carga de rede de passagem, consulte o artigo Vista geral dos serviços de back-end: nomenclatura do balanceador de carga.

Componentes do mapa de URLs

Um mapa de URLs é um conjunto de Google Cloud recursos de configuração que direcionam pedidos de URLs para serviços de back-end ou contentores de back-end. O mapa de URLs faz isso através das partes hostname e path para cada URL que processa:

• Um nome do anfitrião é a parte do nome do domínio de um URL; por exemplo, a parte do nome do anfitrião do URL http://example.net/video/hd é example.net.
• Um caminho é a parte de um URL que segue o nome do anfitrião e o número da porta opcional; por exemplo, a parte do caminho do URL http://example.net/video/hd é /video/hd.

Configuração do balanceador de carga com mapa de URL básico (clique para aumentar).

Este diagrama mostra a estrutura dos objetos de configuração do equilíbrio de carga em relação uns aos outros.

Nota: o diagrama não se destina a mostrar o fluxo de processamento dos pedidos.

Controla que serviços de back-end ou contentores de back-end recebem pedidos recebidos através dos seguintes parâmetros de configuração do mapa de URLs:

• Serviço de back-end predefinido ou segmento de back-end predefinido. Quando cria um mapa de URLs, tem de especificar um serviço de back-end predefinido ou um contentor de back-end predefinido, mas não ambos. Esta predefinição representa o serviço de back-end ou o contentor de back-end para o qual Google Cloud direciona pedidos de URLs com qualquer nome de anfitrião, a menos que exista uma regra de anfitrião aplicável.

  Nota: os contentores de back-end não são suportados com equilibradores de carga de aplicações internos e Cloud Service Mesh.

• Regra de anfitrião (hostRules). Uma regra de anfitrião direciona os pedidos enviados para um ou mais nomes de anfitrião associados para um único localizador de caminhos (pathMatchers). A parte do nome de anfitrião de um URL é correspondida exatamente ou correspondida através de expressões regulares com o conjunto de nomes de anfitrião configurados da regra de anfitrião. Numa regra de anfitrião e caminho do mapa de URLs, se omitir o anfitrião, a regra corresponde a qualquer anfitrião pedido. Para direcionar pedidos para http://example.net/video/hd para um correspondente de caminho, precisa de uma única regra de anfitrião que inclua, pelo menos, o nome do anfitrião example.net. Essa mesma regra de anfitrião também pode processar pedidos de outros nomes de anfitriões, mas direcioná-los para o mesmo matcher de caminho.

  Se precisar de direcionar pedidos para diferentes correspondências de caminhos, tem de usar regras de anfitriões diferentes. Duas regras de anfitrião num mapa de URLs não podem incluir o mesmo nome de anfitrião.

  É possível fazer corresponder todos os nomes de anfitrião especificando o caráter universal * na regra de anfitrião. Por exemplo, para os URLs http://example.org, http://example.net/video/hd e http://example.com/audio, todos os três nomes de anfitrião example.org, example.net e example.com podem ser correspondidos especificando * na regra de anfitrião. Também é possível fazer corresponder um nome de anfitrião parcial especificando o caráter universal *. Por exemplo, uma regra de anfitrião *.example.net é correspondida com os nomes de anfitrião news.example.net e finance.example.net.

  Número da porta. Os diferentes equilibradores de carga de aplicações processam os números de porta de forma diferente. No caso do Application Load Balancer interno, pode usar o parâmetro Host rule para especificar um número de porta. Por exemplo, para direcionar pedidos para a porta 8080, defina a regra de anfitrião como example.net:8080.example.net No caso do Application Load Balancer clássico, apenas o nome do anfitrião no URL é considerado quando corresponde a uma regra de anfitrião. Por exemplo, os pedidos para a porta 8080 e a porta 80 correspondem à regra de anfitrião example.net.example.net

  Nota: o equilibrador de carga não valida o valor do nome do anfitrião no URL. Os clientes podem definir valores arbitrários para o nome do anfitrião, por exemplo, definindo o cabeçalho Host. Não deve usar o campo de nome de anfitrião para implementar o controlo de acesso para a sua aplicação.

• Correspondência de caminhos (pathMatchers). Uma correspondência de caminhos é o parâmetro de configuração referenciado por uma regra de anfitrião. Define a relação entre a parte do caminho de um URL e o serviço de back-end ou o contentor de back-end que deve publicar o pedido. Um correspondente de caminho é composto por dois elementos:

  • Serviço de back-end predefinido do Path Matcher ou contentor de back-end predefinido do Path Matcher. Para cada correspondência de caminho, tem de especificar, pelo menos, um serviço de back-end predefinido ou um contentor de back-end predefinido, mas não ambos. Esta predefinição representa o serviço de back-end ou o contentor de back-end para o qual Google Cloud direciona pedidos de URLs cujos nomes de anfitrião correspondem a uma regra de anfitrião associada ao correspondente de caminhos e cujos caminhos de URL não correspondem a nenhuma regra de caminho no correspondente de caminhos.

  • Regras do caminho. Para cada correspondência de caminho, pode especificar uma ou mais regras de caminho, que são pares de chave/valor que mapeiam um caminho de URL para um único serviço de back-end ou contentor de back-end.

    Os operadores de correspondência de padrões flexíveis permitem-lhe fazer corresponder várias partes de um caminho de URL, incluindo URLs parciais e sufixos (extensões de ficheiros), através da sintaxe de carateres universais. Estes operadores podem ser úteis quando precisa de encaminhar o tráfego e executar reescritas com base em caminhos de URL complexos. Também pode associar um ou mais componentes do caminho a variáveis com nomes e, em seguida, fazer referência a essas variáveis ao reescrever o URL. Com as variáveis com nome, pode reordenar e remover componentes do URL antes de o pedido ser enviado para a sua origem. Para ver detalhes, consulte o artigo Carateres universais, expressões regulares e URLs dinâmicos nas regras de caminho.

    Se precisar de capacidades de encaminhamento mais avançadas, por exemplo, se quiser direcionar o tráfego de um URL exclusivo para vários serviços, pode usar regras de encaminhamento em vez de regras de caminho.

  • Regras de trajeto. As regras de encaminhamento podem ser usadas como alternativa às regras de caminho quando precisar de capacidades de encaminhamento de tráfego avançadas, como o encaminhamento de tráfego com base no caminho do URL, nos cabeçalhos HTTP e nos parâmetros de consulta.

    Pode configurar regras de encaminhamento com operadores de correspondência de padrões flexíveis e variáveis denominadas. Estes operadores podem ser úteis quando precisa de encaminhar o tráfego e executar reescritas com base em caminhos de URL complexos. Para ver detalhes, consulte o artigo Carateres universais e operadores de correspondência de padrões em modelos de caminhos para regras de rotas.

    Também pode configurar regras de encaminhamento para serem comparadas com expressões regulares que correspondem ao caminho, aos parâmetros de consulta ou aos cabeçalhos no pedido recebido. Para obter detalhes, consulte o artigo Expressões regulares nas regras de encaminhamento.

Relação entre o nome do anfitrião e a regra do anfitrião

• Um nome de anfitrião só pode referenciar uma regra de anfitrião.

• Uma única regra de anfitrião pode processar vários nomes de anfitriões.

Relação entre a regra de anfitrião e o correspondente de caminhos

• Várias regras de anfitrião podem fazer referência a um único localizador de caminhos.

• Uma regra de anfitrião só pode referenciar um único correspondente de caminho.

Relação entre o URL e o back-end

Cada URL exclusivo é direcionado para apenas um serviço de back-end ou um contentor de back-end. Consequentemente:

• Google Cloud usa a parte do nome do anfitrião de um URL para selecionar uma única regra de anfitrião e o respetivo matcher de caminho referenciado.

• Quando usa regras de caminho num correspondente de caminho, não pode criar mais do que uma regra de caminho para o mesmo caminho. Por exemplo, os pedidos de /videos/hd não podem ser direcionados para mais do que um serviço de back-end ou um contentor de back-end. Os serviços de back-end podem ter grupos de instâncias de back-end ou grupos de pontos finais de rede de back-end (NEGs) em diferentes zonas e regiões, e pode criar contentores de back-end que usam classes de armazenamento multirregionais.

  Para direcionar o tráfego de um URL exclusivo para vários serviços, pode usar regras de encaminhamento em vez de regras de caminho. Se configurar o matcher de caminhos com regras de encaminhamento para correspondências de cabeçalhos ou parâmetros, um URL exclusivo pode ser direcionado para mais do que um serviço ou contentor de back-end, com base no conteúdo dos cabeçalhos ou dos parâmetros de consulta no URL.

  Da mesma forma, para os equilibradores de carga de aplicações externos regionais e o Cloud Service Mesh, os serviços de back-end ponderados nas ações de encaminhamento podem direcionar o mesmo URL para vários serviços de back-end ou contentores, consoante as ponderações definidas no serviço de back-end ponderado.

Mapas de URLs e protocolos

Pode usar o mesmo mapa de URLs, regras de anfitriões e correspondências de caminhos para processar pedidos HTTP e HTTPS enviados pelos clientes, desde que um proxy HTTP de destino e um proxy HTTPS de destino referenciem o mapa de URLs.

Mapa de URL mais simples

O mapa de URLs mais simples tem apenas um serviço de back-end predefinido ou um contentor de back-end predefinido. Não contém regras de anfitrião nem correspondências de caminhos. O serviço de back-end predefinido ou o contentor de back-end predefinido (conforme o que definiu) processa todos os URLs pedidos.

Se definir um serviço de back-end predefinido, Google Cloud direciona os pedidos para os respetivos grupos de instâncias de back-end ou NEGs de back-end de acordo com a configuração do serviço de back-end.

Mapa de URLs sem regras, exceto a predefinição (clique para aumentar).

Ordem das operações

Para um determinado nome de anfitrião e caminho num URL pedido, Google Cloud usa o seguinte procedimento para direcionar o pedido para o serviço de back-end correto ou o contentor de back-end, conforme configurado no seu mapa de URLs:

• Se o mapa de URLs não contiver uma regra de anfitrião para o nome de anfitrião do URL, Google Cloud direciona os pedidos para o serviço de back-end predefinido do mapa de URLs ou para o contentor de back-end predefinido, consoante o que tiver definido.

• Se o mapa de URLs contiver uma regra de anfitrião que inclua o nome do anfitrião do URL, é consultado o matcher de caminhos referenciado por essa regra de anfitrião:

  • Se o matcher de caminhos contiver uma regra de caminho que corresponda exatamente ao caminho do URL, Google Cloud direciona os pedidos para o serviço de back-end ou o contentor de back-end para essa regra de caminho.

  • Se o matcher de caminhos não contiver uma regra de caminho que corresponda exatamente ao caminho do URL, mas contiver uma regra de caminho que termine em /* cujo prefixo corresponda à secção mais longa do caminho do URL, então, o Google Clouddireciona os pedidos para o serviço de back-end ou o contentor de back-end dessa regra de caminho. Por exemplo, para o mapa de URLs que contém duas regras de correspondência de caminhos /video/hd/movie1 e /video/hd/*, se o URL contiver o caminho exato /video/hd/movie1, é comparado com essa regra de caminho.

  • Se nenhuma das condições anteriores for verdadeira, Google Cloud direciona os pedidos para o serviço de back-end predefinido do matcher de caminhos ou para o contentor de back-end predefinido, consoante o que tiver definido.

Restrições de configuração do mapa de URLs

As secções seguintes descrevem determinadas restrições de configuração para os componentes do mapa de URLs.

Correspondências de expressões regulares nas regras de anfitrião e de encaminhamento

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais do Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

As regras de anfitrião permitem-lhe fazer corresponder a parte do URL referente ao nome do anfitrião ao conjunto de nomes de anfitriões configurados da regra de anfitrião. Pode optar por usar um nome de anfitrião específico ou um caráter universal * no campo hostRules[].hosts[] para corresponder ao nome de anfitrião no pedido recebido.

As regras de encaminhamento permitem-lhe definir regras de correspondência que podem corresponder a uma expressão regular no caminho, na string de consulta ou num cabeçalho no pedido recebido. As regras de encaminhamento suportam a utilização de expressões regulares para os seguintes campos do mapa de URLs:

• pathMatchers[].routeRules[].matchRules[].regexMatch: uma expressão regular usada para fazer corresponder o caminho do pedido recebido.
• pathMatchers[].routeRules[].matchRules[].headerMatches[].regexMatch: Uma expressão regular que contém um predicado que corresponde a um cabeçalho do pedido recebido.
• pathMatchers[].routeRules[].matchRules[].queryParameterMatches[].regexMatch: Uma expressão regular que contém um predicado que corresponde a um parâmetro de consulta do pedido recebido.

Considera-se que um pedido correspondeu a uma routeRule quando qualquer uma das matchRules for satisfeita. No entanto, os predicados numa determinada matchRule têm uma semântica AND. Ou seja, todos os predicados numa matchRule têm de corresponder para que o pedido corresponda à regra.

Notas de utilização adicionais:

• As expressões regulares só são suportadas para os seguintes produtos:

  • Balanceadores de carga de aplicações internos regionais
  • Balanceadores de carga de aplicações internos entre regiões
  • Balanceadores de carga de aplicações externos regionais

  Os equilibradores de carga de aplicações globais e clássicos não suportam expressões regulares.

• Tem de usar a sintaxe RE2 para criar as suas expressões regulares. Para ver a lista completa de limitações e operadores permitidos em mapas de URLs, consulte as especificações RE2 para mapas de URLs.

• A correspondência de expressões regulares é dispendiosa em termos de consumo de memória e latências de processamento de pedidos. Se optar por usar a correspondência de expressões regulares, tem de ter em conta a degradação do desempenho quando planear a implementação. Por exemplo, se tiver um mapa de URLs com uma única expressão regular, pode esperar que a latência do balanceador de carga aumente 100 microssegundos por pedido. Se o mapa de URLs tiver 5 expressões regulares a serem correspondidas, pode esperar que a latência aumente 200 microssegundos por pedido.

Exemplo n.º 1: use uma expressão regular para fazer corresponder o caminho

O caminho é considerado uma correspondência se corresponder à expressão regular especificada por regexMatch após a remoção de quaisquer parâmetros de consulta e âncoras fornecidos com o URL original. Por exemplo, nos seguintes mapeamentos de URLs de exemplo, a expressão regular da regra de encaminhamento, /videos/hd.*, aplicar-se-ia a um URL com o caminho /videos/hd-abcd?key=245.

defaultService: projects/example-project/global/backendServices/org-site
name: rule-match-url-map
hostRules:
- hosts:
  - '*' # Match any host
  pathMatcher: video-matcher
- hosts:
  - example.net
  pathMatcher: video-matcher
pathMatchers:
- name: video-matcher
  # Optional: default service for this path matcher if no routeRules match
  defaultService: projects/example-project/global/backendServices/video-site
  routeRules:
  - priority: 100000
    matchRules:
    - regexMatch: /videos/hd.*
    routeAction:
      weightedBackendServices:
      - backendService: projects/example-project/global/backendServices/video-hd
        weight: 100

Segue-se uma explicação de cada campo do mapa de URLs de exemplo:

• defaultService: Especifica o serviço de back-end predefinido a usar se nenhuma outra regra no mapa de URLs corresponder ao pedido recebido.
• name: atribui o nome rule-match-url-map a esta configuração do mapa de URLs.
• hostRules: define uma lista de regras para fazer corresponder o cabeçalho do anfitrião dos pedidos recebidos. A primeira regra corresponde a qualquer anfitrião (*) e direciona o tráfego para o pathMatcher denominado video-matcher. A segunda regra corresponde especificamente ao anfitrião example.net e também direciona o tráfego para o localizador de caminhos denominado video-matcher.
• pathMatchers: define uma lista de correspondências de caminhos com nomes.
• name: define um correspondente de caminhos denominado video-matcher.
• defaultService: define o serviço predefinido para este caminho. matcher. Este serviço é usado se um pedido corresponder às regras do anfitrião que apontam para video-matcher, mas não corresponder a nenhum dos routeRules no mesmo.
• routeRules: contém uma lista de regras para fazer corresponder o caminho do URL.
• priority: define a prioridade desta regra como 100 000. As regras são avaliadas por ordem do número de prioridade mais baixo para o mais elevado.
• matchRules: contém as condições para que esta regra de encaminhamento seja correspondida.
• regexMatch: esta condição verifica se o caminho do URL corresponde à expressão regular /videos/hd.* (por exemplo, "/videos/hd" e "/videos/hd-caching").
• routeAction: especifica a ação a realizar se todas as condições em matchRules forem cumpridas.
• weightedBackendServices: distribui o tráfego por uma lista de serviços de back-end com base em ponderações.
• backendService: especifica o serviço de back-end para o qual encaminhar o tráfego.
• weight: atribui um peso de 100 a este serviço de back-end. Uma vez que é o único serviço na lista, recebe 100% do tráfego que corresponde a esta routeRule.

O mapa de URLs seguinte mostra um exemplo semelhante sem usar um routeAction.

defaultService: projects/example-project/global/backendServices/video-site
name: path-matcher-videos
routeRules:
  matchRules:
  - regexMatch: /videos/hd.*
  priority: 100000
  service: projects/example-project/global/backendServices/video-hd

Exemplo n.º 2: use uma expressão regular para corresponder a cabeçalhos

O cabeçalho é considerado uma correspondência se o valor do cabeçalho corresponder à expressão regular especificada por regexMatch. Por exemplo, no mapa de URLs de exemplo seguinte, a expressão regular do nome do cabeçalho, .*Android.*-hd, aplicar-se-ia a um pedido com o cabeçalho User-Agent:123Androidabc-hd.

defaultService: projects/example-project/regions/us-central1/backendServices/default-backend-service
name: header-match-url-map
hostRules:
- hosts:
  - '*'  # Match any host
  pathMatcher: header-matcher
pathMatchers:
- name: header-matcher
  # Optional: default service for this path matcher if no routeRules match
  defaultService: projects/example-project/regions/us-central1/backendServices/default-backend-service
  routeRules:
  - priority: 1
    matchRules:
    - headerMatches:
      - headerName: User-Agent
        regexMatch: .*Android.*-hd
    # This prefix match applies to the path part of the URL
    - prefixMatch: /video/
    # service: can be used instead of routeAction if no other actions are needed
    service: projects/example-project/regions/us-central1/backendServices/video-backend-service
    # Alternatively, use routeAction to specify the service:
    # routeAction:
    #   weightedBackendServices:
    #   - backendService: projects/example-project/regions/us-central1/backendServices/video-backend-service
    #     weight: 100

Segue-se uma explicação de cada campo do mapa de URLs de exemplo:

• defaultService: Especifica o serviço de back-end predefinido a usar se nenhuma outra regra no mapa de URLs corresponder ao pedido recebido.
• : atribui o nome header-match-url-map a esta configuração do mapa de URLs.name
• hostRules: Define uma lista de regras para fazer corresponder o cabeçalho do anfitrião dos pedidos recebidos. A regra corresponde a qualquer anfitrião ("*") e direciona o tráfego para o header-matcher denominado pathMatcher.
• pathMatchers: define uma lista de correspondências de caminhos com nomes.
• name: define um correspondente de caminho denominado header-matcher.
• defaultService: define o serviço predefinido para este correspondente de caminhos. Este serviço é usado se um pedido corresponder à regra de anfitrião, mas não corresponder a nenhum dos routeRules neste correspondente de caminho.
• routeRules: contém uma lista de regras para corresponder a pedidos recebidos com base em cabeçalhos e caminhos.
• priority: Define a prioridade desta regra como 1. As regras são avaliadas por ordem, do número de prioridade mais baixo para o mais alto.
• matchRules: contém uma lista de condições que têm de ser todas verdadeiras para que a regra corresponda.
• headerMatches: especifica condições com base nos cabeçalhos dos pedidos.
• headerName: procura o cabeçalho do agente do utilizador.
• regexMatch: verifica se o valor do cabeçalho User-Agent corresponde à expressão regular .*Android.*-hd. Isto corresponderia a agentes do utilizador que indicam um dispositivo Android, com uma string que contém "-hd".
• prefixMatch: definido como /video/, esta condição verifica se o caminho do URL começa com "/video/".
• service: se todas as condições matchRules forem cumpridas, o tráfego é direcionado para este serviço de back-end.
• A secção routeAction com comentários mostra uma forma alternativa de especificar o serviço de back-end, que seria necessária se precisasse de configurar outras ações de encaminhamento, como reescritas de URLs, transformações de cabeçalhos ou serviços de back-end ponderados.

Exemplo n.º 3: use uma expressão regular para corresponder a parâmetros de consulta

O parâmetro de consulta é considerado uma correspondência se o valor do caminho com os parâmetros de consulta corresponder à expressão regular especificada por regexMatch. Por exemplo, no seguinte mapa de URLs de exemplo, a expressão regular do parâmetro de consulta, /im.*/.*.html, aplicar-se-ia a um URL com parâmetros de consulta, como /images/random_page.html?param1=param_value_123abc-hd.

defaultService: projects/example-project/regions/us-central1/backendServices/sample-bs
name: query-match-url-map
hostRules:
- hosts:
  - '*'  # Match any host
  pathMatcher: query-matcher
pathMatchers:
- name: query-matcher
  # Optional: default service for this path matcher if no routeRules match
  defaultService: projects/example-project/regions/us-central1/backendServices/sample-bs
  routeRules:
  - priority: 1
    matchRules:
    - queryParameterMatches:
      - name: param1   #parameter name in query
        regexMatch: param_value_.*-hd
    # This regexMatch applies to the path part of the URL
    - regexMatch: /im.*/.*.html
    # Directs traffic to this service if all conditions in matchRules are met
    service: projects/example-project/regions/us-central1/backendServices/sample-images-bs

Segue-se uma explicação de cada campo do mapa de URLs de exemplo:

• hostRules: adiciona uma regra para corresponder a todos os anfitriões (*) e direciona o tráfego para o pathMatcher denominado query-matcher.
• pathMatchers: define um elemento de correspondência de caminho denominado query-matcher.
• routeRules: coloca o bloco routeRules fornecido em query-matcher.
• priority: Define a prioridade desta regra como 1. As regras são avaliadas por ordem, do número de prioridade mais baixo para o mais alto.
• matchRules: contém as condições para o elemento routeRules.
• queryParameterMatches: verifica se o parâmetro de consulta denominado "param1" corresponde à expressão regular param_value_.*-hd.
• regexMatch: A expressão regular /im.*/.*.html aplica-se ao caminho do URL (por exemplo, /images/random_page.html), antes da string de consulta.
• service: especifica o serviço de back-end a usar se todas as condições no elemento matchRules forem verdadeiras.

Carateres universais, expressões regulares e URLs dinâmicos em regras de caminho e correspondência de prefixo

• Uma regra de caminho (pathMatchers[].pathRules[]) só pode incluir um caráter universal (*) após um caráter de barra (/). Por exemplo, /videos/* e /videos/hd/* são válidos para regras de caminho, mas /videos* e /videos/hd* não são.

• As regras de caminho não usam expressões regulares nem correspondência de substrings. PathTemplateMatch pode usar operadores de correspondência de caminhos simplificados. Por exemplo, as regras de caminho para /videos/hd ou /videos/hd/* não se aplicam a um URL com o caminho /video/hd-abcd. No entanto, uma regra do caminho para /video/* aplica-se a esse caminho.

• Uma correspondência de prefixo (pathMatchers[].routeRules[].matchRules[].prefixMatch) não trata * como um caráter universal, mas como um caráter literal.

• Os correspondentes de caminhos (e os mapas de URLs em geral) não oferecem funcionalidades que funcionam como a diretiva <LocationMatch> do Apache. Se tiver uma aplicação que gere caminhos de URL dinâmicos com um prefixo comum, como /videos/hd-abcd e /videos/hd-pqrs, e precisar de enviar pedidos feitos a esses caminhos para diferentes serviços de back-end, pode não conseguir fazê-lo com um mapa de URLs. Para casos que contenham apenas alguns URLs dinâmicos possíveis, pode criar um correspondente de caminho com um conjunto limitado de regras de caminho. Para casos mais complexos, tem de fazer a correspondência de expressões regulares baseada no caminho nos seus back-ends.

Carateres universais e operadores de correspondência de padrões em modelos de caminhos para regras de encaminhamento

Os operadores de correspondência de padrões flexíveis permitem-lhe fazer corresponder várias partes de um caminho de URL, incluindo URLs parciais e sufixos (extensões de ficheiros), através da sintaxe de carateres universais. Estes operadores podem ser úteis quando precisa de encaminhar tráfego e executar reescritas com base em caminhos de URL complexos. Também pode associar um ou mais componentes do caminho a variáveis com nomes e, em seguida, referir-se a essas variáveis ao reescrever o URL. Com as variáveis com nome, pode reordenar e remover componentes do URL antes de o pedido ser enviado para a sua origem.

A correspondência de padrões com carateres universais só é suportada para os seguintes produtos:

• Balanceador de carga de aplicações externo global

• Balanceador de carga de aplicações externo regional
• Balanceador de carga de aplicações interno regional

• Balanceador de carga de aplicações interno entre regiões
• Cloud Service Mesh

O exemplo seguinte encaminha o tráfego para uma aplicação de comércio eletrónico que tem serviços separados para informações do carrinho e informações do utilizador. Pode configurar routeRules com operadores de correspondência de padrões flexíveis e variáveis com nomes para enviar o ID exclusivo do utilizador para uma página de detalhes da conta de utilizador e as informações do carrinho do utilizador para um serviço de processamento de carrinhos após reescrever o URL.

  pathMatchers:
    - name: cart-matcher
      routeRules:
        - description: CartService
          matchRules:
            - pathTemplateMatch: '/xyzwebservices/v2/xyz/users/{username=*}/carts/{cartid=**}'
          service: cart-backend
          priority: 1
          routeAction:
            urlRewrite:
              pathTemplateRewrite: '/{username}-{cartid}/'
    - name: user-matcher
      routeRules:
        - description: UserService
          matchRules:
            - pathTemplateMatch: '/xyzwebservices/v2/xyz/users/*/accountinfo/*'
          service: user-backend
          priority: 1

Veja o que acontece quando um cliente pede /xyzwebservices/v2/xyz/users/[e-mail]/carts/FL0001090004/entries/SJFI38u3401nms?fields=FULL&client_type=WEB, que tem informações do utilizador e informações do carrinho:

1. O caminho do pedido corresponde ao pathTemplateMatch no cart-matcher pathMatcher. A variável {username=*} corresponde a [e-mail] e a variável {cartid=**} corresponde a FL0001090004/entries/SJFI38u3401nms.
2. Os parâmetros de consulta são separados do caminho, o caminho é reescrito com base em pathTemplateRewrite e os parâmetros de consulta são anexados ao caminho reescrito. Só podemos usar as mesmas variáveis que usámos para definir o pathTemplateMatch no nosso pathTemplateRewrite.
3. O pedido reescrito é enviado para cart-backend com o caminho do URL reescrito: /[e-mail]-FL0001090004/entries/SJFI38u3401nms?fields=FULL&client_type=WEB.

Quando um cliente pede /xyzwebservices/v2/xyz/users/abc%40xyz.com/accountinfo/abc-1234, que tem apenas informações do utilizador e da conta, acontece o seguinte:

1. O caminho do pedido corresponde ao pathTemplateMatch no user-matcher pathMatcher. O primeiro * corresponde a abc%40xyz.com e o segundo * corresponde a abc-1234.
2. O pedido é enviado para user-backend.

A tabela seguinte descreve a sintaxe dos padrões de modelos de caminhos.

Operador	Correspondências
*	Um único segmento de caminho, não incluindo os carateres separadores de caminho / circundantes.
**	Corresponde a zero ou mais carateres, incluindo quaisquer carateres separadores de caminho / entre vários segmentos de caminho. Se forem incluídos outros operadores, o operador ** tem de ser o último.
{name} ou {name=*}	Uma variável com nome que corresponda a um segmento do caminho. Corresponde a um único segmento de caminho, não incluindo os carateres separadores de caminho / circundantes.
{name=news/*}	Uma variável com nome que corresponde explicitamente a dois segmentos do caminho: news e um segmento com carateres universais *.
{name=*/news/*}	Uma variável com nome que corresponde a três segmentos do caminho.
{name=**}	Uma variável com nome que corresponde a zero ou mais carateres. Se estiver presente, tem de ser o último operador.

Quando usa estes operadores para a correspondência de padrões flexível, tenha em atenção as seguintes considerações:

• É possível combinar vários operadores num único padrão.
• Os parâmetros de consulta são separados do caminho, o caminho é reescrito com base em pathTemplateRewrite e os parâmetros de consulta são anexados ao caminho reescrito.
• Os pedidos não são normalizados com codificação em percentagem. Por exemplo, um URL com um caráter de barra codificado em percentagem (%2F) não é descodificado para o formato não codificado.
• Cada nome de variável, como {segment} ou {region}, só pode aparecer uma vez no mesmo padrão. As variáveis múltiplas com o mesmo nome são inválidas e são rejeitadas.
• Os nomes das variáveis são sensíveis a maiúsculas e minúsculas e têm de ser identificadores válidos. Para verificar se um nome de variável é válido, certifique-se de que corresponde à expressão regular ^[a-zA-Z][a-zA-Z0-9_]*$.
  • {API}, {api} e {api_v1} são todos identificadores válidos. Identificam três variáveis distintas.
  • {1}, {_api} e {10alpha} não são identificadores válidos.
• Existe um limite de cinco operadores por padrão de modelo.

Para executar uma reescrita de URL opcional antes de o pedido ser enviado para a origem, pode usar as mesmas variáveis que definiu para capturar um caminho. Por exemplo, pode fazer referência, reordenar ou omitir variáveis no campo pathTemplateRewrite ao definir urlRewrite.

Quando usa variáveis e operadores para a correspondência de padrões flexível para reescritas de URLs, tenha em atenção estas considerações:

• Ao reescrever um URL, pode omitir variáveis se não forem necessárias como parte do URL reescrito.
• Antes de quaisquer reescritas, pode identificar o URL enviado pelo cliente na sua origem inspecionando os cabeçalhos de resposta. O URL do cliente original é preenchido com o cabeçalho x-client-request-url e o cabeçalho x-envoy-original-path.

Exemplo de fluxo de trabalho de mapa de URLs com um balanceador de carga de aplicações externo

O exemplo seguinte ilustra a ordem das operações para um mapa de URLs. Este exemplo configura apenas o mapa de URLs para um balanceador de carga da aplicação clássico existente. Para simplificar o conceito, usa apenas serviços de back-end. No entanto, pode substituir os serviços de back-end por contentores de back-end. Para saber como criar os outros componentes do balanceador de carga, consulte o artigo Crie um balanceador de carga de aplicações clássico.

Para mais informações sobre como criar e configurar mapas de URLs com correspondências de caminhos e regras de anfitriões, consulte a gcloud compute url-maps create documentação.

1. Crie um mapa de URLs para o balanceador de carga e especifique um serviço de back-end predefinido. Este exemplo cria um mapa de URLs denominado video-org-url-map que faz referência a um serviço de back-end existente denominado org-site.

   gcloud compute url-maps create video-org-url-map \
       --default-service=org-site
   

2. Crie um correspondente de caminho com o nome video-matcher com as seguintes características:

   • O serviço de back-end predefinido é video-site, um serviço de back-end existente.
   • Adicione regras de caminho que direcionam pedidos para o caminho de URL exato /video/hd ou o prefixo do caminho de URL /video/hd/* para um serviço de back-end existente denominado video-hd.
   • Adicione regras de caminho que direcionam pedidos para o caminho de URL exato /video/sd ou o prefixo do caminho de URL /video/sd/* para um serviço de back-end existente denominado video-sd.

   gcloud compute url-maps add-path-matcher video-org-url-map \
       --path-matcher-name=video-matcher \
       --default-service=video-site \
       --path-rules=/video/hd=video-hd,/video/hd/*=video-hd,/video/sd=video-sd,/video/sd/*=video-sd
   

3. Crie uma regra de anfitrião para o nome do anfitrião example.net que faça referência ao matcher de caminho video-matcher.

   gcloud compute url-maps add-host-rule video-org-url-map \
       --hosts=example.net \
       --path-matcher-name=video-matcher
   

O video-org-url-mapURL do mapa deve ter o seguinte formato:

gcloud compute url-maps describe video-org-url-map

creationTimestamp: '2021-03-05T13:34:15.833-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/org-site
fingerprint: mfyJIT7Zurs=
hostRules:
- hosts:
  - '*'
  pathMatcher: video-matcher
- hosts:
  - example.net
  pathMatcher: video-matcher
id: '8886405179645041976'
kind: compute#urlMap
name: video-org-url-map
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-site
  name: video-matcher
  pathRules:
  - paths:
    - /video/hd
    - /video/hd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-hd
  - paths:
    - /video/sd
    - /video/sd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-sd
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/video-org-url-map

O mapa de URLs video-org-url-map direciona os URLs solicitados para back-ends da seguinte forma.

Mapa de URLs com uma regra de caminho, correspondências de caminho e uma regra de anfitrião (clique para aumentar).

A tabela seguinte explica o processamento de pedidos apresentado no diagrama anterior.

Nome do anfitrião	Caminhos de URLs	Serviço de back-end selecionado	Motivo da seleção
Nome do anfitrião: example.org e todos os outros nomes de anfitriões diferentes de example.net	todos os caminhos	org-site	O nome do anfitrião não está em nenhuma regra de anfitrião do mapa de URLs, pelo que o pedido é direcionado para o serviço de back-end predefinido do mapa de URLs.
Nome do anfitrião: example.net	/video /video/examples	video-site	O pedido é enviado para o serviço de back-end predefinido porque não existe nenhuma regra de caminho para /video/ ou /video/*. A regra de anfitrião para example.net faz referência a um correspondente de caminhos, mas esse correspondente de caminhos não tem regras de caminhos que se aplicariam a estes caminhos.
Nome do anfitrião: example.net	/video/hd /video/hd/movie1 /video/hd/movies/movie2 Outros URLs que começam por /video/hd/*	video-hd	Uma regra de anfitrião para example.net faz referência a um matcher de caminho cujas regras de caminho direcionam pedidos de caminhos de URL que correspondem exatamente /video/hd ou que começam com /video/hd/* para o serviço de back-end video-hd.
Nome do anfitrião: example.net	/video/sd /video/sd/show1 /video/sd/shows/show2 Outros URLs que começam por /video/sd/*	video-sd	Uma regra de anfitrião para example.net faz referência a um matcher de caminho cujas regras de caminho direcionam pedidos de caminhos de URL que correspondem exatamente /video/sd ou que começam com /video/sd/* para o serviço de back-end video-sd.

Redirecionamentos de URL

Um redirecionamento de URL redireciona os visitantes do seu domínio de um URL para outro.

Um redirecionamento de URL predefinido não está condicionado à correspondência de nenhum padrão específico no pedido recebido. Por exemplo, é recomendável usar um redirecionamento de URL predefinido para redirecionar qualquer nome do anfitrião para um nome do anfitrião à sua escolha.

Existem várias formas de criar um redirecionamento de URL, conforme descrito na tabela seguinte.

Método	Configuração
Redirecionamento de URL predefinido do mapa de URLs	Nível superior defaultUrlRedirect
Um redirecionamento de URL predefinido de um correspondente de caminho	pathMatchers[].defaultUrlRedirect[]
O redirecionamento de URL da regra de caminho de um correspondente de caminho	pathMatchers[].pathRules[].urlRedirect
O redirecionamento de URL da regra de encaminhamento de um matcher de caminho	pathMatchers[].routeRules[].urlRedirect

Dentro de um defaultUrlRedirect ou urlRedirect, o pathRedirect funciona sempre da seguinte forma:

• Todo o caminho do pedido é substituído pelo caminho que especificar.

Dentro de um defaultUrlRedirect ou urlRedirect, o funcionamento do prefixRedirect depende da forma como o usa:

• Se usar um defaultUrlRedirect, prefixRedirect é efetivamente um prefixo adicionado porque o caminho correspondente é sempre /.
• Se usar um urlRedirect numa regra de trajeto ou numa regra de caminho de um matcher de caminhos, prefixRedirect é uma substituição de prefixo com base na forma como o caminho pedido foi correspondido conforme definido na regra de caminho ou na regra de trajeto.

Exemplos de redirecionamentos

A tabela seguinte apresenta alguns exemplos de configurações de redirecionamento. A coluna do lado direito mostra a configuração da API para um redirecionamento de URL predefinido.

Quer	Realizado através de um redirecionamento de URL predefinido
Redirecionamento de HTTP para HTTPS Redirecionar http://host.name/path para https://host.name/path	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True
Redirecionamento de HTTP para HTTPS + anfitrião Redirecionamento http://any-host-name/path para https://www.example.com/path	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True hostRedirect: "www.example.com"
HTTP para HTTPS + redirecionamento de anfitrião + redirecionamento de caminho completo Redirecionar http://any-host-name/path para https://www.example.com/newPath	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True hostRedirect: "www.example.com" pathRedirect: "/newPath"
HTTP para HTTPS + redirecionamento de anfitrião + redirecionamento de prefixo Redirecionamento http://any-host-name/originalPath para https://www.example.com/newPrefix/originalPath	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True hostRedirect: "www.example.com" prefixRedirect: "/newPrefix"

O fragmento parcial seguinte anota cada recurso da API:

defaultUrlRedirect:
   redirectResponseCode: MOVED_PERMANENTLY_DEFAULT
   httpsRedirect: True # True if you want https://, false if you want http://
   hostRedirect: "new-host-name.com" # Omit to keep the requested host
   pathRedirect: "/new-path" # Omit to keep the requested path; mutually exclusive to prefixRedirect
   prefixRedirect: "/newPrefix" # Omit to keep the requested path; mutually exclusive to pathRedirect
   stripQuery: False # True to omit everything in the URL after ?
   ...

O que se segue?

• Para adicionar, validar, testar, listar ou eliminar um mapa de URLs, consulte o artigo Use mapas de URLs.

• Para obter informações sobre mapas de regras de encaminhamento com a Cloud Service Mesh, consulte a vista geral dos mapas de regras de encaminhamento da Cloud Service Mesh.