Métodos auxiliares para modificação da origem - Amazon CloudFront
Escolher entre o CloudFront Functions e o Lambda@Edgemétodo updateRequestOrigin()Método selectRequestOriginById()Método createRequestOriginGroup()

Métodos auxiliares para modificação da origem

Esta seção se aplica se você atualizar ou alterar dinamicamente a origem usada na solicitação dentro do seu código do CloudFront Functions. Você pode atualizar a origem somente em solicitações do visualizador do CloudFront Functions. O CloudFront Functions tem um módulo que oferece métodos auxiliares para atualizar ou alterar dinamicamente a origem.

Para usar esse módulo, crie uma função do CloudFront usando o runtime 2.0 do JavaScript e inclua a seguinte declaração na primeira linha do código da função:

import cf from 'cloudfront';

Para obter mais informações, consulte Recursos de runtime 2.0 do JavaScript para CloudFront Functions.

nota

As páginas da API de teste e do console de teste não verificam se ocorreu uma modificação na origem. No entanto, o teste garante que o código da função seja executado sem erros.

Escolher entre o CloudFront Functions e o Lambda@Edge

Você pode atualizar suas origens usando o CloudFront Functions ou o Lambda@Edge.

Ao usar o CloudFront Functions para atualizar as origens, você usa o acionador de evento de solicitação do visualizador, o que significa que essa lógica será executada em todas as solicitações quando essa função for usada. Ao usar o Lambda@Edge, os recursos de atualização de origem estão no acionador de evento da solicitação para a origem, o que significa que essa lógica só é executada em caso de ausências no cache.

Sua escolha depende muito da workload e de qualquer uso existente do CloudFront Functions e do Lambda@Edge em suas distribuições. As considerações a seguir podem ajudar você a decidir se deve usar o CloudFront Functions ou o Lambda@Edge para atualizar suas origens.

O CloudFront Functions é mais útil nas seguintes situações:

  • Quando suas solicitações são dinâmicas (o que significa que não podem ser armazenadas em cache) e sempre vão para a origem. O CloudFront Functions oferece melhor desempenho e menor custo geral.

  • Quando você já tem uma função do CloudFront de solicitação do visualizador que será executada em todas as solicitações, é possível adicionar a lógica de atualização de origem à função existente.

Para usar o CloudFront Functions para atualizar as origens, consulte os métodos auxiliares nos tópicos a seguir.

O Lambda@Edge é mais útil nas seguintes situações:

  • Quando você tem conteúdo altamente armazenável em cache, o Lambda@Edge pode ser mais econômico porque é executado somente em caso de ausências no cache, enquanto o CloudFront Functions é executado em todas as solicitações.

  • Quando você já tem uma função do Lambda@Edge de solicitação para a origem, é possível adicionar a lógica de atualização de origem à função existente.

  • Quando sua lógica de atualização de origem exige a busca de dados de fontes de dados de terceiros, como o Amazon DynamoDB ou o Amazon S3.

Para ter mais informações sobre o Lambda@Edge, consulte Personalização na borda com o Lambda@Edge.

método updateRequestOrigin()

Use o método updateRequestOrigin() para atualizar as configurações da origem de uma solicitação. Você pode usar esse método para atualizar as propriedades da origem existente no caso de origens que já estejam definidas na sua distribuição ou para definir uma nova origem para a solicitação. Para isso, especifique as propriedades que você deseja alterar.

Importante

Qualquer configuração que você não especificar no updateRequestOrigin() herdará as mesmas configurações da configuração da origem existente.

A origem definida pelo método updateRequestOrigin() pode ser qualquer endpoint HTTP e não precisa ser uma origem existente na sua distribuição do CloudFront.

Observações

  • Se você estiver atualizando uma origem que faz parte de um grupo de origens, somente a origem primária desse grupo será atualizada. A origem secundária permanecerá inalterada. Qualquer código de resposta da origem modificada que corresponda aos critérios de failover acionará um failover para a origem secundária.

  • Se você estiver alterando o tipo de origem e o OAC estiver habilitado, verifique se o tipo de origem em originAccessControlConfig corresponde ao novo tipo de origem.

  • Não é possível usar o método updateRequestOrigin() para atualizar origens de VPC. A solicitação falhará.

Solicitação

updateRequestOrigin({origin properties})

A chave origin properties pode conter os seguintes valores:

domainName (opcional)

O nome de domínio da origem. Se isso não for fornecido, será usado o nome de domínio da origem atribuída.

Para origens personalizadas

Especifique um nome de domínio DNS, como www.example.com. O nome de domínio não pode incluir dois-pontos (:) e não pode ser um endereço IP. O nome de domínio pode ter até 253 caracteres.

