Configure rotas de serviço

A RFC de multimédia oferece capacidades de encaminhamento HTTP avançadas que lhe permitem mapear o tráfego para configurações e origens específicas na extremidade da rede a um nível detalhado.

Configure uma regra de trajeto

Configure uma regra de encaminhamento para um serviço de RFC de conteúdo multimédia.

Consola

  1. Na Google Cloud consola, aceda à página RFC de multimédia.

    Aceda à RFC de multimédia

  2. Para abrir a página Detalhes do serviço para o qual quer configurar uma regra de encaminhamento, clique no nome do serviço.

  3. Para mudar para o modo de edição, clique no botão Editar.

  4. Para navegar para a secção Encaminhamento, clique em Seguinte.

  5. Especifique, pelo menos, uma regra de anfitrião. Clique em Adicionar regra de anfitrião. Em seguida, faça o seguinte:

    1. Para Anfitriões, especifique, pelo menos, um anfitrião para correspondência.

    2. Em Descrição, indique uma breve descrição da regra de anfitrião.

    Em alternativa, para editar uma regra de anfitrião, clique na seta para a expandir.

  6. Especifique, pelo menos, uma regra de encaminhamento. Clique em Adicionar regra de encaminhamento.

    Em alternativa, para editar uma regra de encaminhamento, clique em Editar na linha respetiva.

  7. No painel Editar regra de encaminhamento, para Prioridade, defina um valor para a prioridade de encaminhamento.

  8. Em Descrição, indique uma breve descrição que possa ajudar a identificar a regra numa lista de regras.

  9. Na secção Correspondência, especifique, pelo menos, uma condição de correspondência. Clique em Adicionar uma condição de correspondência. Em seguida, faça o seguinte:

    1. Para Tipo de correspondência, selecione qualquer opção de correspondência de caminho.

    2. Para Correspondência do caminho, especifique os nomes, os caminhos ou os modelos. Considere usar a correspondência de padrões com carateres universais.

      Se necessário, selecione também Ativar sensibilidade a maiúsculas e minúsculas para o valor do caminho.

    3. Opcional: selecione Os cabeçalhos correspondem e Os parâmetros de consulta correspondem. Em seguida, clique nos botões relevantes para adicionar cabeçalhos e parâmetros de consulta. Para cada um, especifique o nome, o tipo de correspondência e o valor.

      Para mais informações, consulte o artigo Faça a correspondência com base nos cabeçalhos e nos parâmetros de consulta.

    4. Para guardar a condição de correspondência, clique em Concluído.

  10. Para Ação principal, selecione uma das seguintes opções:

    • Obter a partir de uma origem: para direcionar pedidos para uma origem específica, selecione esta opção e, de seguida, selecione uma origem.

    • Redirecionamento de URL: para redirecionar pedidos, selecione esta opção. Em seguida, especifique o tipo de redirecionamento, o caminho e o código de estado.

      Opcionalmente, selecione as opções para redirecionar todas as respostas para HTTPS ou remover a consulta.

  11. Clique em Configurações avançadas.

    1. Na secção Ação do cabeçalho, clique em Adicione um item.

      Selecione um tipo de ação e, de seguida, especifique um cabeçalho como um par de nome e valor. Em seguida, clique em Concluído.

    2. Na secção Ação de encaminhamento, clique em Adicione um item.

      Especifique um tipo de ação e as respetivas opções relacionadas. Em seguida, clique em Concluído.

  12. Para a filtragem de métodos HTTP, selecione Personalizar filtragem de métodos HTTP.

    Em seguida, selecione os métodos HTTP que quer encaminhar para a sua origem.

  13. Para guardar a regra de encaminhamento, clique em Guardar.

  14. Para guardar as alterações ao serviço, clique em Atualizar serviço.

gcloud e YAML

  1. Exporte a configuração da RFC de conteúdo multimédia para um ficheiro YAML. Use o comando gcloud edge-cache services export.

    gcloud edge-cache services export SERVICE_NAME \
    --destination=FILENAME.yaml

    Substitua o seguinte:

    • SERVICE_NAME: o nome do seu serviço
    • FILENAME : o nome do seu ficheiro YAML

  2. Atualize o ficheiro YAML com a configuração necessária, conforme descrito nas secções desta página.

  3. Para atualizar o serviço, importe a configuração da RFC de multimédia a partir do ficheiro YAML. Use o comando gcloud edge-cache services import.

    gcloud edge-cache services import SERVICE_NAME \
    --source=FILENAME.yaml

Pedidos de correspondência

Uma configuração da RFC de multimédia contém um conjunto de rotas definidas na secção Routing para um recurso EdgeCacheService. Estas rotas fazem corresponder pedidos com base (pelo menos) num anfitrião. Para mais detalhes sobre como o tráfego é direcionado para uma origem, consulte HostRule e PathMatcher. Cada rota pode definir a sua própria configuração de RFC, reescritas, redirecionamentos, políticas de CORS, cabeçalhos HTTP personalizados e mapeamento de origem. Os trajetos podem partilhar origens.

