Visão geral dos mapas de URL

Google Cloud Os balanceadores de carga de aplicativo e o Cloud Service Mesh usam um Google Cloud recurso de configuração chamado mapa de URL para encaminhar solicitações HTTP(S) para serviços ou buckets de back-end.

Por exemplo, com um balanceador de carga de aplicativo externo, é possível usar um único mapa de URL para rotear solicitações para destinos diferentes com base nas regras configuradas no mapa de URL:

• As solicitações de https://example.com/video vão para um serviço de back-end.
• As solicitações de https://example.com/audio vão para um serviço de back-end diferente

• As solicitações de https://example.com/images vão para um bucket de back-end do Cloud Storage.

• As solicitações de qualquer outra combinação de host e caminho vão para um serviço de back-end padrão.

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

• Balanceador de carga de aplicativo externo (modos globais, regionais e clássicos)
• Balanceador de carga de aplicativo interno (modos regionais e regionais)
• Cloud Service Mesh, quando o Cloud Service Mesh é implantado com as APIs de balanceamento de carga

Há dois tipos de recursos de mapa de URL disponíveis: globais e regionais.

• Os urlMaps globais são usados por balanceadores de carga de aplicativo externos globais, balanceadores de carga de aplicativo clássicos, balanceadores de carga de aplicativo internos entre regiões e o Cloud Service Mesh.

• regionUrlMaps são usados por balanceadores de carga de aplicativo externos regionais, balanceadores de carga de aplicativo internos regionais e Cloud Service Mesh.

O tipo de recurso usado depende do esquema de balanceamento de carga do produto.

Produto	Esquema de balanceamento de carga	Tipo de recurso do mapa de URL	Destinos possíveis
Balanceador de carga de aplicativo externo global	EXTERNAL_MANAGED	Global	Serviços de back-end, buckets de back-end
Balanceador de carga de aplicativo clássico	EXTERNAL	Global	Serviços de back-end, buckets de back-end
Balanceador de carga de aplicativo externo regional	EXTERNAL_MANAGED	Regional	Serviços de back-end
Balanceador de carga de aplicativo interno entre regiões	INTERNAL_MANAGED	Global	Serviços de back-end
Balanceador de carga de aplicativo 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 todos os recursos do mapa de URL estão disponíveis para todos os produtos. Os mapas de URL usados com balanceadores de carga de aplicativo externos globais, balanceadores de carga de aplicativo externos regionais, balanceadores de carga de aplicativo internos, e o Cloud Service Mesh também dão suporte a vários recursos de gerenciamento de tráfego. Para mais informações sobre essas diferenças, consulte Comparação de recursos do balanceador de carga: roteamento e gerenciamento de tráfego. Além disso, os mapas de URL regionais podem ser um recurso designado como um serviço nos aplicativos do App Hub.

Como os mapas de URL funcionam

Quando uma solicitação chega ao balanceador de carga, ele a direciona para um serviço de back-end específico ou para um bucket de back-end com base nas regras definidas no mapa de URL.

Um serviço de back-end representa um conjunto de back-ends, que são instâncias de um aplicativo ou microsserviço. Um bucket de back-end é um bucket do Cloud Storage, normalmente usado para hospedar conteúdo estático, como imagens.

Para balanceadores de carga de aplicativo externos regionais, balanceadores de carga de aplicativo internos e Cloud Service Mesh, os destinos possíveis são:

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

Além disso, os balanceadores de carga de aplicativo externos globais são compatíveis com:

• Bucket de back-end padrão
• Bucket de back-end não padrão

Por exemplo, suponha que você tenha a seguinte configuração:

• Um endereço IP:
  • Todas as solicitações à sua organização vão para o mesmo endereço IP e o mesmo balanceador de carga.
  • O tráfego é direcionado para diferentes serviços de back-end com base no URL da solicitação.
• Dois domínios:
  • example.net hospeda vídeos de treinamento.
  • example.org hospeda o site da sua organização.
• Quatro conjuntos de servidores:
  • Um hospeda o site da sua organização (serviço de back-end: org-site).
  • Um hospeda o site de vídeo de treinamento geral (serviço de back-end: video-site).
  • Um hospeda vídeos de treinamento em HD (serviço de back-end: video-hd).
  • Um hospeda vídeos de treinamento em definição padrão (serviço de back-end: video-sd).

