Código de função de escrita (modelo de programação do CloudFront Functions)

Com o CloudFront Functions no Amazon CloudFront, você pode escrever funções leves em JavaScript para personalizações de CDN de alta escala e sensíveis à latência. Seu código de função pode manipular as solicitações e respostas que fluem pelo CloudFront, executar autenticação e autorização básicas, gerar respostas HTTP na borda e muito mais.

Os tópicos a seguir podem ajudá-lo a escrever código de função para o CloudFront Functions.

Tópicos

• Selecione o propósito da sua função
• Estrutura de eventos
• Recursos de tempo de execução JavaScript
• Código de exemplo

Selecione o propósito da sua função

Antes de escrever seu código de função, determine o propósito da sua função. A maioria das funções no CloudFront Functions tem uma das seguintes finalidades. Para obter mais informações, consulte o tópico que corresponde ao propósito da sua função.

Independentemente do propósito da sua função, o handler é o ponto de entrada para qualquer função. É preciso um único argumento chamado event, que é passado para a função pelo CloudFront. O event é um objeto JSON que contém uma representação da solicitação HTTP (e a resposta, se sua função modificar a resposta HTTP). Para obter mais informações sobre a estrutura do código-fonte do objeto event, consulte Estrutura de eventos do CloudFront Functions.

Modificar a solicitação HTTP

Sua função pode modificar a solicitação HTTP que o CloudFront recebe do visualizador (cliente) e retornar a solicitação modificada ao CloudFront para processamento contínuo. Por exemplo, seu código de função pode normalizar a chave de cache ou modificar cabeçalhos de solicitação.

Quando você criar uma função que modifica a solicitação HTTP, certifique-se de selecionar o tipo de evento viewer request (solicitação do visualizador). Isso significa que a função é executada sempre que o CloudFront recebe uma solicitação de um visualizador, antes de verificar se o objeto solicitado está no cache do CloudFront.

O pseudocódigo a seguir mostra a estrutura de uma função que modifica a solicitação HTTP.

function handler(event) {
    var request = event.request;

    // Modify the request object here.

    return request;
}

A função retorna o objeto request modificado para o CloudFront. O CloudFront continua processando a solicitação retornada verificando o cache do CloudFront quanto a uma ocorrência de cache e enviando a solicitação para a origem, se necessário.

Para obter mais informações sobre a estrutura dos objetos event e request, consulteEstrutura de eventos.

Gerar uma resposta HTTP na borda

Sua função pode gerar uma resposta HTTP na borda e retorná-la diretamente ao visualizador (cliente) sem verificar se há uma resposta em cache ou qualquer processamento adicional pelo CloudFront. Por exemplo, seu código de função pode redirecionar a solicitação para uma nova URL ou verificar se há autorização e retornar uma resposta 401 ou 403 a solicitações não autorizadas.

Quando você criar uma função que gera uma resposta HTTP, certifique-se de selecionar o tipo de evento viewer request (solicitação do visualizador). Isso significa que a função é executada sempre que o CloudFront recebe uma solicitação de um visualizador, antes que o CloudFront faça qualquer processamento adicional da solicitação.

O pseudocódigo a seguir mostra a estrutura de uma função que gera uma resposta HTTP.

function handler(event) {
    var request = event.request;

    var response = ...; // Create the response object here,
                        // using the request properties if needed.

    return response;
}

A função retorna um objeto response ao CloudFront, que o CloudFront retorna imediatamente ao visualizador sem verificar o cache do CloudFront ou enviar uma solicitação para a origem.

Para obter mais informações sobre a estrutura dos objetos event, request e response, consulte Estrutura de eventos.

nota

Quando você gera uma resposta HTTP com o CloudFront Functions, não é possível incluir um corpo de resposta. Se você precisar incluir um corpo de resposta com sua resposta HTTP gerada, use o Lambda@Edge.

Modificar a resposta HTTP

Sua função pode modificar a resposta HTTP antes que o CloudFront a envie para o visualizador (cliente), independentemente de a resposta vir do cache do CloudFront ou da origem. Por exemplo, seu código de função pode adicionar ou modificar cabeçalhos de resposta.

Ao criar uma função que modifica a resposta HTTP, certifique-se de selecionar o tipo de evento de viewer response (resposta do visualizador). Isso significa que a função é executada antes que o CloudFront retorne uma resposta ao visualizador, independentemente de a resposta vir do cache do CloudFront ou da origem.

O pseudocódigo a seguir mostra a estrutura de uma função que modifica a resposta HTTP.

function handler(event) {
    var request = event.request;
    var response = event.response;

    // Modify the response object here,
    // using the request properties if needed.

    return response;
}

A função retorna o objeto response modificado ao CloudFront, que o CloudFront retorna imediatamente ao visualizador.

Para obter mais informações sobre a estrutura dos objetos event e response, consulteEstrutura de eventos.

nota

Quando você modifica uma resposta HTTP com o CloudFront Functions, não é possível alterar ou modificar o corpo da resposta. Se você precisar alterar o corpo da resposta, use o Lambda@Edge. Com o Lambda@Edge, você pode substituir todo o corpo de resposta por um novo ou remover o corpo da resposta. No entanto, você não pode modificar propriedades individuais dentro do corpo da resposta.

Para obter mais informações sobre como escrever código de função para o CloudFront Functions, consulte Estrutura de eventos, Recursos de tempo de execução JavaScript e Código de exemplo.