Para origens do S3

Especifique o nome de domínio DNS do bucket do Amazon S3, como amzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com. O nome pode ter até 128 caracteres e deve ser todo em minúsculas.

originPath (opcional)

O caminho do diretório na origem em que a solicitação deve localizar o conteúdo. O caminho deve começar com uma barra (/), mas não deve terminar com uma. Por exemplo, não deve terminar com example-path/. Se isso não for fornecido, será usado o caminho de origem da origem atribuída.

Para origens personalizadas

O caminho deve ser codificado por URL e ter um tamanho máximo de 255 caracteres.

customHeaders (opcional)

Você pode incluir os cabeçalhos personalizados com a solicitação ao especificar o par de nome e valor do cabeçalho para cada cabeçalho personalizado. O formato é diferente do formato dos cabeçalhos de solicitação e resposta na estrutura do evento. Use os seguintes pares de chave/valor:

{"key1": "value1", "key2": "value2", ...}

Não é possível adicionar cabeçalhos não permitidos e não pode haver um cabeçalho com o mesmo nome em headers de solicitação de entrada. O nome do cabeçalho deve estar em letras minúsculas no código da função. Quando o CloudFront Functions converte o objeto de evento novamente em uma solicitação HTTP, a primeira letra de toda palavra em nomes de cabeçalho é grafada em maiúscula e as palavras são separadas por hífen.

Por exemplo, se o código da função adicionar um cabeçalho chamado example-header-name, o CloudFront o converterá em Example-Header-Name na solicitação HTTP. Para obter mais informações, consulte Cabeçalhos personalizados que o CloudFront não pode adicionar às solicitações da origem e Restrições das funções de borda.

Se isso não for fornecido, quaisquer cabeçalhos personalizados da origem atribuída serão usados.

connectionAttempts (opcional)

O número de vezes que o CloudFront tenta se conectar à origem. O mínimo é 1 e o máximo é 3. Se isso não for fornecido, serão usadas as tentativas de conexão da origem atribuída.

originShield (opcional)

Isso ativa ou atualiza o CloudFront Origin Shield. Usar o Origin Shield pode ajudar a reduzir a carga na sua origem. Para obter mais informações, consulte Usar o Amazon CloudFront Origin Shield. Se isso não for fornecido, serão usadas as configurações do Origin Shield da origem atribuída.

enabled (obrigatório)

Expressão booliana para habilitar ou desabilitar o Origin Shield. Aceita um valor true ou false.

region (obrigatório quando habilitado)

A Região da AWS para o Origin Shield. Especifique a região da Região da AWS que tem a latência mais baixa para sua origem. Use o código da região, não o nome da região. Por exemplo, especifique a região Leste dos EUA (Ohio) como us-east-2.

Ao habilitar o CloudFront Origin Shield, você deve especificar a Região da AWS para o Origin Shield. Para obter uma lista das Regiões da AWS disponíveis e ajuda para escolher a melhor região para sua origem, consulte Escolher a região da AWS para o Origin Shield.

originAccessControlConfig (opcional)

O identificador exclusivo de um controle de acesso de origem (OAC) para essa origem. Isso só é usado quando a origem é compatível com um OAC do CloudFront, como Amazon S3, URLs de funções do Lambda, MediaStore e MediaPackage V2. Se isso não for fornecido, serão usadas as configurações do OAC da origem atribuída.

Nesse caso, não é possível usar a identidade do acesso de origem (OAI) legada. Para obter mais informações, consulte Restringir o acesso a uma origem da AWS.

enabled (obrigatório)

Expressão booliana para habilitar ou desabilitar o OAC. Aceita um valor true ou false.

signingBehavior (obrigatório quando habilitado)

Especifica quais solicitações o CloudFront assina (adiciona informações de autenticação). Especifique always para o caso de uso mais comum. Para obter mais informações, consulte Configurações avançadas para controle de acesso à origem.

Esse campo pode ter um dos seguintes valores:

  • always: o CloudFront assina todas as solicitações de origem, substituindo o cabeçalho Authorization da solicitação do visualizador se houver.

  • never: o CloudFront não assina nenhuma solicitação para a origem. Esse valor desativa o controle de acesso de origem.

  • no-override: se a solicitação do visualizador não contiver o cabeçalho Authorization, o CloudFront assinará a solicitação para a origem. Se a solicitação do visualizador contiver o cabeçalho Authorization, o CloudFront não assinará a solicitação para a origem e, em vez disso, passará adiante o cabeçalho Authorization da solicitação do visualizador.

    Atenção

    Para transmitir o cabeçalho Authorization da solicitação do visualizador, você deve adicioná-lo a uma política de solicitação para a origem para todos os comportamentos de cache que usam origens associadas a esse controle de acesso de origem. Para obter mais informações, consulte Controlar as solicitações de origem com uma política.

