Associar funções com distribuições - Amazon CloudFront

Associar funções com distribuições

Para usar uma função no CloudFront Functions com uma distribuição do CloudFront, você associa a função a um ou mais comportamentos de cache na distribuição. Você pode associar uma função a vários comportamentos de cache em várias distribuições. Antes de associar uma função, você deve publicá-la na fase LIVE.

Quando você associa uma função a um comportamento de cache, você deve selecionar um tipo de evento. O tipo de evento determina quando o CloudFront Functions executa a função. Existem dois tipos de eventos para selecionar:

Para obter mais informações sobre os tipos de evento, consulte Eventos do CloudFront que podem acionar uma função do Lambda@Edge. Você não pode usar tipos de evento voltados para a origem (solicitação de origem e resposta de origem) com o CloudFront Functions.

  • Solicitação do visualizador: a função é executada quando o CloudFront recebe uma solicitação de um visualizador.

  • Resposta do visualizador: a função é executada antes que o CloudFront retorne uma resposta ao visualizador.

Você pode associar uma função a uma distribuição no console do CloudFront ou à AWS CLI.

Você pode usar o console do CloudFront para associar uma função a um comportamento de cache existente em uma distribuição existente do CloudFront. Para obter informações sobre como criar uma distribuição, consulte Criar uma distribuição.

Para associar uma função a um comportamento de cache existente (console)

  1. Para associar uma função a uma distribuição, abra a página Functions (Funções) no console do CloudFront em https://console.aws.amazon.com/cloudfront/v3/home#/functions e, em seguida, selecione a função que deseja associar.

  2. Na página de função, selecione a guia Associate (Associar). Então, faça o seguinte:

    1. Para Distribution (Distribuição), selecione uma distribuição à qual associar a função.

    2. Para Event type (Tipo de evento), selecione quando deseja que essa função seja executada:

      • Para executar a função sempre que o CloudFront receber uma solicitação, selecione Viewer Request (Solicitação do visualizador).

      • Para executar a função sempre que o CloudFront retornar uma resposta, selecione Viewer Response (Resposta do visualizador).

    3. Para Cache behavior (Comportamento de cache), selecione um comportamento de cache para associar essa função (selecione * para o comportamento de cache padrão). A função é executada quando a solicitação (ou no caso de uma função de resposta do visualizador, a solicitação correspondente da resposta) corresponde a esse comportamento de cache.

    4. Escolha Add association. Em seguida, na janela pop-up Associate function to cache behavior (Associar função ao comportamento de cache), selecione Associate (Associar).

    
                                Guia Associate (Associar) de uma página de função no console do CloudFront.

Quando for bem-sucedido, você verá um banner na parte superior da página que diz Function name associated successfully ([Nome da função] associada com sucesso). Você também vê a distribuição associada na tabela Associated CloudFront distributions (Distribuições do CloudFront Associated). Aguarde alguns minutos para que a distribuição associada termine a implantação. Para verificar o status da distribuição, selecione a distribuição associada e escolha View distribution (Exibir distribuição).

O Status da distribuição muda para InProgress enquanto a distribuição é reimplantada. Assim que a nova configuração de distribuição atingir um local da borda do CloudFront, esse local da borda começará a usar a função associada. Quando a distribuição é totalmente implantada, o Status muda novamente para Deployed, o que indica que a função associada do CloudFront está ativa em todos os locais de borda do CloudFront no mundo todo. Normalmente, isso demora alguns minutos.

Você pode associar uma função a um comportamento de cache existente, a um novo comportamento de cache em uma distribuição existente ou a um novo comportamento de cache em uma nova distribuição. O procedimento a seguir mostra como associar uma função a um comportamento de cache existente. Você pode associar uma função a um novo comportamento de cache (em uma distribuição existente ou nova) usando um processo semelhante ao descrito aqui.

Para associar uma função a um comportamento de cache existente (AWS CLI)