Por exemplo, pode encaminhar pedidos de manifestos para uma origem específica e definir um TTL da cache de curta duração e uma política de colocação em cache negativa. Os pedidos de segmentos podem ser divididos para outra origem através de cabeçalhos e parâmetros de consulta para discriminar tipos de manifestos ou utilizadores específicos.

O exemplo seguinte mostra como encaminhar pedidos que correspondem a um cabeçalho específico, a um parâmetro de consulta e a um prefixo do caminho para o anfitrião media.example.com:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 10
      origin: staging-live-origin
      matchRules:
      - prefixMatch: /vod/
        headerMatches:
        - headerName: "x-staging-client"
          presentMatch: true
        queryParameterMatches:
        - name: "live"
          exactMatch: "yes"
      routeAction:
        cdnPolicy:
          defaultTtl: 5s

Correspondência de caminhos

A RFC é compatível com a correspondência de caminhos completa (exata), de prefixos e de carateres universais. A correspondência de caminhos pode ser combinada com a correspondência baseada em anfitriões, cabeçalhos e parâmetros de consulta para criar regras de encaminhamento de pedidos detalhadas.

Seguem-se três formas de fazer a correspondência com um caminho de URL.

Campo Descrição Exemplo
matchRules[].fullPathMatch A condição fullPathMatch corresponde ao caminho do URL completo, que não inclui a string de consulta. Tem de especificar barras invertidas finais, se relevante.

Um trajeto com uma regra de correspondência de fullPathMatch: "/stream/" corresponde a /stream/, mas não a /stream nem a /stream/us/hls/1234.ts.

Um fullPathMatch é uma correspondência explícita (exata).
matchRules[].prefixMatch A condição prefixMatch corresponde ao prefixo do caminho do URL; os URLs que começam com a mesma string correspondem.

Uma rota com uma regra de correspondência de prefixMatch: "/videos/" corresponde a /videos/hls/58481314/manifest.m3u8 e /videos/dash porque ambas contêm o prefixo /videos/.
matchRules[].pathTemplateMatch A condição pathTemplateMatch suporta operadores de carateres universais, o que lhe permite fazer corresponder padrões de URL complexos e segmentos de caminhos, bem como capturar variáveis com nomes para reescrever URLs.

Uma rota com uma regra de correspondência de pathTemplateMatch: "/**.m3u8" corresponde a qualquer caminho de URL que termine com .m3u8.

Ambos os URLs /content/en-GB/13/51491/manifest_193193.m3u8 e /p/abc/1234/manifest_1080p5000.m3u8 correspondem a este padrão.

Para mais exemplos, consulte a secção Correspondência de padrões.

Para mais detalhes, consulte a especificação da API para MatchRule.

Por exemplo, para fazer corresponder todos os pedidos que começam por /stream/, crie uma regra de encaminhamento semelhante à seguinte:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    - *.vod.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      matchRules:
      - prefixMatch: /stream/

Este exemplo inclui explicitamente a barra invertida final na regra de correspondência:

  • Um pedido para media.example.com/stream/id/1234/hls/manifest.m3u8 corresponde a este trajeto.
  • Um pedido para media.example.com/stream-eu/id/4567/hls/manifest.m3u8 não corresponde a este trajeto.

No segundo caso, a RFC de conteúdo multimédia devolve um erro HTTP 404, a menos que exista outra rota ou uma rota genérica configurada.

Para orientações sobre como a precedência funciona para rotas com prefixos semelhantes, consulte a secção Prioridade e ordenação de rotas.

Correspondência de padrões (caracteres universais)

A correspondência de padrões permite-lhe fazer corresponder várias partes de um URL, incluindo URLs parciais e sufixos (extensões de ficheiros), através da sintaxe de carateres universais.

Também pode associar um ou mais segmentos do caminho a variáveis com nomes num campo pathTemplateMatch e, em seguida, referir-se a essas variáveis ao reescrever o URL num campo pathTemplateRewrite. Isto permite-lhe reordenar e remover segmentos de URL antes de o pedido ser enviado para a sua origem.

O exemplo seguinte mostra como pode fazer a correspondência com dois sufixos de URL diferentes:

# EdgeCacheService.routing.pathMatchers[]
    routeRules:
    - priority: 1
      description: "Match video segments"
      matchRules:
      - pathTemplateMatch: "/**.ts"
      - pathTemplateMatch: "/**.m4s"
      origin: prod-video-storage

A sintaxe suportada inclui o seguinte.