signingProtocol (obrigatório quando habilitado)

O protocolo de assinatura do OAC, que determina como o CloudFront assina (autentica) as solicitações. O único valor válido é sigv4.

originType (obrigatório quando habilitado)

O tipo de origem desse OAC. Os valores válidos são s3, mediapackagev2, mediastore e lambda.

timeouts (opcional)

Tempos limite que você pode especificar para indicar por quanto tempo o CloudFront deve tentar esperar até que as origens respondam ou enviem dados. Se isso não for fornecido, serão usadas as configurações de tempo limite da origem atribuída.

readTimeout (opcional)

O tempo limite só se aplica a origens personalizadas, não a origens do Amazon S3. (As configurações de origem do S3 ignorarão essas configurações.) readTimeout aplica-se a estes dois valores:

  • O período (em segundos) que o CloudFront aguarda uma resposta após o encaminhamento de uma solicitação à origem.

  • O período (em segundos) que o CloudFront aguarda após o recebimento de um pacote de uma resposta da origem e antes do recebimento do próximo pacote.

O tempo limite mínimo é de 1 segundo e o máximo é de 60 segundos. Para obter mais informações, consulte Tempo limite de resposta (somente origens de VPC e personalizadas).

keepAliveTimeout (opcional)

O tempo limite só se aplica a origens personalizadas, não a origens do Amazon S3. (As configurações de origem do S3 ignorarão essas configurações.) keepAliveTimeout especifica por quanto tempo o CloudFront deve tentar manter a conexão com a origem depois de receber o último pacote da resposta. O tempo limite mínimo é de 1 segundo e o máximo é de 60 segundos. Para obter mais informações, consulte Tempo limite de keep alive (somente origens de VPC e personalizadas).

connectionTimeout (opcional)

O número de segundos que o CloudFront aguarda ao tentar estabelecer uma conexão com a origem. O tempo limite mínimo é de 1 segundo e o máximo é de 10 segundos. Para obter mais informações, consulte Tempo limite da conexão.

customOriginConfig (opcional)

Use customOriginConfig para especificar configurações de conexão para origens que não sejam um bucket do Amazon S3. Há uma exceção: você pode especificar essas configurações se o bucket do S3 estiver configurado com hospedagem de site estático. (Outros tipos de configuração do bucket do S3 ignorarão essas configurações.) Se customOriginConfig não for fornecido, serão usadas as configurações da origem atribuída.

port (obrigatório)

A porta HTTP que o CloudFront usa para se conectar à origem. Especifique a porta HTTP que a origem escuta.

protocol (obrigatório)

Especifica o protocolo (HTTP ou HTTPS) que o CloudFront usa para se conectar à origem. Os valores válidos são os seguintes:

  • http: o CloudFront sempre usa HTTP para se conectar à origem.

  • https: o CloudFront sempre usa HTTPS para se conectar à origem.

sslProtocols (obrigatório)

Uma lista que especifica o protocolo SSL/TLS mínimo que o CloudFront usa ao se conectar à sua origem por HTTPS. Os valores válidos são SSLv3, TLSv1, TLSv1.1 e TLSv1.2. Para obter mais informações, consulte Protocolo SSL de origem mínimo.

exemplo – Atualização para a origem da solicitação do Amazon S3

O exemplo a seguir altera a origem da solicitação do visualizador para um bucket do S3, habilita o OAC e redefine os cabeçalhos personalizados enviados à origem.

cf.updateRequestOrigin({
    "domainName" : "amzn-s3-demo-bucket-in-us-east-1.s3.us-east-1.amazonaws.com",
    "originAccessControlConfig": {
        "enabled": true,
        "signingBehavior": "always",
        "signingProtocol": "sigv4",
        "originType": "s3"
    },
    // Empty object resets any header configured on the assigned origin
    "customHeaders": {}
});
exemplo – Atualização para a origem da solicitação do Application Load Balancer

O exemplo a seguir altera a origem da solicitação do visualizador para uma origem do Application Load Balancer e define um cabeçalho personalizado e tempos limite.

cf.updateRequestOrigin({
    "domainName" : "example-1234567890.us-east-1.elb.amazonaws.com",
    "timeouts": {
        "readTimeout": 30,
        "connectionTimeout": 5
    },
    "customHeaders": {
        "x-stage": "production",
        "x-region": "us-east-1"
    }
});
exemplo – Atualização para a origem com o Origin Shield habilitado

