Configurar rotas de serviço

O Media CDN oferece recursos avançados de roteamento HTTP que permitem associar o tráfego a origens e configurações de borda específicas em um nível detalhado.

Configurar uma regra de roteamento

Configure uma regra de roteamento para um serviço do Media CDN.

Console

  1. No console do Google Cloud, acesse a página Media CDN.

    Acesse Media CDN

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

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

  4. Para navegar até a seção Roteamento, clique em Próxima.

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

    1. Em Hosts, especifique pelo menos um host para correspondência.

    2. Em Descrição, forneça uma breve descrição da regra do organizador.

    Para editar uma regra de host, clique na seta para abrir.

  6. Especifique pelo menos uma regra de rota. Clique em Adicionar regra de rota.

    Como alternativa, para editar uma regra de rota, clique em Editar na respectiva linha.

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

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

  9. Na seçã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. Em Tipo de correspondência, selecione qualquer opção de correspondência de caminho.

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

      Se necessário, selecione Ativar a diferenciação de maiúsculas e minúsculas para o valor do caminho.

    3. Opcional: selecione Correspondência de cabeçalhos e Correspondência de parâmetros de consulta. 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 Correspondência em cabeçalhos e parâmetros de consulta.

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

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

    • Buscar em uma origem: para direcionar solicitações a uma origem específica, selecione essa opção e escolha uma origem.

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

      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 seção Ação do cabeçalho, clique em Adicionar um item.

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

    2. Na seção Rota de ação, clique em Adicionar um item.

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

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

    Em seguida, selecione os métodos HTTP que você quer usar como proxy para a origem.

  13. Para salvar a regra de roteamento, clique em Salvar.

  14. Para salvar as alterações no serviço, clique em Atualizar serviço.

gcloud e YAML

  1. Exporte a configuração do Media CDN para um arquivo YAML. Use o comando gcloud edge-cache services export.

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

    Substitua:

    • SERVICE_NAME: o nome do serviço;
    • FILENAME : o nome do arquivo YAML

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

  3. Para atualizar o serviço, importe a configuração do Media CDN do arquivo YAML. Use o comando gcloud edge-cache services import.

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

Solicitações de correspondência

Uma configuração do Media CDN contém um conjunto de rotas definidas na seção Roteamento de um recurso EdgeCacheService. Essas rotas correspondem a solicitações com base em (pelo menos) um host. Para mais detalhes sobre como o tráfego é direcionado a uma origem, consulte HostRule e PathMatcher. Cada rota pode definir a própria configuração de CDN, reescritas, redirecionamentos, políticas CORS, cabeçalhos HTTP personalizados e mapeamento de origem. As rotas podem compartilhar origens.

Por exemplo, é possível encaminhar solicitações de manifestos para uma origem específica e definir um TTL de cache de curta duração e uma política de armazenamento em cache negativo. As solicitações de segmentos podem ser divididas em outra origem usando cabeçalhos e parâmetros de consulta para separar tipos de manifesto ou usuários específicos.

O exemplo a seguir mostra como rotear solicitações que correspondem a um cabeçalho, parâmetro de consulta e prefixo de caminho específico para o host 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 caminho

O Media CDN oferece suporte à correspondência de caminhos completos (exatos), de prefixo e de caractere curinga. A correspondência de caminho pode ser combinada com a correspondência baseada em host, cabeçalho e parâmetro de consulta para criar regras de roteamento de solicitações detalhadas.

Confira a seguir três maneiras de fazer a correspondência em um caminho de URL.

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

Uma rota com uma regra de correspondência de fullPathMatch: "/stream/" corresponde a /stream/, mas não a /stream ou /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 são correspondentes.

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 oferece suporte a operadores de curinga, permitindo que você corresponda a padrões de URL e segmentos de caminho complexos, além de capturar variáveis nomeadas para reescrever URLs.

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

Tanto /content/en-GB/13/51491/manifest_193193.m3u8 quanto /p/abc/1234/manifest_1080p5000.m3u8 correspondem a esse padrão.

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

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

Por exemplo, para corresponder a todas as solicitações que começam com /stream/, crie uma regra de roteamento semelhante a esta:

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 o caractere de barra invertida na regra de correspondência:

  • Uma solicitação para media.example.com/stream/id/1234/hls/manifest.m3u8 corresponde a essa rota.
  • Uma solicitação para media.example.com/stream-eu/id/4567/hls/manifest.m3u8 não corresponde a essa rota.