nota

Os comandos de exemplo a seguir usam arquivos de entrada e saída que são formatados como uma cadeia YAML. Esse recurso só está disponível na versão 2 da AWS CLI. Para obter mais informações, consulte Configuração do formato da saída da AWS CLI no Guia do usuário da AWS Command Line Interface.

Se estiver usando a versão 1 da AWS CLI, você poderá seguir um processo semelhante usando JSON para os arquivos de entrada e saída.

  1. Use o comando a seguir para salvar a configuração de distribuição para a distribuição cujo comportamento de cache você deseja associar a uma função. Esse comando salva a configuração de distribuição em um arquivo chamado dist-config.yaml. Para usar esse comando, faça o seguinte:

    • Substitua DistributionID pelo ID da distribuição.

    • Execute o comando em uma linha. No exemplo, as quebras de linha são fornecidas para tornar o exemplo mais legível.

    aws cloudfront get-distribution-config \ --id DistributionID \ --output yaml > dist-config.yaml

    Quando o comando é bem-sucedido, a AWS CLI não retorna nenhuma saída.

  2. Abra o arquivo chamado dist-config.yaml que você acabou de criar. Edite o arquivo fazendo as seguintes alterações:

    1. Renomeie o campo ETag para IfMatch, mas não altere o valor do campo.

    2. No comportamento do cache, localize o objeto chamado FunctionAssociations. Atualize esse objeto para adicionar uma associação de função. A sintaxe YAML para uma associação de função se parece com o exemplo a seguir.

      • O exemplo a seguir mostra um tipo de evento de solicitação de visualizador (trigger). Para usar um tipo de evento de resposta do visualizador, substitua viewer-request por viewer-response.

      • Substitua arn:aws:cloudfront::111122223333:function/ExampleFunction pelo nome do recurso da Amazon (ARN) da função que você está associando a esse comportamento de cache. Para obter o ARN da função, você pode usar o comando aws cloudfront list-functions.

      FunctionAssociations: Items: - EventType: viewer-request FunctionARN: arn:aws:cloudfront::111122223333:function/ExampleFunction Quantity: 1

    Depois de fazer essas alterações, salve o arquivo.

  3. Use o comando a seguir para atualizar a distribuição, adicionando a associação de função. Para usar esse comando, faça o seguinte:

    • Substitua DistributionID pelo ID da distribuição.

    • Execute o comando em uma linha. No exemplo, as quebras de linha são fornecidas para tornar o exemplo mais legível.

    aws cloudfront update-distribution \ --id DistributionID \ --cli-input-yaml file://dist-config.yaml

    Quando o comando é bem-sucedido, você vê uma saída como a seguinte que descreve a distribuição que foi atualizada apenas com a associação de função. O exemplo de saída a seguir é truncado para legibilidade.

    Distribution: ARN: arn:aws:cloudfront::111122223333:distribution/EBEDLT3BGRBBW ... truncated ... DistributionConfig: ... truncated ... DefaultCacheBehavior: ... truncated ... FunctionAssociations: Items: - EventType: viewer-request FunctionARN: arn:aws:cloudfront::111122223333:function/ExampleFunction Quantity: 1 ... truncated ... DomainName: d111111abcdef8.cloudfront.net Id: EDFDVBD6EXAMPLE LastModifiedTime: '2021-04-19T22:39:09.158000+00:00' Status: InProgress ETag: E2VJGGQEG1JT8S

    Quando você atualiza uma distribuição, o Status da distribuição é alterado para InProgress enquanto a distribuição é reimplantada. Assim que a nova configuração de distribuição atingir um local da borda do CloudFront, esse local da borda começará a usar a função associada. Quando a distribuição é totalmente implantada, o Status muda novamente para Deployed, o que indica que a função associada do CloudFront está ativa em todos os locais de borda do CloudFront no mundo todo. Normalmente, isso demora alguns minutos.