Operador Correspondências Exemplo
* Corresponde a um único segmento de caminho, até ao separador de caminho seguinte: / /videos/*/*/*.m4s correspondências /videos/123414/hls/1080p5000_00001.m4s.
** Corresponde a zero ou mais segmentos do caminho. Se estiver presente, tem de ser o último operador. /**.mpd correspondências /content/123/india/dash/55/manifest.mpd.
{name} or {name=*}

Uma variável com nome que corresponda a um segmento do caminho.

Corresponde a um único segmento do caminho, até ao separador do caminho seguinte: /.

/content/{format}/{lang}/{id}/{file}.vtt corresponde /content/hls/en-us/12345/en_193913.vtt e captura format="hls", lang="en-us", id="12345" e file="en_193913" como variáveis.
{name=videos/*} Uma variável com nome que corresponde a mais de um segmento do caminho. O segmento do caminho que corresponde a videos/* é capturado como a variável com nome. /videos/{language=lang/*}/* corresponde a /videos/lang/en/video.m4s e preenche a variável de caminho language com o valor lang/en.
{name=**}

Uma variável com nome que corresponde a zero ou mais segmentos do caminho.

Se estiver presente, tem de ser o último operador.

/**.m3u8 ou /{path=**}.m3u8 corresponde a todos os segmentos do caminho até à extensão.

/videos/{file=**} corresponde a /videos/en-GB/def566/manifest.m3u8, incluindo a extensão, e captura a variável de caminho file="en-GB/def566/manifest.m3u8.

Notas:

  • Se não estiver a reescrever um URL, use os operadores mais simples * e **.
  • Quando usa variáveis para capturar segmentos do caminho, não é possível fazer referência a nenhuma parte do URL que não seja capturada por uma variável num pathTemplateRewrite subsequente. Para ver um exemplo, consulte a secção Capturar variáveis de caminho.
  • Não pode fazer referência a variáveis num pathTemplateRewrite subsequente que não existam no pathTemplateMatch no mesmo trajeto.
  • As variáveis são sensíveis a maiúsculas e minúsculas, com {FORMAT}, {forMAT} e {format} a representar diferentes variáveis e valores.
  • Pode especificar até 10 operadores (caracteres universais ou variáveis) numa correspondência. Os campos pathTemplateMatch e pathTemplateRewrite não podem exceder os 255 carateres.

Exemplo: fazer correspondência com uma extensão de ficheiro

O exemplo seguinte mostra um exemplo de utilização comum para operadores de carateres universais: estabelecer correspondência com todos os segmentos do caminho até um sufixo.

Neste caso, faz o seguinte:

  • Obter manifestos de vídeo (playlists) que terminam em .m3u8 e .mpd da origem do manifesto, aplicando um TTL curto (5 segundos) a estas respostas porque mudam regularmente.
  • Obter segmentos de vídeo que terminam em .ts e .m4s a partir da origem do segmento e aplicar um TTL mais longo (1 dia) a estas respostas.

Esta abordagem é frequentemente usada quando se usam serviços de SSAI (inserção de anúncios do lado do servidor) ou DAI (inserção de anúncios dinâmicos) e para vídeo em direto em que o manifesto é atualizado a cada poucos segundos.

A configuração seguinte demonstra como configurar o encaminhamento da RFC para suportar esta funcionalidade:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    # the first route only matches video manifests
    - priority: 1
      matchRules:
      - pathTemplateMatch: "/**.m3u8" # "**" matches all path segments
      - pathTemplateMatch: "/**.mpd"
      origin: manifest-origin
      routeAction:
        cdnPolicy:
          cacheMode: FORCE_CACHE_ALL
          defaultTtl: 5s
    # the second route matches video segments, fetches them
    # from a separate origin server, caching them for a longer
    # duration (1 day).
    - priority: 2
      matchRules:
      - pathTemplateMatch: "/**.ts"
      - pathTemplateMatch: "/**.m4s"
      origin: segment-origin
      routeAction:
        cdnPolicy:
          cacheMode: FORCE_CACHE_ALL
          defaultTtl: 86400s

Exemplo: capture variáveis de caminho

O exemplo seguinte mostra como usar variáveis com nomes para descrever um ou mais segmentos do caminho.

Estas variáveis podem ser usadas num pathTemplateRewrite para reescrever o caminho antes de o pedido ser enviado para a origem ou para tornar um pathTemplateMatch complexo autodescritivo.

routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      matchRules:
      # Matches a request of "/us/en/hls/123139139/segments/00001.ts"
      - pathTemplateMatch: "/{country}/{lang}/{format}/{id}/{file=**}"
      origin: my-origin
      routeAction:
        urlRewrite:
          # Rewrites to "/123139139/hls/segments/00001.ts"
          pathTemplateRewrite: "/{id}/{format}/{file}"

Em concreto:

  • Cada variável {name} capta um único segmento do caminho. Um segmento de caminho é o conjunto de carateres entre um par de / ("barras") num caminho de URL.
  • Uma variável de {name=**} capta todos os segmentos do caminho restantes. Neste caso, corresponde a segments/00001.ts e master.m3u8.
  • No pathTemplateRewrite na mesma rota, faz referência a algumas das variáveis que captou no pathTemplateMatch. Omitir explicitamente as variáveis {country} e {lang} porque não correspondem à estrutura de diretórios na origem.

Com este exemplo, ocorre o seguinte:

  • Um URL de pedido recebido de /us/en/hls/123139139/segment_00001.ts corresponde a pathTemplateMatch e é reescrito para /123139139/hls/segment_00001.ts antes de ser enviado para a origem.
  • Um URL de pedido recebido de /us/123139139/master.m3u8 não corresponde a pathTemplateMatch e recebe uma resposta HTTP 404 (Not Found).
  • Um URL de pedido recebido de /br/es/dash/c966cbbe6ae3/subtitle_00001.vtt também corresponde a pathTemplateMatch e é reescrito para /c966cbbe6ae3/dash/subtitle_00001.vtt antes de ser enviado para a origem.

Para saber como a correspondência com carateres universais interopera com a reescrita de URLs, consulte a secção reescritas.

Correspondência de anfitriões

Cada serviço pode corresponder a vários nomes de anfitrião, com cada conjunto de nomes de anfitrião a conter o seu próprio grupo de rotas (conhecido como correspondências de caminhos). No caso mais comum, todos os nomes de anfitriões de um serviço são mapeados para um único conjunto de rotas partilhadas com uma única lista de anfitriões e um único localizador de caminhos.

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    - *.vod.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    # list of routes for the configured hosts
    - priority: 999
      matchRules:
      - prefixMatch: /
      origin: DEFAULT_ORIGIN

Os anfitriões que não correspondem recebem uma página HTTP 404 predefinida. Para aceitar qualquer anfitrião, pode incluir o caráter universal * como uma entrada hostRules[].hosts[].

Também pode definir grupos de trajetos (por exemplo, agrupando por país ou em direto versus a pedido). Uma vez que cada serviço tem uma única política de segurança, recomendamos geralmente que tenha um serviço para cada mercado (geografia) ou carga de trabalho que tiver.

Notas:

  • Os cabeçalhos de anfitrião (ou HTTP/2 :authority) que contêm uma porta são implicitamente correspondidos com um anfitrião configurado. Não precisa de especificar explicitamente as portas.
  • Se o pedido for através de HTTP, uma entrada hostRules[].hosts[] de *.vod.example.com corresponde a us.vod.example.com e us.vod.example.com:80.
  • Se o pedido for através de HTTPS (TLS), uma entrada hostRules[].hosts[] de *.vod.example.com corresponde a us.vod.example.com:443.

Para mais detalhes, consulte a especificação da API para HostRule.

Corresponda a cabeçalhos e parâmetros de consulta

Pode configurar rotas para corresponder a nomes de parâmetros de consulta e cabeçalhos específicos, bem como à presença de um valor de cabeçalho (prefixo, sufixo ou correspondência exata).

A correspondência de parâmetros de consulta e cabeçalhos é "AND" lógico. O pedido tem de corresponder a todos os parâmetros de consulta e chaves de cabeçalho (e valores, se especificados) para corresponder à rota fornecida.

Por exemplo, se quiser encaminhar pedidos com um nome de campo de cabeçalho e um valor de cabeçalho específicos para uma origem denominada alternate-origin, configure as condições de correspondência em routeRules[].matchRules[].headerMatches[]:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: alternate-origin
      matchRules:
      - prefixMatch: "/videos/"
        headerMatches:
        - headerName: "x-device-name"
          exactMatch: "roku"

Neste exemplo, os pedidos com /videos/ no início do URL e o cabeçalho x-device-name: roku correspondem a esta rota. Os pedidos que não tenham este nome do cabeçalho ou que tenham um valor diferente não correspondem a esta rota.

Para mais detalhes, consulte a especificação da API para HeaderMatch.

Da mesma forma, para fazer a correspondência com parâmetros de consulta, especifique um ou mais queryParameterMatches da seguinte forma:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: eu-live-origin-prod
      matchRules:
      - prefixMatch: "/videos/"
        queryParameterMatches:
        - name: "playback_type"
          exactMatch: "live"
        - name: "geo"
          exactMatch: "eu"

Neste exemplo, um pedido do cliente de https://cdn.example.com/videos/1234/abcd/xyz.m3u8?playback_type=live&geo=eu corresponde a esta rota.

Para mais detalhes, consulte a especificação da API para QueryParameterMatcher.

Defina um trajeto genérico (predefinido)

Por predefinição, a RFC de multimédia devolve um erro HTTP 404 (Not Found) se um pedido não corresponder a nenhuma rota configurada.

Para configurar uma rota geral para um determinado pathMatcher (conjunto de rotas), faça o seguinte:

  • Crie um routeRule com a prioridade mais baixa (número mais elevado), por exemplo, 999, que é a prioridade de rota mais baixa possível.
  • Configure um matchRule com uma correspondência de prefixo de / (corresponde a todos os caminhos de pedido).
  • Configure (uma das) uma origin ou uma urlRedirect no trajeto.

Por exemplo, para configurar uma rota geral que direcione todos os pedidos não correspondentes para uma origem predefinida denominada my-origin, crie uma nova rota com priority: 999 e um matchRules[].prefixMatch de / da seguinte forma:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 999
      origin: my-origin
      matchRules:
      - prefixMatch: /

Opcionalmente, pode reescrever o URL antes da obtenção da origem ou redirecionar para uma página predefinida (como a página de destino) em vez de enviar o pedido "tal como está" para a origem.

Prioridade e ordenação dos trajetos

Cada trajeto numa matriz de routeRules[] tem de ter um priority associado.

As rotas mais específicas devem ser definidas com uma prioridade mais alta (número mais pequeno). Um percurso que corresponda a um prefixo de /stream/ com uma prioridade de 1 impede, caso contrário, que um percurso mais específico de /stream/live/eu/ com uma prioridade de 5 corresponda a quaisquer pedidos.

  • O caminho de prioridade mais elevada é "1" e o mais baixo é "999".
  • Não pode configurar duas ou mais routeRules com a mesma prioridade. A prioridade de cada regra tem de ser definida como um número entre 1 e 999, inclusive.
  • A definição de uma rota genérica permite-lhe enviar todos os pedidos não correspondentes para uma origem predefinida ou redirecioná-los para uma página de destino ou um ponto final.

No exemplo seguinte, pode ver que a rota /live/us/ nunca seria encontrada porque a rota /live/ tem uma prioridade mais elevada:

routeRules:
- priority: 1
  description: "Live routes"
  matchRules:
  - prefixMatch: /live/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 2
  description: "U.S based live streams"
  matchRules:
  # This would never be matched, as the /live/ prefixMatch at priority 1
  # would always take precedence.
  - prefixMatch: /live/us/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 999
  description: "Catch-all route"
  matchRules:
  - prefixMatch: /

Para resolver este problema, coloque a rota mais específica (mais longa) com uma prioridade mais elevada:

routeRules:
- priority: 1
  description: "U.S based live streams"
  matchRules:
  # The more specific (longer) match is at a higher priority, and now
  # matches requests as expected.
  - prefixMatch: /live/us/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 2
  description: "Live routes"
  matchRules:
  - prefixMatch: /live/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 999
  description: "Catch-all route"
  matchRules:
  - prefixMatch: /

Isto permite que a rota mais específica corresponda corretamente aos pedidos. Um pedido com o prefixo /live/eu/ continuaria a ser encaminhado para a rota /live/ com prioridade 2.

Filtragem de métodos

Por predefinição, a RFC de multimédia envia apenas os métodos GET, HEAD e OPTIONS para a sua origem e filtra os métodos que podem modificar a sua origem.

Pode substituir este comportamento predefinido para uma regra de trajeto específica, especificando os métodos que quer encaminhar por proxy para a sua origem. Além de GET, HEAD e OPTIONS, a Media CDN suporta PUT, POST, DELETE e PATCH.

Para configurar o suporte de um conjunto de métodos para uma regra de trajeto, especifique uma secção routeMethods que tenha um valor allowed_methods para cada método.

routeRules:
- priority: 5
  description: "Video uploads"
  routeMethods:
    allowedMethods: ["PUT", "POST", "OPTIONS"]
  matchRules:
  - pathTemplateMatch: "/uploads/**.ts"
  origin: prod-video-storage
- priority: 10
  description: "Video serving"
  routeMethods:
    allowedMethods: ["GET", "HEAD"]
  matchRules:
  - pathTemplateMatch: "/videos/**.ts"
  origin: prod-video-storage

Normalização do caminho

A normalização do caminho descreve como a RFC de multimédia combina várias representações de um URL numa única representação canónica em cenários específicos.

A normalização de caminhos pode melhorar diretamente as taxas de acertos da cache, reduzindo o número de URLs de pedidos que representam o mesmo conteúdo e mitigando erros de origem para origens que esperam caminhos normalizados.

Os pedidos recebidos são normalizados da seguinte forma:

  • As várias barras invertidas consecutivas são unidas numa única barra invertida. Por exemplo, um caminho do URL de /videos///12345/manifest.mpd é normalizado para /videos/12345/manifest.mpd.
  • Os segmentos de caminho são normalizados de acordo com a secção 6.2.2.3 da RFC 3986. Por exemplo, o caminho /a/b/c/./../../g é normalizado para /a/g com base no algoritmo "remove dot segments" definido na RFC 3986. Esta normalização ocorre antes de verificar a cache ou encaminhar o pedido para a origem.
  • Os pedidos não são normalizados com codificação percentual. Por exemplo, um URL com um caráter de barra codificado em percentagem (%2F) não é descodificado para o formato não codificado.

Os URLs permanecem sensíveis a maiúsculas e minúsculas e não são normalizados em termos de maiúsculas e minúsculas. Muitos URLs contêm codificações base64 sensíveis a maiúsculas e minúsculas, incluindo URLs com tokens de pedido assinado.

Reescritas e redirecionamentos

As secções seguintes fornecem exemplos sobre como reescrever pedidos e configurar redirecionamentos.

Rescreva URLs de pedidos

A RFC 7230 (Hypertext Transfer Protocol (HTTP/1.1)) é uma especificação técnica que descreve o protocolo HTTP/1.1. A reescrita altera o URL enviado para a origem e permite-lhe modificar os anfitriões e os caminhos conforme necessário. As reescritas de anfitrião e caminho estão ao nível da rota, o que lhe permite definir que pedidos específicos são reescritos com base em qualquer correspondência, incluindo o caminho, o parâmetro de consulta e o cabeçalho do pedido.

Para mais detalhes, consulte a especificação da API para RouteAction.UrlRewrite.

Seguem-se três formas de reescrever um pedido:

Campo Descrição
urlRewrite.pathPrefixRewrite

Reescreve o caminho, removendo o prefixo especificado no prefixMatch que correspondeu ao pedido.

Só é possível especificar um de pathPrefixRewrite ou pathTemplateRewrite numa única regra de encaminhamento.

urlRewrite.pathTemplateRewrite

pathTemplateRewrite só pode ser usado com uma regra de correspondência pathTemplateMatch correspondente na mesma rota.

Só é possível especificar um de pathPrefixRewrite ou pathTemplateRewrite numa única regra de encaminhamento.

urlRewrite.hostRewrite Reescreve o anfitrião antes de o pedido ser enviado para o servidor de origem.

Notas:

  • Os URLs reescritos não alteram a chave da cache. A chave da cache baseia-se no URL do pedido enviado pelo cliente.
  • A reescrita ocorre após a correspondência de rotas e a validação de pedidos assinados. As rotas não são novamente associadas a outra regra de correspondência.

Exemplo: remova um prefixo do caminho

Por exemplo, para reescrever um URL de pedido de cliente de /vod/videos/hls/1234/abc.ts para /videos/hls/1234/abc.ts (removendo /vod do caminho), pode usar a funcionalidade pathPrefixRewrite:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: my-origin
      matchRules:
      - prefixMatch: "/vod/videos/"
      routeAction:
        urlRewrite:
          pathPrefixRewrite: "/videos/"

Um pathPrefixRewrite funciona substituindo o prefixo do caminho completo com correspondência no matchRules[].prefixMatch pelo valor de pathPrefixRewrite.

Para reescrever um nome do anfitrião (por exemplo, reescrever cdn.example.com para my-bucket.s3.us-west-2.amazonaws.com), pode configurar o seguinte:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: my-origin
      matchRules:
      - prefixMatch: "/videos/"
      routeAction:
        urlRewrite:
          hostRewrite: "my-bucket.s3.us-west-2.amazonaws.com"

Neste caso, o URL do pedido de origem seria alterado de cdn.example.com/videos/* para my-bucket.s3.us-west-2.amazonaws.com/videos/*. Também pode combinar reescritas de anfitrião e caminho numa única rota.

Exemplo: use variáveis para reescrever URLs

Para usar pathTemplateMatch e pathTemplateRewrite para reescrever partes de um URL de pedido recebido, consulte a secção Capturar variáveis.

Pedidos de redirecionamento

A RFC de multimédia suporta três tipos de redirecionamentos:

  • Redirecionamentos de anfitrião, que redirecionam apenas o anfitrião (domínio), mantendo o caminho e os parâmetros de consulta inalterados.
  • Redirecionamentos de caminhos, que substituem o caminho na íntegra.
  • Redirecionamentos de prefixo do caminho, que apenas substituem o prefixo correspondente.

Os redirecionamentos são predefinidos para HTTP 301 (Moved Permanently), mas podem ser configurados para devolver códigos de estado de redirecionamento diferentes por rota.

A configuração seguinte é um exemplo de um redirecionamento baseado em prefixos, em que redireciona os utilizadores que visitam https://cdn.example.com/on-demand/* para https://cdn.example.com/streaming/*.

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 10
      matchRules:
      - prefixMatch: "/on-demand/"
      urlRedirect:
        # The prefix matched in matchRules.prefixMatch is replaced
        # by this value
        prefixRedirect: "/streaming/"
        redirectResponseCode: TEMPORARY_REDIRECT # corresponds to a HTTP 307

Este exemplo também altera o redirecionamento para um redirecionamento temporário, o que impede que os clientes (como os navegadores) o armazenem em cache. Isto pode ser útil se esperar alterá-lo num futuro próximo.

Os valores redirectResponseCode suportados são apresentados na tabela seguinte.

Código de resposta de redirecionamento Código de estado HTTP
MOVED_PERMANENTLY_DEFAULT HTTP 301 (Movido permanentemente)
FOUND HTTP 302 (Encontrado)
SEE_OTHER HTTP 303 (See Other)
TEMPORARY_REDIRECT HTTP 307 (redirecionamento temporário)
PERMANENT_REDIRECT HTTP 308 (redirecionamento permanente)

Notas:

  • Uma rota pode direcionar o tráfego para uma origem ou devolver um redirecionamento ao cliente. Não pode definir os campos origin e urlRedirect ao mesmo tempo.
  • As rotas que redirecionam para HTTPS requerem que, pelo menos, um certificado SSL esteja anexado ao serviço.

Para mais detalhes, consulte a especificação da API para RouteRule.UrlRedirect.

Redirecione todos os pedidos para HTTPS

Para redirecionar todos os pedidos para HTTPS (em vez de HTTP), pode configurar cada um dos seus serviços para redirecionar automaticamente todos os pedidos do cliente para HTTPS. Os clientes que se ligam através de HTTP recebem uma resposta HTTP 301 (Permanent Redirect) com o cabeçalho Location definido para o mesmo URL, mas usando "https://" em vez de "http://".

gcloud 

gcloud edge-cache services update MY_SERVICE \
    --require-tls
 
Request issued for: [MY_SERVICE]
Updated service [MY_SERVICE].

O comando devolve uma descrição do seu serviço, com requireTls agora definido como true.

  name: MY_SERVICE
  requireTls: true
HTTP.

Também pode optar por definir o cabeçalho Strict-Transport-Security como um cabeçalho de resposta para direcionar os clientes para se ligarem sempre diretamente através de HTTPS.

Use back-ends de armazenamento de terceiros

A RFC de multimédia suporta a ligação a pontos finais HTTP acessíveis publicamente fora do Google Cloud, incluindo contentores de armazenamento do AWS S3, armazenamento de blobs do Azure e outros fornecedores de armazenamento. Isto pode ser útil se tiver uma arquitetura de várias nuvens ou ainda não tiver migrado dados para o Cloud Storage através do Serviço de transferência de armazenamento.

Uma configuração de origem mínima que configura um contentor alojado virtualmente no AWS S3:

name: MY_S3_ORIGIN
originAddress: BUCKET-NAME.s3.REGION.amazonaws.com

Se não estiver a usar um nome de contentor que corresponda aos nomes de anfitriões configurados para os seus recursos EdgeCacheService, também tem de configurar uma reescrita de anfitrião para as rotas associadas a esta origem (ou origens). Caso contrário, o cabeçalho Host definido pelo pedido do cliente é usado quando a origem é obtida.

Por exemplo, para mapear todos os pedidos com um prefixo de caminho de /legacy/ para o seu contentor externo, pode configurar um hostRewrite e um pathPrefixRewrite para remover este prefixo do pedido de origem:

routeRules:
  - description: legacy backend
    matchRules:
    - prefixMatch: "/legacy/"
    routeAction:
      urlRewrite:
        hostRewrite: BUCKET-NAME.s3.REGION.amazonaws.com
        pathPrefixRewrite: /
      cdnPolicy:
        cacheMode: CACHE_ALL_STATIC
        defaultTtl: 3600s

Para mais informações sobre como o cabeçalho do anfitrião é definido em pedidos de origem, consulte a documentação sobre os cabeçalhos de pedidos de origem.

Partilha de recursos de origem cruzada (CORS)

A partilha de recursos de origem cruzada (CORS) é uma abordagem centrada no navegador para fazer pedidos de origem cruzada em segurança. As políticas CORS permitem-lhe definir automaticamente cabeçalhos CORS, como Access-Control-Allow-Origins, com base numa política por rota.

Configure o CORS

A RFC de multimédia permite-lhe definir uma política CORS numa rota para um EdgeCacheService.

Uma política CORS define estas regras com um conjunto comum de cabeçalhos HTTP. Pode definir cabeçalhos CORS comuns nas respostas, como Access-Control-Allow-Origin, Access-Control-Max-Age e Access-Control-Allow-Headers. Estes cabeçalhos permitem fazer chamadas de origem cruzada aos seus serviços de RFC de multimédia que podem estar alojados num domínio (origem) diferente do frontend do seu Website e podem impedir pedidos de origem cruzada que não permite explicitamente.

Por exemplo, player.example.com e api.example.com são origens diferentes (no sentido do navegador) e pode querer que a sua aplicação de front-end faça pedidos a api.example.com para obter a playlist seguinte ou atualizar uma lista de conteúdo relacionado. Da mesma forma, player.example.com pode ter de contactar cdn.example.com para obter playlists de vídeos e segmentos de vídeo: cdn.example.com tem de indicar que não há problema e que player.example.com é um allowed origin, bem como quaisquer outras regras (cabeçalhos permitidos, se os cookies podem ser incluídos).

Por exemplo, se quiser permitir stream.example.com como origem e um cabeçalho X-Client-ID em pedidos CORS, pode configurar um corsPolicy numa rota, da seguinte forma:

corsPolicy: maxAge: 600 allowOrigins: ["stream.example.com"] allowHeaders:
["X-Client-ID"]

Um corsPolicy está configurado em routing.pathMatchers[].routeRules[].routeAction.corsPolicy num EdgeCacheService. Cada routeRule pode definir um corsPolicy diferente, conforme necessário, ou nenhum.

Se definir um valor corsPolicy e também definir um cabeçalho da resposta personalizado através dos campos responseHeadersToAdd numa rota com o mesmo nome, o cabeçalho da resposta personalizado tem precedência sobre o valor corsPolicy e é usado em vez deste.

Se a resposta de origem definir cabeçalhos HTTP e tiver um valor corsPolicy definido, são usados os valores corsPolicy. Os valores não são reduzidos nem combinados para evitar o envio de valores de cabeçalho inválidos a um cliente ou a definição não intencional de uma política mais permissiva do que o pretendido.

O parâmetro especial {origin_request_header} é preenchido com o cabeçalho HTTP Origin no pedido do cliente. Pode ser definido como um valor de cabeçalho de resposta personalizado numa rota para o cabeçalho Access-Control-Allow-Origin.

Para mais detalhes, consulte a especificação da API para RouteAction.CORSPolicy.

Campos da política de CORS

A tabela seguinte descreve os campos que uma política CORS contém.

Campo Descrição Exemplo
allowOrigins

Define o cabeçalho da resposta Access-Control-Allow-Origins, que especifica as origens que podem fazer pedidos de origem cruzada num ambiente do navegador.

Por exemplo, se o conteúdo de vídeo for publicado a partir de https://video.example.com, mas o portal virado para o utilizador for publicado a partir de https://stream.example.com, adicionaria https://stream.example.com como origem permitida.

Access-Control-Allow-Origins: https://stream.example.com
maxAge

Define o cabeçalho de resposta Access-Control-Max-Age, que especifica durante quanto tempo, em segundos, um cliente do navegador deve colocar em cache a resposta a um pedido de verificação prévia de CORS.

Alguns navegadores limitam este valor a 2 horas ou menos, mesmo que o valor máximo (86 400 s) seja especificado.

 Access-Control-Max-Age: 7200
allowMethods

Define o cabeçalho de resposta Access-Control-Allow-Methods, que especifica os métodos HTTP que têm autorização para aceder ao recurso.

Por predefinição, a RFC de multimédia suporta apenas os métodos GET, HEAD e OPTIONS. Para configurar o suporte de outros métodos, consulte o artigo Métodos de planeamento de trajeto.

 Access-Control-Allow-Methods: GET, OPTIONS, HEAD
allowHeaders

Define o cabeçalho Access-Control-Allow-Headers, que determina que cabeçalhos podem ser enviados num pedido CORS.

Isto é frequentemente exigido pelos leitores de vídeo, que precisam de aceder a alguns cabeçalhos de resposta para conteúdo de vídeo quando o pedem de origem cruzada.

 Access-Control-Allow-Headers: Content-Type, If-Modified-Since, Range, User-Agent
exposeHeaders

Define o cabeçalho da resposta Access-Control-Expose-Headers, que determina a que cabeçalhos o JavaScript do lado do cliente pode aceder.

Isto é frequentemente exigido pelos leitores de vídeo, que podem precisar de aceder a cabeçalhos de resposta específicos para conteúdo de vídeo quando solicitam conteúdo de origem cruzada.

 Access-Control-Expose-Headers: Date, Cache-Status, Content-Type, Content-Length
allowCredentials

Define o cabeçalho de resposta Access-Control-Allow-Credentials, que permite que o JavaScript do lado do cliente inspecione a resposta para pedidos com credenciais incluídas.

Este cabeçalho é omitido quando definido como falso.

 Access-Control-Allow-Credentials: true
disabled Desativa a corsPolicy sem a remover. Os pedidos OPTIONS pré-voo são enviados através de proxy para a origem. N/A

Exemplo de corsPolicy

O exemplo de configuração seguinte mostra uma configuração básica de corsPolicy:

routeRules:
- priority: 1
  matchRules:
  - prefixMatch: /stream/
  routeAction:
    cdnPolicy:
      defaultTtl: 3600s
    corsPolicy:
      allowOrigins:
      - "https://stream.example.com"
      - "https://stream-staging.example.com"
      maxAge: 86400s # some browsers might only honor up to 7200s or less
      allowMethods:
      - "GET"
      - "HEAD"
      - "OPTIONS"
      allowHeaders:
      - "Content-Type"
      - "If-Modified-Since"
      - "Range"
      - "User-Agent"
      exposeHeaders:
      - "Content-Type"
      - "Content-Length"
      - "Date"

Resolva problemas de encaminhamento

Se alguns pedidos não obtiverem resultados correspondentes ou devolverem erros, verifique o seguinte:

  • Um trajeto tem de ter um matchRule com exatamente um dos seguintes elementos definidos: prefixMatch, fullPathMatch ou pathTemplateMatch. A API devolve um erro se não incluir um desses campos.
  • Certifique-se de que o priority de cada trajeto está definido corretamente: os trajetos mais específicos (mais longos) devem ter uma prioridade mais elevada do que as correspondências de trajetos mais curtas e amplas.
  • Por predefinição, apenas são suportados pedidos GET, HEAD e OPTIONS. Para configurar o suporte para outros métodos, consulte o artigo Métodos de encaminhamento. Os métodos que não estão ativados para uma determinada rota são rejeitados com um erro HTTP 405 (Method Not Allowed).
  • Os pedidos HTTP GET com um corpo ou qualquer pedido com trailers são rejeitados com um erro HTTP 400, porque os corpos dos pedidos não são permitidos em pedidos GET.
  • A correspondência de parâmetros de consulta e cabeçalhos é "E" lógico. O pedido tem de corresponder a todas as chaves de parâmetros de consulta ou cabeçalhos (e valores, se especificados) para corresponder à rota fornecida.

O que se segue?