No exemplo a seguir, a origem na distribuição tem o Origin Shield habilitado. O código da função atualiza somente o nome de domínio usado para a origem e omite todos os outros parâmetros opcionais. Nesse caso, o Origin Shield ainda será usado com o nome de domínio de origem modificado porque os parâmetros do Origin Shield não foram atualizados.

cf.updateRequestOrigin({
    "domainName" : "www.example.com"
});

Método selectRequestOriginById()

Use selectRequestOriginById() para atualizar uma origem existente selecionando uma origem diferente que já esteja configurada na sua distribuição. Esse método usa todas as mesmas configurações definidas pela origem atualizada.

Esse método só aceita origens que já estão definidas na mesma distribuição usada ao executar a função. As origens são referidas pelo ID de origem, que é o nome de origem que você definiu ao configurar a origem.

Se você tiver uma origem de VPC configurada em sua distribuição, poderá usar esse método para atualizá-la para sua origem de VPC. Para obter mais informações, consulte Restringe o acesso com origens de VPC..

Solicitação

selectRequestOriginById(origin_id)

No exemplo anterior, origin_id é uma string que aponta para o nome de uma origem na distribuição que está executando a função.

exemplo – Selecionar a origem da solicitação do Amazon S3

O exemplo a seguir seleciona a origem denominada amzn-s3-demo-bucket-in-us-east-1 na lista de origens associadas à distribuição e aplica as configurações da origem amzn-s3-demo-bucket-in-us-east-1 à solicitação.

cf.selectRequestOriginById("amzn-s3-demo-bucket-in-us-east-1");
exemplo – Selecionar a origem da solicitação do Application Load Balancer

O exemplo a seguir seleciona uma origem do Application Load Balancer denominada myALB-prod na lista de origens associadas à distribuição e aplica as configurações de myALB-prod à solicitação.

cf.selectRequestOriginById("myALB-prod");

Método createRequestOriginGroup()

Use createRequestOriginGroup() para definir duas origens a serem usadas como um grupo de origens para failover em cenários que exigem alta disponibilidade.

Um grupo de origens inclui duas origens (uma primária e uma secundária) e critérios de failover especificados por você. Você cria um grupo de origem para oferecer suporte ao failover de origem no CloudFront. Ao criar ou atualizar um grupo de origens usando esse método, você pode especificar o grupo de origens em vez de uma única origem. O CloudFront fará o failover da origem primária para a origem secundária usando os critérios de failover.

Se você tiver uma origem de VPC configurada em sua distribuição, poderá usar esse método para criar um grupo de origens usando uma origem de VPC. Para obter mais informações, consulte Restringe o acesso com origens de VPC..

Solicitação

createRequestOriginGroup({origin_group_properties})

No exemplo anterior, as origin_group_properties podem conter o seguinte:

originIds (obrigatório)

Matriz de origin_ids, em que o origin_id é uma string que aponta para o nome de uma origem na distribuição que executa a função. É necessário fornecer duas origens como parte da matriz. A primeira origem na lista é a primária e a segunda serve como a segunda origem para fins de failover.

selectionCriteria (opcional)

Selecione se deseja usar os critérios de failover da origem default ou usar a lógica de failover baseada em media-quality-score. Os valores válidos são os seguintes:

  • default usa os critérios de failover com base nos códigos de status especificados nos failoverCriteria. Se você não definir selectionCriteria na função, a default será usada.

  • media-quality-score é usado quando o recurso de roteamento com reconhecimento de mídia está sendo usado.

failoverCriteria (obrigatório)

Uma matriz de códigos de status que, quando retornados da origem primária, acionarão o CloudFront para fazer failover para a origem secundária. Se você sobrescrever um grupo de origens existente, essa matriz substituirá todos os códigos de status de failover definidos na configuração original do grupo de origens.

Quando você usar media-quality-score como selectionCriteria, o CloudFront tentará encaminhar as solicitações com base na pontuação de qualidade de mídia. Se a origem selecionada retornar um código de erro definido nessa matriz, o CloudFront fará failover para a outra origem.

exemplo – Criar grupo de origens para uma solicitação

O exemplo a seguir cria um grupo de origens para uma solicitação usando os IDs de origem. Esses IDs de origem provêm da configuração do grupo de origens da distribuição usada para executar essa função.

cf.createRequestOriginGroup({
    originIds: ["us-east-1-s3-origin", "us-west-2-s3-origin"],
    failoverCriteria: {
        statusCodes: [500, 502, 503, 504] 
    }
});