Você quer que aconteça o seguinte:

• As solicitações para example.org ou qualquer domínio diferente de example.net para acessar o serviço de back-end org-site.
• Solicitações para example.net que não correspondem a caminhos mais específicos para acessar o serviço de back-end video-site.
• Solicitações para example.net/video/hd/* para acessar o serviço de back-end video-hd.
• Solicitações para example.net/video/sd/* para acessar o serviço de back-end video-sd.

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

Se o balanceador de carga receber uma solicitação com /../ no URL, ele transformará o URL removendo o segmento de caminho antes do .. e responderá com o URL transformado. Por exemplo, quando uma solicitação é enviada 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 emitindo uma solicitação ao URL retornado pelo balanceador de carga (neste caso, http://example.net/abc). Esse redirecionamento 302 não está registrado no Cloud Logging.

Com o mapa de URL, você configura esse tipo de roteamento baseado em host e caminho.

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

Como nomear o balanceador de carga

Para balanceadores de carga de aplicativo, o nome do balanceador de carga é sempre o mesmo que o nome do mapa de URL. O comportamento de cada interface Google Cloud é o seguinte:

• Console doGoogle Cloud . Se você criar um balanceador de carga de aplicativo usando o consoleGoogle Cloud , o mapa de URL vai receber automaticamente o mesmo nome que você inseriu para o nome do balanceador de carga.
• CLI ou API do Google Cloud. Se você criar um balanceador de carga de aplicativo usando a CLI gcloud ou a API, insira um nome de sua escolha ao criar o mapa de URL. Esse nome é refletido no consoleGoogle Cloud como o nome do balanceador de carga.

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

Componentes do mapa de URL

Um mapa de URL é um conjunto de recursos de Google Cloud configuração que direciona solicitações de URLs para serviços ou buckets de back-end. O mapa de URL faz isso usando as partes nome do host e caminho de cada URL processado:

• O nome do host é a parte do nome de domínio de um URL. Por exemplo, a parte do nome do host do URL http://example.net/video/hd é example.net.
• Um caminho é a parte de um URL após o nome do host 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 básico de URL (clique para ampliar).

Este diagrama mostra a estrutura dos objetos de configuração de balanceamento de carga um em relação ao outro.

Observação: o diagrama não se destina a mostrar o fluxo de processamento das solicitações.

Você controla quais serviços ou buckets de back-end recebem solicitações usando os parâmetros de configuração de mapa de URL a seguir:

• Serviço ou bucket de back-end padrão. Ao criar um mapa de URL, você precisa especificar um serviço ou bucket de back-end padrão, mas não ambos. Esse padrão representa o serviço ou bucket de back-end a que o Google Cloud encaminha solicitações de URLs com qualquer nome de host, a menos que haja uma regra de host aplicável.

  Observação: os buckets de back-end não são compatíveis com balanceadores de carga de aplicativo internos e o Cloud Service Mesh.

• Regra de host (hostRules). Uma regra de host direciona as solicitações enviadas para um ou mais nomes de host associados a uma única correspondência de caminho (pathMatchers). A parte do nome do host de um URL corresponde exatamente ou corresponde usando expressões regulares ao conjunto de nomes de host configurados da regra de host. Em um host de mapa de URL e uma regra de caminho, se você omitir o host, a regra corresponderá a qualquer host solicitado. Para direcionar as solicitações de http://example.net/video/hd para uma correspondência de caminho, você precisa de uma única regra de host que inclua, no mínimo, o nome de host example.net. Essa mesma regra de host também pode processar solicitações de outros nomes de host, mas isso as direciona para a mesma correspondência de caminho.

  Se você precisar direcionar solicitações para diferentes correspondências de caminho, use regras de host distintas. Duas regras de host em um mapa de URL não podem incluir o mesmo nome de host.

  Para corresponder todos os nomes de host, especifique o caractere curinga * na regra de host. Por exemplo, para os URLs http://example.org, http://example.net/video/hd e http://example.com/audio, é possível corresponder os três nomes de host example.org, example.net e example.com especificando * na regra de host. Também é possível fazer a correspondência de um nome do host parcial especificando o caractere curinga *. Por exemplo, uma regra de host *.example.net corresponde aos dois nomes de host news.example.net e finance.example.net.

  Número da porta. Balanceadores de carga de aplicativo diferentes processam números de porta de maneira diferente. No caso do balanceador de carga de aplicativo interno, é possível usar o parâmetro Regra de host para especificar um número de porta. Por exemplo, para direcionar solicitações example.net para a porta 8080, defina a regra de host como example.net:8080. No caso do balanceador de carga de aplicativo clássico, apenas o nome do host no URL é considerado ao corresponder a uma regra de host. Por exemplo, as solicitações example.net para a porta 8080 e a porta 80 correspondem à regra de host example.net.

  Observação: o balanceador de carga não valida o valor do nome do host no URL. Os clientes podem definir valores arbitrários para o nome do host, por exemplo, definindo o cabeçalho Host. Não use o campo de nome de host para implementar controle de acesso no seu aplicativo.

• Correspondência de caminhopathMatchers: parâmetro de configuração referenciado por uma regra de host. Ela define o vínculo entre a parte do caminho de um URL e o serviço ou bucket de back-end que deve veicular a solicitação. Uma correspondência de caminho consiste em dois elementos:

  • Serviço ou bucket de back-end padrão da correspondência de caminho. Para cada correspondência de caminho, você precisa especificar pelo menos um serviço ou um bucket de back-end padrão, mas não ambos. Esse padrão representa o serviço ou bucket de back-end a que o Google Cloud encaminha solicitações de URLs com nomes de host que correspondem a uma regra de host associada à correspondência de caminho e com caminhos de URL que não correspondem a nenhuma regra de caminho na correspondência.

  • Regras de caminho. Para cada correspondência de caminho, é possível especificar uma ou mais regras de caminho. Elas são pares de chave-valor que mapeiam um caminho do URL para um único serviço ou bucket de back-end.

    Com os operadores de correspondência de padrão flexível, é possível corresponder várias partes de um caminho de URL, incluindo URLs parciais e sufixos (extensões de arquivo), usando uma sintaxe de caracteres curinga. Esses operadores podem ser úteis quando você precisa rotear o tráfego e executar substituições com base em caminhos de URL complexos. Também é possível associar um ou mais componentes de caminho a variáveis nomeadas e, em seguida, consultar essas variáveis ao reescrever o URL. Com variáveis nomeadas, é possível reordenar e remover componentes de URL antes que a solicitação seja enviada à sua origem. Para mais detalhes, consulte Caracteres curinga, expressões regulares e URLs dinâmicos em regras de caminho.

    Se você precisar de recursos de roteamento mais avançados, por exemplo, se quiser direcionar o tráfego de um URL exclusivo para vários serviços, use regras de rota em vez de regras de caminho.

  • Regras de rota. As regras de rota podem ser usadas como alternativa às regras de caminho quando você precisa de recursos avançados de roteamento de tráfego, como roteamento de tráfego com base no caminho do URL, cabeçalhos HTTP e parâmetros de consulta.

    É possível configurar regras de rota com operadores de correspondência de padrão flexíveis e variáveis nomeadas. Esses operadores podem ser úteis quando você precisa rotear o tráfego e executar substituições com base em caminhos de URL complexos. Para mais detalhes, consulte Operadores com caracteres curinga e correspondência de padrão em modelos de caminho para regras de rota.

    Também é possível configurar regras de rota para serem correspondidas com expressões regulares que correspondem ao caminho, aos parâmetros de consulta ou aos cabeçalhos na solicitação de entrada. Para mais detalhes, consulte Expressões regulares em regras de rota.

Relação de nome do host e regra de host

• Um nome de host só pode referenciar uma única regra de host.

• Uma única regra de host pode processar vários nomes de host.

Relação de regra de host e correspondência de caminho

• Várias regras de host podem referenciar uma única correspondência de caminho.

• Uma regra de host só pode referenciar uma única correspondência de caminho.

Relação de URL e back-end

Cada URL único é direcionado a apenas um serviço ou bucket de back-end: Consequentemente:

• OGoogle Cloud usa a parte do nome de host de um URL para selecionar uma única regra de host e a correspondência de caminho referenciada.

• Quando você usa regras de caminho em uma correspondência de caminho, não é possível criar mais de uma para o mesmo caminho. Por exemplo, não é possível direcionar solicitações de /videos/hd para mais de um serviço ou bucket de back-end. Os serviços de back-end podem ter grupos de instâncias de back-end ou grupos de endpoints de rede de back-end (NEGs) em diferentes zonas e regiões. Além disso, é possível criar buckets de back-end que usam classes Multi-Regional Storage.

  Para direcionar o tráfego de um URL exclusivo para vários serviços, use regras de rota em vez de regras de caminho. Se você configurar a correspondência de caminho com regras de rota para correspondências de cabeçalho ou parâmetro, um URL exclusivo poderá ser direcionado para mais de um serviço ou bucket de back-end, com base no conteúdo dos cabeçalhos ou parâmetros de consulta na URL.

  Da mesma forma, para balanceadores de carga de aplicativo externos regionais e para o Cloud Service Mesh, os serviços de back-end ponderados em ações de rota podem direcionar o mesmo URL para vários serviços ou buckets de back-end, dependendo das ponderações definidas no serviço de back-end ponderado.

Mapas e protocolos de URL

É possível usar o mesmo mapa de URL, regras de host e correspondências de caminho para processar solicitações HTTP e HTTPS enviadas por clientes. Para isso, os proxies HTTP e HTTPS de destino precisam referenciar o mapa de URL.

Mapa de URL mais simples

O mapa de URL mais simples tem apenas um serviço ou bucket de back-end padrão. Ele não contém regras de host nem correspondências de caminho. A opção que você definiu, seja serviço ou bucket de back-end padrão, processa todos os URLs solicitados.

Se você definir um serviço de back-end padrão,o Google Cloud direcionará as solicitações para os grupos de instâncias de back-end ou NEGs de acordo com a configuração do serviço de back-end.

Mapa de URL sem regras, exceto a padrão (clique para ampliar)

Ordem de operações

Para um determinado nome de host e caminho em um URL solicitado,o Google Cloud usa o procedimento a seguir para direcionar a solicitação ao serviço ou bucket de back-end correto, conforme configurado no mapa de URL:

• Se o mapa de URL não tiver uma regra de host para o nome de host do URL, oGoogle Cloud encaminhará as solicitações ao serviço ou bucket de back-end padrão do mapa de URL, dependendo de qual você definiu.

• Se o mapa de URL tiver uma regra de host que inclua o nome de host do URL, a correspondência de caminho referenciada por essa regra de host será consultada:

  • Se a correspondência de caminho tiver uma regra que corresponda exatamente ao caminho do URL, Google Cloud encaminhará as solicitações ao serviço de back-end ou bucket de back-end dessa regra.

  • Se a correspondência de caminho não tiver uma regra que corresponda exatamente ao caminho do URL, mas tiver outra terminada em /* com um prefixo que corresponda à seção mais longa do caminho do URL, o Google Cloud encaminhará as solicitações ao serviço de back-end ou bucket de back-end dessa regra. Por exemplo, para o mapa de URL que contém duas regras de correspondência de caminho /video/hd/movie1 e /video/hd/*, se o URL tiver o caminho exato /video/hd/movie1, ele será correspondido com essa regra de caminho.

  • Se nenhuma das condições anteriores for verdadeira, Google Cloud direcionará as solicitações ao serviço ou bucket de back-end padrão da correspondência de caminho, dependendo de qual deles você definiu.

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

As seções a seguir descrevem algumas restrições de configuração para componentes do mapa de URL.

Comparadores de expressões regulares em regras de host e de rota

Pré-lançamento

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Com as regras de host, é possível corresponder a parte do nome do host de um URL ao conjunto de nomes de host configurados da regra. Você pode usar um nome de host específico ou um caractere curinga * no campo hostRules[].hosts[] para corresponder ao nome de host na solicitação recebida.

Com as regras de rota, é possível definir regras de correspondência que podem corresponder a uma expressão regular no caminho, na string de consulta ou em um cabeçalho na solicitação de entrada. As regras de rota aceitam o uso de expressões regulares para os seguintes campos do mapa de URLs:

• pathMatchers[].routeRules[].matchRules[].regexMatch: uma expressão regular usada para corresponder ao caminho da solicitação recebida.
• pathMatchers[].routeRules[].matchRules[].headerMatches[].regexMatch: uma expressão regular que contém um predicado que corresponde a um cabeçalho da solicitação recebida.
• pathMatchers[].routeRules[].matchRules[].queryParameterMatches[].regexMatch: uma expressão regular que contém um predicado correspondente a um parâmetro de consulta da solicitação recebida.

Uma solicitação é considerada correspondente a uma routeRule quando qualquer uma das matchRules é atendida. No entanto, os predicados em uma determinada matchRule têm semântica AND. Ou seja, todos os predicados em uma matchRule precisam corresponder para que a solicitação corresponda à regra.

Outras observações sobre o uso:

• As expressões regulares são compatíveis apenas com os seguintes produtos:

  • Balanceadores de carga de aplicativo internos regionais
  • Balanceadores de carga de aplicativo internos entre regiões
  • Balanceadores de carga de aplicativo externos regionais

  Os balanceadores de carga de aplicativo globais e clássicos não são compatíveis com expressões regulares.

• Você precisa usar a sintaxe RE2 para criar suas expressões regulares. Para conferir a lista completa de limitações e operadores permitidos em mapas de URL, consulte Especificações do RE2 para mapas de URL.

• A correspondência de expressões regulares é cara em termos de consumo de memória e latências de processamento de solicitações. Se você optar por usar a correspondência de expressão regular, considere a degradação da performance ao planejar a implantação. Por exemplo, se você tiver um mapa de URL com uma única expressão regular, a latência do balanceador de carga vai aumentar em 100 microssegundos por solicitação. Se o mapa de URL tiver cinco expressões regulares para serem correspondidas, espere um aumento de 200 microssegundos por solicitação.

Exemplo 1: usar uma expressão regular para corresponder ao caminho

O caminho é considerado uma correspondência se corresponder à expressão regular especificada por regexMatch depois de remover todos os parâmetros de consulta e âncoras fornecidos com o URL original. Por exemplo, nos mapas de URL de amostra a seguir, a expressão regular da regra de rota, /videos/hd.*, seria aplicada 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

Confira uma explicação de cada campo do mapa de URL de exemplo:

• defaultService: especifica o serviço de back-end padrão a ser usado se nenhuma outra regra no mapa de URL corresponder à solicitação de entrada.
• name: atribui o nome rule-match-url-map a essa configuração de mapa de URL.
• hostRules: define uma lista de regras para corresponder ao cabeçalho do host de solicitações recebidas. A primeira regra corresponde a qualquer host (*) e direciona o tráfego para a pathMatcher chamada video-matcher. A segunda regra corresponde especificamente ao host example.net e também direciona o tráfego para a correspondência de caminho chamada video-matcher.
• pathMatchers: define uma lista de correspondências de caminho nomeadas.
• name: define uma correspondência de caminho chamada video-matcher.
• defaultService: define o serviço padrão para esta correspondência de caminho. Esse serviço é usado se uma solicitação corresponder às regras de host que apontam para video-matcher, mas não corresponder a nenhum dos routeRules dentro dele.
• routeRules: contém uma lista de regras para corresponder ao caminho do URL.
• priority: define a prioridade desta regra como 100000. As regras são avaliadas em ordem do número de prioridade mais baixo para o mais alto.
• matchRules: contém as condições para que essa regra de rota seja correspondida.
• regexMatch: essa 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 ser realizada se todas as condições em matchRules forem atendidas.
• weightedBackendServices: distribui o tráfego entre uma lista de serviços de back-end com base em ponderações.
• backendService: especifica o serviço de back-end para rotear o tráfego.
• weight: atribui um peso de 100 a esse serviço de back-end. Como é o único serviço na lista, ele vai receber 100% do tráfego que corresponde a essa routeRule.

O mapa de URL a seguir 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 2: usar uma expressão regular para corresponder a cabeçalhos

O cabeçalho é considerado uma correspondência se o valor dele corresponder à expressão regular especificada por regexMatch. Por exemplo, no mapa de URL de amostra a seguir, a expressão regular do nome do cabeçalho, .*Android.*-hd, seria aplicada a uma solicitação 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

Confira uma explicação de cada campo do mapa de URL de exemplo:

• defaultService: especifica o serviço de back-end padrão a ser usado se nenhuma outra regra no mapa de URL corresponder à solicitação de entrada.
• name: atribui o nome header-match-url-map a essa configuração de mapa de URL.
• hostRules: define uma lista de regras para corresponder ao cabeçalho do host de solicitações recebidas. A regra corresponde a qualquer host ("*") e direciona o tráfego para o header-matcher chamado pathMatcher.
• pathMatchers: define uma lista de correspondências de caminho nomeadas.
• name: define uma correspondência de caminho chamada header-matcher.
• defaultService: define o serviço padrão para este comparador de caminhos. Esse serviço é usado se uma solicitação corresponder à regra de host, mas não a nenhuma das routeRules nessa correspondência de caminho.
• routeRules: contém uma lista de regras para corresponder às solicitações recebidas com base em cabeçalhos e caminhos.
• priority: define a prioridade desta regra como 1. As regras são avaliadas em ordem do número de prioridade mais baixo para o mais alto.
• matchRules: contém uma lista de condições que precisam ser verdadeiras para que a regra corresponda.
• headerMatches: especifica condições com base em cabeçalhos de solicitação.
• headerName: procura o cabeçalho User-Agent.
• regexMatch: verifica se o valor do cabeçalho User-Agent corresponde à expressão regular .*Android.*-hd. Isso corresponderia a user agents que indicam um dispositivo Android, com uma string que contém "-hd".
• prefixMatch: definido como /video/, essa condição verifica se o caminho do URL começa com "/video/".
• service: se todas as condições matchRules forem atendidas, o tráfego será direcionado para esse serviço de back-end.
• A seção routeAction comentada mostra uma maneira alternativa de especificar o serviço de back-end, que seria necessária se você precisasse configurar outras ações de rota, como reescritas de URL, transformações de cabeçalho ou serviços de back-end ponderados.

Exemplo 3: usar 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 mapa de URL de amostra a seguir, a expressão regular do parâmetro de consulta, /im.*/.*.html, seria aplicada 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