No segundo caso, o Media CDN retorna um erro HTTP 404, a menos que haja outra rota ou uma rota de captura configurada.

Para saber como a precedência funciona para rotas com prefixos semelhantes, consulte a seção Prioridade e ordenação de rotas.

Correspondência de padrão (caractere curinga)

Com a correspondência de padrão, é possível corresponder várias partes de um URL, incluindo URLs parciais e sufixos (extensões de arquivo), usando uma sintaxe de caracteres curinga.

Também é possível associar um ou mais segmentos de caminho a variáveis nomeadas em um campo pathTemplateMatch e, em seguida, consultar essas variáveis ao reescrever o URL em um campo pathTemplateRewrite. Isso permite reordenar e remover segmentos de URL antes que a solicitação seja enviada à origem.

O exemplo a seguir mostra como fazer a correspondência em 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 com suporte inclui o seguinte.

Operador Corresponde a Exemplo
* Corresponde a um único segmento de caminho, até o próximo separador de caminho: / /videos/*/*/*.m4s corresponde /videos/123414/hls/1080p5000_00001.m4s.
** Corresponde a zero ou mais segmentos de caminho. Se presente, precisa ser o último operador. /**.mpd corresponde /content/123/india/dash/55/manifest.mpd.
{name} or {name=*}

Uma variável nomeada que corresponde a um só segmento de caminho.

Corresponde a um único segmento de caminho, até o próximo separador de caminho: /.

/content/{format}/{lang}/{id}/{file}.vtt corresponde a /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 nomeada que corresponde a mais de um segmento de caminho. O segmento de caminho que corresponde a videos/* é capturado como a variável nomeada. /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 nomeada que corresponde a zero ou mais segmentos de caminho.

Se presente, precisa ser o último operador.

/**.m3u8 ou /{path=**}.m3u8 corresponde a todos os segmentos de caminho até a 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.

Observações:

  • Se você não estiver reescrevendo um URL, use os operadores * e ** mais simples.
  • Ao usar variáveis para capturar segmentos de caminho, as partes do URL que não são capturadas por uma variável não podem ser referenciadas em uma pathTemplateRewrite subsequente. Para conferir um exemplo, consulte a seção captura de variáveis de caminho.
  • Não é possível fazer referência a variáveis em uma pathTemplateRewrite subsequente que não existe na pathTemplateMatch no mesmo trajeto.
  • As variáveis diferenciam maiúsculas de minúsculas, com {FORMAT}, {forMAT} e {format} representando diferentes variáveis e valores.
  • É possível especificar até 10 operadores (caracteres curinga ou variáveis) em uma correspondência. Os campos pathTemplateMatch e pathTemplateRewrite não podem exceder 255 caracteres.

Exemplo: correspondência em uma extensão de arquivo

O exemplo a seguir mostra um caso de uso comum para operadores curinga: correspondência de todos os segmentos de caminho até um sufixo.

Nesse caso, faça o seguinte:

  • Extraia manifestos de vídeo (playlists) que terminam em .m3u8 e .mpd da origem do manifesto, aplicando um TTL curto (5 segundos) a essas respostas porque elas mudam regularmente.
  • Extrair trechos de vídeo que terminam em .ts e .m4s da origem do segmento e aplicar um TTL mais longo (um dia) a essas respostas.

Essa abordagem é usada com frequência ao usar serviços de SSAI (Injeção de anúncios do lado do servidor) ou DAI (Inserção de anúncios dinâmicos) e para vídeos ao vivo em que o manifesto é atualizado a cada poucos segundos.

A configuração a seguir demonstra como configurar o roteamento do Media CDN para oferecer suporte a isso:

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: capturar variáveis de caminho

O exemplo a seguir mostra como usar variáveis nomeadas para descrever um ou mais segmentos de caminho.

Essas variáveis podem ser usadas em um pathTemplateRewrite para regravar o caminho antes de a solicitação ser enviada à origem ou para fazer com que um pathTemplateMatch complexo se autodescrever.

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}"

Especificamente:

  • Cada variável {name} captura um único segmento de caminho. Um segmento de caminho é o conjunto de todos os caracteres entre um par de / ("barras verticais") em um caminho de URL.
  • Uma variável de {name=**} captura todos os segmentos de caminho restantes. Nesse caso, ela corresponde a segments/00001.ts e master.m3u8.
  • Na pathTemplateRewrite na mesma rota, você se refere a algumas das variáveis capturadas no pathTemplateMatch. Você exclui explicitamente as variáveis {country} e {lang} porque elas não correspondem à estrutura de diretórios na origem.

Neste exemplo, o seguinte ocorre:

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

Para saber mais sobre como a correspondência de curinga interage com a substituição de URL, consulte a seção substituições.

Correspondência de host

Cada serviço pode corresponder a vários nomes de host, com cada conjunto de nomes de host contendo o próprio grupo de rotas (conhecidos como corresponder de caminho). No caso mais comum, todos os nomes de host de um mapa de serviço são mapeados para um único conjunto de rotas compartilhadas com uma única lista de hosts e uma única correspondência de caminho.

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 hosts que não correspondem recebem uma página 404 HTTP padrão. Para aceitar qualquer host, inclua o caractere curinga * como uma entrada hostRules[].hosts[].

Também é possível definir grupos de trajetos, por exemplo, agrupar por país ou ao vivo em vez de sob demanda. Como cada serviço tem uma política de segurança única, geralmente recomendamos ter um serviço para cada mercado (geografia) ou carga de trabalho.

Observações:

  • Os cabeçalhos de host (ou :authority HTTP/2) que contêm uma porta são implicitamente correspondidos a um host configurado. Não é necessário especificar explicitamente os portas.
  • Se a solicitação for por HTTP, uma entrada hostRules[].hosts[] de *.vod.example.com vai corresponder a us.vod.example.com e us.vod.example.com:80.
  • Se a solicitação for feita por HTTPS (TLS), uma entrada hostRules[].hosts[] de *.vod.example.com vai corresponder a us.vod.example.com:443.

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

Correspondência em cabeçalhos e parâmetros de consulta

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

A correspondência de cabeçalho e parâmetro de consulta é "AND" lógico: a solicitação precisa corresponder a todos os parâmetros de consulta e chaves de cabeçalho (e valores, se especificados) para corresponder à rota especificada.

Por exemplo, se você quiser encaminhar solicitações com um nome de campo de cabeçalho específico e um valor de cabeçalho para uma origem chamada 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, as solicitações com /videos/ no início do URL e o cabeçalho x-device-name: roku correspondem a essa rota. As solicitações que não têm esse nome de cabeçalho ou têm um valor diferente não correspondem a essa rota.

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

Da mesma forma, para corresponder aos parâmetros de consulta, especifique um ou mais queryParameterMatches da seguinte maneira:

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, uma solicitação do cliente de https://cdn.example.com/videos/1234/abcd/xyz.m3u8?playback_type=live&geo=eu corresponde a essa rota.

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

Definir uma rota "pega-tudo" (padrão)

Por padrão, a Media CDN retorna um erro HTTP 404 (Not Found) se uma solicitação não corresponder a nenhuma rota configurada.

Para configurar uma rota catch-all para um determinado pathMatcher (coleção de rotas), faça o seguinte:

  • Crie um routeRule com a prioridade mais baixa (número mais alto), 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 solicitação).
  • Configure um origin ou urlRedirect na rota.

Por exemplo, para configurar uma rota "pega-tudo" que direcione todas as solicitações não correspondentes para uma origem padrão chamada my-origin, crie uma nova rota com priority: 999 e um matchRules[].prefixMatch de / da seguinte maneira:

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

Você pode reescrever o URL antes da busca da origem ou redirecionar para uma página padrão (como a página de destino) em vez de enviar a solicitação "como está" para a origem.

Prioridade e ordem de rotas

Cada rota em uma matriz de routeRules[] precisa ter um priority associado a ela.

As rotas mais específicas precisam ter uma prioridade maior (número menor). Uma rota que corresponde a um prefixo de /stream/ com prioridade 1 impede que uma rota mais específica de /stream/live/eu/ com prioridade 5 corresponda a qualquer solicitação.

  • A rota de maior prioridade é "1", e a de menor prioridade é "999".
  • Não é possível configurar duas ou mais regras de rota com a mesma prioridade. A prioridade de cada regra precisa ser definida como um número entre 1 e 999, inclusive.
  • A definição de uma rota catch-all permite enviar todas as solicitações que não correspondem a uma origem padrão ou redirecioná-las para uma página de destino ou um endpoint.

No exemplo abaixo, a rota /live/us/ nunca será correspondida porque a rota /live/ tem prioridade mais alta:

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 isso, coloque a rota mais específica (mais longa) em uma prioridade mais alta:

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: /

Isso permite que a rota mais específica corresponda às solicitações corretamente. Uma solicitação prefixada com /live/eu/ ainda cairia na rota /live/ com prioridade 2.

Filtragem de método

Por padrão, o Media CDN faz o proxy apenas dos métodos GET, HEAD e OPTIONS para a origem e filtra os métodos que podem modificá-la.

É possível substituir esse comportamento padrão para uma regra de rota específica especificando os métodos que você quer que sejam encapsulados na origem. Além de GET, HEAD e OPTIONS, o Media CDN oferece suporte a PUT, POST, DELETE e PATCH.

Para configurar o suporte a um conjunto de métodos para uma regra de rota, especifique uma seçã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 de caminho

A normalização de caminho descreve como o Media CDN combina várias representações de um URL em uma única representação canônica em cenários específicos.

A normalização de caminho pode melhorar diretamente as taxas de ocorrência em cache, reduzindo o número de URLs de solicitação que representam o mesmo conteúdo e mitigando erros de origem para origens que esperam caminhos normalizados.

As solicitações recebidas são normalizadas da seguinte maneira:

  • Várias barras invertidas consecutivas são mescladas em uma única barra. Por exemplo, um caminho de URL de /videos///12345/manifest.mpd é normalizado para /videos/12345/manifest.mpd.
  • Os segmentos do caminho são normalizados de acordo com a RFC 3986, seção 6.2.2.3. Por exemplo, o caminho /a/b/c/./../../g é normalizado para /a/g com base no algoritmo "remove dot segments" definido no RFC 3986. Essa normalização acontece antes da verificação do cache ou do encaminhamento da solicitação para a origem.
  • 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.

Os URLs continuam diferenciando maiúsculas de minúsculas e não são normalizados. Muitos URLs contêm codificações base64 que diferenciam maiúsculas de minúsculas, incluindo URLs com tokens de solicitação assinada.

Regravações e redirecionamentos

As seções a seguir fornecem exemplos sobre como reescrever solicitações e configurar redirecionamentos.

Reescrever URLs de solicitação

A Media CDN é compatível com substituições de host e caminho. As substituições mudam o URL enviado para a origem e permitem modificar hosts e caminhos conforme necessário. As substituições de host e caminho estão no nível da rota, permitindo que você defina quais solicitações específicas são reescritas com base em qualquer correspondente, incluindo caminho, parâmetro de consulta e cabeçalho de solicitação.

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

Confira a seguir três maneiras de reescrever uma solicitação:

Campo Descrição
urlRewrite.pathPrefixRewrite

Reescreva o caminho, removendo o prefixo especificado no prefixMatch que correspondeu à solicitação.

Apenas um de pathPrefixRewrite ou pathTemplateRewrite pode ser especificado em uma única regra de rota.

urlRewrite.pathTemplateRewrite

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

Apenas um de pathPrefixRewrite ou pathTemplateRewrite pode ser especificado em uma única regra de rota.

urlRewrite.hostRewrite Reescreve o host antes que a solicitação seja enviada ao servidor de origem.

Observações:

  • Os URLs reescritos não mudam a chave de cache. A chave de cache é baseada no URL da solicitação enviado pelo cliente.
  • A reescrita ocorre após a correspondência de rotas e a validação de solicitações assinadas. As rotas não são refeitas com outra regra de correspondência.

Exemplo: remover um prefixo de caminho

Por exemplo, para reescrever um URL de solicitação de cliente de /vod/videos/hls/1234/abc.ts para /videos/hls/1234/abc.ts (removendo /vod do caminho), use o recurso 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 todo o prefixo de caminho correspondente em o matchRules[].prefixMatch pelo valor de pathPrefixRewrite.

Para reescrever um nome de host (por exemplo, reescrevendo cdn.example.com para my-bucket.s3.us-west-2.amazonaws.com), configure 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"

Nesse caso, o URL da solicitação de origem mudaria de cdn.example.com/videos/* para my-bucket.s3.us-west-2.amazonaws.com/videos/*. Também é possível combinar as reescritas de host e de caminho em uma única rota.

Exemplo: usar variáveis para substituir URLs

Para usar pathTemplateMatch e pathTemplateRewrite para reescrever partes de um URL de solicitação de entrada, consulte a seção captura de variáveis.

Redirecionar solicitações

A CDN para mídias oferece suporte a três tipos de redirecionamentos:

  • Redirecionamentos de host, que redirecionam apenas o host (domínio), mantendo o caminho e os parâmetros de consulta inalterados.
  • Redirecionamentos de caminho, que substituem o caminho por completo.
  • Redirecionamentos de prefixo de caminho, que substituem apenas o prefixo correspondente.

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

A configuração a seguir é um exemplo de redirecionamento baseado em prefixo, em que você redireciona os usuários 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

Esse exemplo também muda o redirecionamento para um temporário, o que impede que clientes (como navegadores) o armazenem em cache. Isso pode ser útil se você pretende mudar o endereço em breve.

Os valores redirectResponseCode compatíveis são mostrados na tabela a seguir.

Redirecionar o código de resposta Código de status HTTP
MOVED_PERMANENTLY_DEFAULT HTTP 301 (movido permanentemente)
FOUND HTTP 302 (encontrado)
SEE_OTHER HTTP 303 (ver outros)
TEMPORARY_REDIRECT HTTP 307 (redirecionamento temporário)
PERMANENT_REDIRECT HTTP 308 (redirecionamento permanente)

Observações:

  • Uma rota pode direcionar o tráfego para uma origem ou retornar um redirecionamento para o cliente. Não é possível definir os campos origin e urlRedirect ao mesmo tempo.
  • As rotas que redirecionam para HTTPS exigem que pelo menos um certificado SSL seja anexado ao serviço.

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

Redirecionar todas as solicitações para HTTPS

Para redirecionar todas as solicitações para HTTPS (em vez de HTTP), configure cada um dos seus serviços para redirecionar automaticamente todas as solicitações de cliente para HTTPS. Os clientes que se conectam por HTTP recebem uma resposta HTTP 301 (Permanent Redirect) com o cabeçalho Location definido para o mesmo URL 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 retorna uma descrição do serviço, com requireTls definido como true.

  name: MY_SERVICE
  requireTls: true

Também é possível definir o cabeçalho Strict-Transport-Security como um cabeçalho de resposta para direcionar os clientes a se conectarem sempre por HTTPS.

Usar back-ends de armazenamento de terceiros

O Media CDN oferece suporte à conexão com endpoints HTTP acessíveis publicamente fora do Google Cloud, incluindo buckets de armazenamento do AWS S3, Azure Blob Storage e outros provedores de armazenamento. Isso pode ser útil se você tiver uma arquitetura multicloud ou ainda não tiver migrado dados para o Cloud Storage usando o Serviço de transferência do Cloud Storage.

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

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

Se você não estiver usando um nome de bucket que corresponda aos nomes de host configurados para seus recursos EdgeCacheService, também será necessário configurar uma substituição de host para rotas associadas a essa origem. Caso contrário, o cabeçalho Host definido pela solicitação do cliente é usado ao buscar da origem.

Por exemplo, para mapear todas as solicitações com um prefixo de caminho de /legacy/ para seu bucket externo, configure um hostRewrite e um pathPrefixRewrite para remover esse prefixo da solicitação 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 de host é definido nas solicitações de origem, consulte a documentação de cabeçalhos de solicitação de origem.

Compartilhamento de recursos entre origens (CORS, na sigla em inglês)

O Compartilhamento de recursos entre origens (CORS, na sigla em inglês) é uma abordagem centrada no navegador para fazer solicitações entre origens com segurança. As políticas CORS permitem que você defina automaticamente cabeçalhos CORS, como Access-Control-Allow-Origins, com base em uma política por rota.

Configurar o CORS

A CDN de mídia permite definir uma política CORS em uma rota para um EdgeCacheService.

Uma política CORS define essas regras com um conjunto comum de cabeçalhos HTTP. É possível definir cabeçalhos CORS comuns em respostas, como Access-Control-Allow-Origin, Access-Control-Max-Age e Access-Control-Allow-Headers. Esses cabeçalhos permitem fazer chamadas entre origens para seus serviços do Media CDN que podem ser hospedados em um domínio (origem) diferente do front-end do seu site e podem impedir solicitações entre origens que você não permite explicitamente.

Por exemplo, player.example.com e api.example.com são origens diferentes (no sentido do navegador), e talvez você queira que seu aplicativo de front-end faça solicitações para api.example.com para buscar a próxima playlist ou atualizar uma lista de conteúdo relacionado. Da mesma forma, o player.example.com pode precisar entrar em contato com o cdn.example.com para buscar playlists e trechos de vídeo: o cdn.example.com precisa indicar que isso está OK e que o player.example.com é um allowed origin, bem como qualquer outra regra (cabeçalhos permitidos, se os cookies podem ser incluídos).

Para outro exemplo, se você quiser permitir stream.example.com como uma origem e um cabeçalho X-Client-ID em solicitações CORS, configure um corsPolicy em uma rota, conforme mostrado abaixo:

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

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

Se você definir um valor corsPolicy e também definir um cabeçalho de resposta personalizado usando os campos responseHeadersToAdd em uma rota com o mesmo nome, o cabeçalho de resposta personalizado terá precedência e será usado em vez do valor corsPolicy.

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

O {origin_request_header} especial é preenchido com o cabeçalho HTTP Origin na solicitação do cliente. Isso pode ser definido como um valor de cabeçalho de resposta personalizado em uma 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 a seguir descreve os campos que uma política CORS contém.

Campo Descrição Exemplo
allowOrigins

Define o cabeçalho de resposta Access-Control-Allow-Origins, que especifica quais origens podem fazer solicitações entre origens em um ambiente de navegador.

Por exemplo, se o conteúdo do vídeo for veiculado em https://video.example.com, mas o portal voltado ao usuário for veiculado em https://stream.example.com, adicione https://stream.example.com como uma origem permitida.

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

Define o cabeçalho de resposta Access-Control-Max-Age, que especifica por quanto tempo, em segundos, um cliente do navegador precisa armazenar em cache a resposta a uma solicitação de simulação do CORS.

Alguns navegadores limitam esse valor a duas horas ou menos, mesmo que o valor máximo (86400s) seja especificado.

 Access-Control-Max-Age: 7200
allowMethods

Define o cabeçalho de resposta Access-Control-Allow-Methods, que especifica quais métodos HTTP têm permissão para acessar o recurso.

Por padrão, o Media CDN oferece suporte apenas aos métodos GET, HEAD e OPTIONS. Para configurar o suporte a outros métodos, consulte Métodos de rota.

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

Define o cabeçalho Access-Control-Allow-Headers, que determina quais cabeçalhos podem ser enviados em uma solicitação CORS.

Isso geralmente é necessário para players de vídeo, que precisam acessar alguns cabeçalhos de resposta para conteúdo de vídeo ao fazer solicitações entre origens.

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

Define o cabeçalho de resposta Access-Control-Expose-Headers, que determina quais cabeçalhos podem ser acessados pelo JavaScript do lado do cliente.

Isso geralmente é necessário para players de vídeo, que podem precisar acessar cabeçalhos de resposta específicos para conteúdo de vídeo ao solicitar conteúdo entre origens.

 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 de solicitações com credenciais incluídas.

Esse cabeçalho é omitido quando definido como falso.

 Access-Control-Allow-Credentials: true
disabled Desativa o corsPolicy sem removê-lo. As solicitações OPTIONS de pré-voo são encaminhadas para a origem. N/A

Exemplo de corsPolicy

O exemplo de configuração a seguir 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"

Resolver problemas de roteamento

Se algumas solicitações não retornarem resultados correspondentes ou retornarem erros, verifique o seguinte:

  • Uma rota precisa ter um matchRule com exatamente um dos valores prefixMatch, fullPathMatch ou pathTemplateMatch definidos. A API vai retornar um erro se você não incluir um desses campos.
  • Verifique se o priority de cada rota está definido corretamente: as rotas mais específicas (mais longas) precisam ter uma prioridade maior do que as correspondências de rotas mais curtas e amplas.
  • Por padrão, apenas as solicitações GET, HEAD e OPTIONS são compatíveis. Para configurar o suporte a outros métodos, consulte Métodos de rota. Os métodos que não estão ativados para uma rota específica são rejeitados com um erro HTTP 405 (Method Not Allowed).
  • As solicitações HTTP GET com um corpo ou qualquer solicitação com trailers são rejeitadas com um erro HTTP 400, porque corpos de solicitação não são permitidos em solicitações GET.
  • A correspondência de parâmetro de consulta e cabeçalho é "AND" lógico: a solicitação precisa corresponder a todas as chaves de parâmetro de consulta ou cabeçalho (e valores, se especificados) para corresponder à rota especificada.

A seguir