Confira uma explicação de cada campo do mapa de URL de exemplo:

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

Caracteres curinga, 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 caractere curinga (*) após uma barra (/). Por exemplo, /videos/* e /videos/hd/* são válidos para regras de caminho, mas /videos* e /videos/hd* não.

• As regras de caminho não usam expressões regulares ou correspondência de substring. PathTemplateMatch pode usar operadores simplificados de correspondência de caminho. 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 de caminho para /video/* se aplica a esse caminho.

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

• As correspondências de caminho (e mapas de URL, em geral) não oferecem recursos que funcionam como a diretiva <LocationMatch> do Apache. Se você tem um aplicativo que gera caminhos de URL dinâmico com um prefixo comum, como /videos/hd-abcd e /videos/hd-pqrs, e precisa enviar as solicitações feitas a esses caminhos para diferentes serviços de back-end, talvez não seja possível fazer isso sem um mapa de URL. Em casos que contêm somente alguns URLs dinâmicos possíveis, talvez seja possível criar uma correspondência de caminho com o conjunto limitado de regras de caminho. Nos casos mais complexos, é necessário fazer a correspondência de expressões regulares baseadas em caminhos nos back-ends.

Caracteres curinga e operadores de correspondência de padrões em modelos de caminho para regras de rota

Com os operadores de correspondência de padrão flexível, é possível corresponder várias partes de um caminho de URL, incluindo URLs parciais e sufixos (extensões de arquivo), usando uma sintaxe de caracteres curinga. Esses operadores podem ser úteis quando você precisa rotear o tráfego e executar substituições com base em caminhos de URL complexos. Também é possível associar um ou mais componentes de caminho a variáveis nomeadas e, em seguida, consultá-las ao reescrever o URL. Com variáveis nomeadas, é possível reordenar e remover componentes de URL antes que a solicitação seja enviada à sua origem.

A correspondência de padrões com caracteres curinga é compatível apenas com os seguintes produtos:

• Balanceador de carga de aplicativo externo global

• Balanceador de carga de aplicativo externo regional
• Balanceador de carga de aplicativo interno regional

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

O exemplo a seguir direciona o tráfego de um aplicativo de e-commerce que tem serviços separados para informações do carrinho e do usuário. É possível configurar routeRules com operadores de correspondência flexível de padrões e variáveis nomeadas para enviar o ID exclusivo do usuário a uma página de detalhes da conta de usuário e as informações do carrinho do usuário para um serviço de processamento de carrinho depois de 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 solicita /xyzwebservices/v2/xyz/users/[e-mail]/carts/FL0001090004/entries/SJFI38u3401nms?fields=FULL&client_type=WEB, que tem informações do usuário e do carrinho:

1. O caminho da solicitação corresponde ao pathTemplateMatch no pathMatcher cart-matcher. 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 adicionados a final do caminho reescrito. Use apenas as mesmas variáveis que usamos para definir o pathTemplateMatch em nosso pathTemplateRewrite.
3. A solicitação reescrita é enviada para cart-backend com o caminho do URL reescrito: /[e-mail]-FL0001090004/entries/SJFI38u3401nms?fields=FULL&client_type=WEB.

Veja a seguir o que acontece quando um cliente solicita /xyzwebservices/v2/xyz/users/abc%40xyz.com/accountinfo/abc-1234, que tem apenas informações da conta e do usuário:

1. O caminho da solicitação corresponde ao pathTemplateMatch no pathMatcher user-matcher. O primeiro * corresponde a abc%40xyz.com, e o segundo * corresponde a abc-1234.
2. A solicitação é enviada para user-backend.

A tabela a seguir descreve a sintaxe para padrões de modelo de caminho.

Operador	Correspondências
*	Um único segmento de caminho, sem incluir os caracteres separadores de caminho / adjacentes.
**	Corresponde a zero ou mais caracteres, incluindo qualquer caractere separador de caminho / entre vários segmentos de caminho. Se outros operadores estiverem inclusos, o operador ** precisará ser o último.
{name} ou {name=*}	Uma variável nomeada que corresponde a um só segmento de caminho. Corresponde a um único segmento de caminho, sem incluir os caracteres separadores de caminho / adjacentes.
{name=news/*}	Uma variável nomeada que corresponde explicitamente a dois segmentos de caminho: news e um segmento de caractere curinga *.
{name=*/news/*}	Uma variável nomeada que corresponde a três segmentos de caminho.
{name=**}	Uma variável nomeada que corresponde a zero ou mais caracteres. Se presente, precisa ser o último operador.

Ao usar esses operadores para correspondência flexível de padrões, tenha em mente as seguintes considerações:

• Vários operadores podem ser combinados em um ú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 adicionados ao final do caminho reescrito.
• As solicitações não são normalizadas com codificação percentual. Por exemplo, um URL com um caractere de barra codificado por porcentagem (%2F) não é decodificado no formulário não codificado.
• Cada nome de variável, como {segment} ou {region}, pode aparecer apenas uma vez no mesmo padrão. Múltiplas variáveis com o mesmo nome são inválidas e são rejeitadas.
• Os nomes das variáveis diferenciam maiúsculas de minúsculas e precisam ser identificadores válidos. Para verificar se o nome de uma variável é válido, verifique se ele corresponde à expressão regular ^[a-zA-Z][a-zA-Z0-9_]*$.
  • {API}, {api} e {api_v1} são identificadores válidos. Eles identificam três variáveis distintas.
  • {1}, {_api} e {10alpha} não são identificadores válidos.
• Há um limite de cinco operadores por padrão de modelo.

Para executar uma reescrita de URL opcional antes do envio da solicitação à origem, use as mesmas variáveis definidas para capturar um caminho. Por exemplo, é possível referenciar, reordenar ou omitir variáveis no campo pathTemplateRewrite ao definir urlRewrite.

Ao usar variáveis e operadores para correspondência flexível de padrões para reescritas de URL, tenha em mente as seguintes considerações:

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

Exemplo de fluxo de trabalho de mapa de URL com um balanceador de carga de aplicativo externo

No exemplo a seguir, veja a ordem das operações de um mapa de URL. Neste exemplo, apenas o mapa de URL de um balanceador de carga de aplicativo clássico que já existe é configurado. Para simplificar o conceito, ele usa apenas serviços de back-end. No entanto, é possível substituir por buckets de back-end. Para saber como criar os outros componentes do balanceador de carga, consulte Criar um balanceador de carga de aplicativo clássico.

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

1. Crie um mapa de URL para o balanceador de carga e especifique um serviço de back-end padrão. Nesse exemplo, criamos um mapa de URL denominado video-org-url-map que referencia um serviço de back-end denominado org-site.

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

2. Crie uma correspondência de caminho denominada video-matcher com as seguintes características:

   • O serviço de back-end padrão é video-site, um serviço de back-end atual.
   • Adicione regras de caminho que direcionem solicitações para o caminho de URL /video/hd exato ou o prefixo /video/hd/* do caminho de URL para um serviço de back-end atual denominado video-hd.
   • Adicione regras de caminho que direcionem solicitações para o caminho de URL /video/sd exato ou o prefixo /video/sd/* do caminho de URL para um serviço de back-end atual 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 host para o nome de host example.net que faça referência à correspondência de caminho video-matcher.

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

O URL video-org-url-map terá esta aparência:

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 URL video-org-url-map direciona os URLs solicitados para os back-ends da maneira a seguir.

Mapa de URL com uma regra de caminho, correspondências de caminho e uma regra de host (clique para ampliar).

Veja na tabela a seguir a descrição do processamento da solicitação mostrado no diagrama anterior.

Nome do host	Caminhos de URL	Serviço de back-end selecionado	Motivo da seleção
O nome do host: example.org e todos os outros nomes de host diferentes de example.net	todos os caminhos	org-site	O nome de host não está em nenhuma regra de host do mapa de URL, portanto, a solicitação é direcionada para o serviço de back-end padrão do mapa de URL.
Nome do host: example.net	/video /video/examples	video-site	A solicitação vai para o serviço de back-end padrão porque não há nenhuma regra de caminho para /video/ ou /video/*. A regra de host para example.net referencia uma correspondência de caminho, mas ela não tem nenhuma regra que se aplica a esses caminhos.
Nome do host: example.net	/video/hd /video/hd/movie1 /video/hd/movies/movie2 Outros URLs que começam com /video/hd/*	video-hd	Uma regra de host para example.net referencia uma correspondência de caminho com regras que direcionam as solicitações para caminhos do URL que correspondem exatamente a /video/hd ou que começam com /video/hd/* para o serviço de back-end video-hd.
Nome do host: example.net	/video/sd /video/sd/show1 /video/sd/shows/show2 Outros URLs que começam com /video/sd/*	video-sd	Uma regra de host para example.net referencia uma correspondência de caminho com regras que direcionam as solicitações para caminhos do URL que correspondem exatamente a /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 domínio de um URL para outro.

Um redirecionamento de URL padrão não é condicionado na correspondência de um padrão específico na solicitação recebida. Por exemplo, é possível usar um redirecionamento de URL padrão para redirecionar qualquer nome de host para um nome de host de sua escolha.

Há várias maneiras de criar um redirecionamento de URL, conforme descrito na tabela a seguir.

Método	Configuração
Redirecionamento de URL padrão do mapa de URL	Alto nível defaultUrlRedirect
Redirecionamento de URL padrão de uma correspondência de caminho	pathMatchers[].defaultUrlRedirect[]
Redirecionamento de URL de uma regra de caminho de correspondência de caminho	pathMatchers[].pathRules[].urlRedirect
Redirecionamento de URL da regra de rota de uma correspondência de caminho	pathMatchers[].routeRules[].urlRedirect

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

• Todo o caminho da solicitação é substituído pelo caminho especificado.

Dentro de um defaultUrlRedirect ou urlRedirect, a forma como o prefixRedirect funciona depende de como você o usa:

• Se você usar um defaultUrlRedirect, prefixRedirect será efetivamente uma adição de prefixo porque o caminho correspondente é sempre /.
• Se você usar um urlRedirect na regra de rota ou na regra de caminho de uma correspondência de caminho, prefixRedirect é um prefixo Substituição com base na correspondência do caminho solicitado conforme definido na regra de caminho ou na regra de rota.

Exemplos de redirecionamento

Veja na tabela a seguir alguns exemplos de configurações de redirecionamento. A coluna à direita mostra a configuração da API para um redirecionamento de URL padrão.

Você quer	Ativado usando um redirecionamento de URL padrão
Redirecionamento de HTTP para HTTPS Redirecionamento http://host.name/path para https://host.name/path	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True
HTTP para HTTPS + redirecionamento de host 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 host + redirecionamento de caminho completo Redirecionamento 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 host + 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 snippet parcial a seguir insere anotações em 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 ?
   ...

A seguir

• Saiba como adicionar, validar, testar, listar ou excluir um mapa de URL em Como usar mapas de URL.

• Para informações sobre mapas de regras de roteamento com o Cloud Service Mesh, consulte Visão geral dos mapas de regras de roteamento do Cloud Service Mesh.