Here is your custom content.
" } } } ``` ## Exemplo de objeto de evento O exemplo a seguir mostra um objeto `event` completo. Este é um exemplo de invocação para uma distribuição padrão, e não para uma distribuição multilocatário. Para distribuições multilocatário, é usado o campo `endpoint`, em vez de `distributionDomainName`. O valor de `endpoint` é o nome de domínio do CloudFront (por exemplo, d111111abcdef8.cloudfront.net) do grupo de conexões associado ao evento. **nota** O objeto `event` é a entrada para sua função. Sua função retorna apenas o objeto `request` ou `response`, não o objeto `event` completo. ``` { "version": "1.0", "context": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-response", "requestId": "EXAMPLEntjQpEXAMPLE_SG5Z-EXAMPLEPmPfEXAMPLEu3EqEXAMPLE==" }, "viewer": {"ip": "198.51.100.11"}, "request": { "method": "GET", "uri": "/media/index.mpd", "querystring": { "ID": {"value": "42"}, "Exp": {"value": "1619740800"}, "TTL": {"value": "1440"}, "NoValue": {"value": ""}, "querymv": { "value": "val1", "multiValue": [ {"value": "val1"}, {"value": "val2,val3"} ] } }, "headers": { "host": {"value": "video.example.com"}, "user-agent": {"value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:83.0) Gecko/20100101 Firefox/83.0"}, "accept": { "value": "application/json", "multiValue": [ {"value": "application/json"}, {"value": "application/xml"}, {"value": "text/html"} ] }, "accept-language": {"value": "en-GB,en;q=0.5"}, "accept-encoding": {"value": "gzip, deflate, br"}, "origin": {"value": "https://website.example.com"}, "referer": {"value": "https://website.example.com/videos/12345678?action=play"}, "cloudfront-viewer-country": {"value": "GB"} }, "cookies": { "Cookie1": {"value": "value1"}, "Cookie2": {"value": "value2"}, "cookie_consent": {"value": "true"}, "cookiemv": { "value": "value3", "multiValue": [ {"value": "value3"}, {"value": "value4"} ] } } }, "response": { "statusCode": 200, "statusDescription": "OK", "headers": { "date": {"value": "Mon, 04 Apr 2021 18:57:56 GMT"}, "server": {"value": "gunicorn/19.9.0"}, "access-control-allow-origin": {"value": "*"}, "access-control-allow-credentials": {"value": "true"}, "content-type": {"value": "application/json"}, "content-length": {"value": "701"} }, "cookies": { "ID": { "value": "id1234", "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT" }, "Cookie1": { "value": "val1", "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT", "multiValue": [ { "value": "val1", "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT" }, { "value": "val2", "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT" } ] } } } } ``` # Recursos de tempo de execução JavaScript para funções do CloudFront O ambiente de runtime do JavaScript do CloudFront Functions é compatível com o [ECMAScript (ES) versão 5.1](https://www.ecma-international.org/ecma-262/5.1/) e também é compatível com alguns recursos das versões 6 a 12 do ES. Para ter os recursos mais atualizados, recomendamos usar o JavaScript runtime 2.0. Os recursos do JavaScript runtime 2.0 têm as seguintes alterações em comparação com o 1.0: + Os métodos do módulo de buffer estão disponíveis. + Os seguintes métodos de protótipo de string não padrão não estão disponíveis: + `String.prototype.bytesFrom()` + `String.prototype.fromBytes()` + `String.prototype.fromUTF8()` + `String.prototype.toBytes()` + `String.prototype.toUTF8()` + O módulo criptográfico tem as seguintes alterações: + `hash.digest()`: o tipo de retorno será alterado para `Buffer` se nenhuma codificação for fornecida. + `hmac.digest()`: o tipo de retorno será alterado para `Buffer` se nenhuma codificação for fornecida. + Para ter mais informações sobre novos recursos adicionais, consulte [Recursos de runtime 2.0 do JavaScript para CloudFront Functions](functions-javascript-runtime-20.md). **Topics** + [Recursos de runtime 1.0 do JavaScript](functions-javascript-runtime-10.md) + [Recursos de runtime 2.0 do JavaScript](functions-javascript-runtime-20.md) # Recursos de runtime 1.0 do JavaScript para CloudFront Functions O ambiente de runtime do JavaScript do CloudFront Functions é compatível com o [ECMAScript (ES) versão 5.1](https://262.ecma-international.org/5.1/) e também é compatível com alguns recursos das versões ES 6 a 9. Ele também fornece alguns métodos não padronizados que não fazem parte das especificações ES. Os tópicos a seguir listam todos os recursos de idioma compatíveis. **Topics** + [ ## Recursos principais ](#writing-functions-javascript-features-core) + [ ## Objetos primitivos ](#writing-functions-javascript-features-primitive-objects) + [ ## Objetos integrados ](#writing-functions-javascript-features-builtin-objects) + [ ## Tipos de erro ](#writing-functions-javascript-features-error-types) + [ ## Variáveis globais ](#writing-functions-javascript-features-globals) + [ ## Módulos integrados ](#writing-functions-javascript-features-builtin-modules) + [ ## Recursos restritos ](#writing-functions-javascript-features-restricted-features) ## Recursos principais Os seguintes recursos principais do ES são compatíveis. **Tipos** Todos os tipos ES 5.1 são compatíveis. Isso inclui valores booleanos, números, cadeias de caracteres, objetos, matrizes, funções, construtores de funções e expressões regulares. **Operadores** Todos os operadores ES 5.1 são compatíveis. O operador de exponenciação ES 7 (`**`) é compatível. **Declarações** As instruções `const` e `let` não são compatíveis. As seguintes instruções ES 5.1 são compatíveis: + `break` + `catch` + `continue` + `do-while` + `else` + `finally` + `for` + `for-in` + `if` + `return` + `switch` + `throw` + `try` + `var` + `while` + Instruções rotuladas **Literais** Os literais de modelo ES 6 são compatíveis: cadeias de várias linhas, interpolação de expressão e modelos de aninhamento. **Funções** Todos os recursos de função ES 5.1 são compatíveis. As funções de seta ES 6 são compatíveis, assim como a sintaxe de parâmetro de descanso ES 6. **Unicode** Texto de origem e literais de cadeias de caracteres podem conter caracteres codificados em Unicode. Sequências de escape de ponto de código Unicode de seis caracteres (por exemplo, `\uXXXX`) também são compatíveis. **Modo estrito** As funções operam no modo estrito por padrão, então você não precisa adicionar uma instrução `use strict` ao seu código de função. Elas não podem ser alteradas. ## Objetos primitivos Os seguintes objetos primitivos de ES são compatíveis. **Objeto** Os seguintes métodos ES 5.1 em objetos são compatíveis: + `create` (sem lista de propriedades) + `defineProperties` + `defineProperty` + `freeze` + `getOwnPropertyDescriptor` + `getOwnPropertyNames` + `getPrototypeOf` + `hasOwnProperty` + `isExtensible` + `isFrozen` + `prototype.isPrototypeOf` + `isSealed` + `keys` + `preventExtensions` + `prototype.propertyIsEnumerable` + `seal` + `prototype.toString` + `prototype.valueOf` Os seguintes métodos ES 6 em objetos são compatíveis: + `assign` + `is` + `prototype.setPrototypeOf` Os seguintes métodos ES 8 em objetos são compatíveis: + `entries` + `values` **String** Os seguintes métodos ES 5.1 em cadeias de caracteres são compatíveis: + `fromCharCode` + `prototype.charAt` + `prototype.concat` + `prototype.indexOf` + `prototype.lastIndexOf` + `prototype.match` + `prototype.replace` + `prototype.search` + `prototype.slice` + `prototype.split` + `prototype.substr` + `prototype.substring` + `prototype.toLowerCase` + `prototype.trim` + `prototype.toUpperCase` Os seguintes métodos ES 6 em cadeias de caracteres são compatíveis: + `fromCodePoint` + `prototype.codePointAt` + `prototype.endsWith` + `prototype.includes` + `prototype.repeat` + `prototype.startsWith` Os seguintes métodos ES 8 em cadeias de caracteres são compatíveis: + `prototype.padStart` + `prototype.padEnd` Os seguintes métodos ES 9 em cadeias de caracteres são compatíveis: + `prototype.trimStart` + `prototype.trimEnd` Os seguintes métodos não padronizados em cadeias de caracteres são compatíveis: + `prototype.bytesFrom(array | string, encoding)` Cria uma cadeia de caracteres de bytes de uma matriz de octetos ou uma cadeia de caracteres codificada. As opções de codificação de cadeia de caracteres são `hex`, `base64` e `base64url`. + `prototype.fromBytes(start[, end])` Cria uma cadeia de caracteres Unicode de uma cadeia de caracteres de bytes em que cada byte é substituído pelo ponto de código Unicode correspondente. + `prototype.fromUTF8(start[, end])` Cria uma cadeia de caracteres Unicode de uma cadeia de caracteres de bytes codificada UTF-8. Se a codificação estiver incorreta, ela retorna `null`. + `prototype.toBytes(start[, end])` Cria uma cadeia de caracteres de bytes de uma cadeia de caracteres Unicode. Todos os caracteres devem estar no intervalo de [0.255]. Se não, ele retorna `null`. + `prototype.toUTF8(start[, end])` Cria uma cadeia de caracteres de bytes codificada UTF-8 de uma cadeia de caracteres Unicode. **telefone** Todos os métodos ES 5.1 em números são compatíveis. Os seguintes métodos ES 6 em números são compatíveis: + `isFinite` + `isInteger` + `isNaN` + `isSafeInteger` + `parseFloat` + `parseInt` + `prototype.toExponential` + `prototype.toFixed` + `prototype.toPrecision` + `EPSILON` + `MAX_SAFE_INTEGER` + `MAX_VALUE` + `MIN_SAFE_INTEGER` + `MIN_VALUE` + `NEGATIVE_INFINITY` + `NaN` + `POSITIVE_INFINITY` ## Objetos integrados Os seguintes objetos integrados do ES são compatíveis. **Matemática** Todos os métodos matemáticos ES 5.1 são compatíveis. No ambiente de tempo de execução do CloudFront Functions, a implementação `Math.random()` usa o OpenBSD `arc4random` propagado com o carimbo de data/hora de quando a função é executada. Os seguintes métodos matemáticos ES 6 são compatíveis: + `acosh` + `asinh` + `atanh` + `cbrt` + `clz32` + `cosh` + `expm1` + `fround` + `hypot` + `imul` + `log10` + `log1p` + `log2` + `sign` + `sinh` + `tanh` + `trunc` + `E` + `LN10` + `LN2` + `LOG10E` + `LOG2E` + `PI` + `SQRT1_2` + `SQRT2` **Data** Todos os recursos `Date` do ES 5.1 são compatíveis. Por razões de segurança, `Date` sempre retorna o mesmo valor, que seria o horário de início da função, durante o tempo de vida de uma única execução de função. Para obter mais informações, consulte [Recursos restritos](#writing-functions-javascript-features-restricted-features). **Função** Os métodos `apply`, `bind` e `call` são compatíveis. Os construtores de função não são compatíveis. **Expressões regulares** Todos os recursos de expressão regular ES 5.1 são compatíveis. A linguagem de expressão regular é compatível com Perl. Os grupos de captura nomeados ES 9 são compatíveis. **JSON** Todos os recursos JSON ES 5.1 são compatíveis, incluindo `parse` e `stringify`. **Array** Os seguintes métodos ES 5.1 em matrizes são compatíveis: + `isArray` + `prototype.concat` + `prototype.every` + `prototype.filter` + `prototype.forEach` + `prototype.indexOf` + `prototype.join` + `prototype.lastIndexOf` + `prototype.map` + `prototype.pop` + `prototype.push` + `prototype.reduce` + `prototype.reduceRight` + `prototype.reverse` + `prototype.shift` + `prototype.slice` + `prototype.some` + `prototype.sort` + `prototype.splice` + `prototype.unshift` Os seguintes métodos ES 6 em matrizes são compatíveis: + `of` + `prototype.copyWithin` + `prototype.fill` + `prototype.find` + `prototype.findIndex` Os seguintes métodos ES 7 em matrizes são compatíveis: + `prototype.includes` **Matrizes digitadas** As seguintes matrizes ES 6 digitadas são compatíveis: + `Int8Array` + `Uint8Array` + `Uint8ClampedArray` + `Int16Array` + `Uint16Array` + `Int32Array` + `Uint32Array` + `Float32Array` + `Float64Array` + `prototype.copyWithin` + `prototype.fill` + `prototype.join` + `prototype.set` + `prototype.slice` + `prototype.subarray` + `prototype.toString` **ArrayBuffer** Os seguintes métodos em `ArrayBuffer` são compatíveis: + `prototype.isView` + `prototype.slice` **Promessa** Os seguintes métodos em promises são compatíveis: + `reject` + `resolve` + `prototype.catch` + `prototype.finally` + `prototype.then` **Criptografia** O módulo criptográfico fornece auxiliares de código de autenticação de mensagens (HMAC) padrão e hash. Você pode carregar o módulo usando `require('crypto')`. O módulo expõe os seguintes métodos que se comportam exatamente como suas contrapartes Node.js: + `createHash(algorithm)` + `hash.update(data)` + `hash.digest([encoding])` + `createHmac(algorithm, secret key)` + `hmac.update(data)` + `hmac.digest([encoding])` Para mais informações, consulte [Criptográficos (hash e HMAC)](#writing-functions-javascript-features-builtin-modules-crypto) na seção de módulos integrados. **Console** Este é um objeto auxiliar para depuração. Ele só é compatível com o método `log()` para gravar mensagens de log. O CloudFront Functions não é compatível com sintaxe de vírgula, como `console.log('a', 'b')`. Em vez disso, use o formato `console.log('a' + ' ' + 'b')`. ## Tipos de erro Os seguintes objetos de erro são compatíveis: + `Error` + `EvalError` + `InternalError` + `MemoryError` + `RangeError` + `ReferenceError` + `SyntaxError` + `TypeError` + `URIError` ## Variáveis globais O objeto `globalThis` é compatível. As seguintes funções globais do ES 5.1 são compatíveis: + `decodeURI` + `decodeURIComponent` + `encodeURI` + `encodeURIComponent` + `isFinite` + `isNaN` + `parseFloat` + `parseInt` As seguintes restrições globais são válidas: + `NaN` + `Infinity` + `undefined` ## Módulos integrados Os seguintes módulos integrados são compatíveis: **Topics** + [ ### Criptográficos (hash e HMAC) ](#writing-functions-javascript-features-builtin-modules-crypto) + [ ### String de consulta ](#writing-functions-javascript-features-builtin-modules-query-string) ### Criptográficos (hash e HMAC) O módulo criptográfico (`crypto`) fornece auxiliares de código de autenticação de mensagens (HMAC) padrão e hash. Você pode carregar o módulo usando `require('crypto')`. O módulo fornece os seguintes métodos que se comportam exatamente como suas contrapartes Node.js. **Métodos de hash** `crypto.createHash(algorithm)` Cria e retorna um objeto hash que você pode usar para gerar resumos de hash usando o algoritmo fornecido: `md5`, `sha1` ou `sha256`. `hash.update(data)` Atualiza o conteúdo de hash com os fornecido `data`. `hash.digest([encoding])` Calcula o resumo de todos os dados passados usando `hash.update()`. A codificação pode ser `hex`, `base64` ou `base64url`. **Métodos de HMAC** `crypto.createHmac(algorithm, secret key)` Cria e retorna um objeto HMAC que usa o `algorithm` e a `secret key` fornecidos. O algoritmo pode ser `md5`, `sha1` ou `sha256`. `hmac.update(data)` Atualiza o conteúdo HMAC com os fornecido `data`. `hmac.digest([encoding])` Calcula o resumo de todos os dados passados usando `hmac.update()`. A codificação pode ser `hex`, `base64` ou `base64url`. ### String de consulta **nota** O [objeto de evento CloudFront Functions](functions-event-structure.md) analisa automaticamente as cadeias de consulta de URL para você. Isso significa que na maioria dos casos você não precisa usar este módulo. O módulo cadeia de consulta (`querystring`) fornece métodos para analisar e formatar cadeias de consulta de URL. Você pode carregar o módulo usando `require('querystring')`. O módulo fornece os seguintes métodos: `querystring.escape(string)` O URL codifica a `string` fornecida, retornando uma cadeia de consulta escapada. O método é usado por `querystring.stringify()` e não deve ser usado diretamente. `querystring.parse(string[, separator[, equal[, options]]])` Analisa uma cadeia de consulta (`string`) e retorna um objeto. O parâmetro `separator` é uma substring para delimitar pares de chaves e valores na cadeia de consulta. O padrão é `&`. O parâmetro `equal` é uma substring para delimitar chaves e valores na cadeia de consulta. O padrão é `=`. O parâmetro `options` é um objeto com as seguintes chaves: `decodeURIComponent function` Uma função para decodificar caracteres codificados por percentual na cadeia de consulta. O padrão é `querystring.unescape()`. `maxKeys number` O número máximo de chaves a serem analisadas. O padrão é `1000`. Use um valor de `0` para remover as limitações para as chaves de contagem. Por padrão, os caracteres codificados por percentual dentro da cadeia de consulta são assumidos para usar a codificação UTF-8. Sequências UTF-8 inválidas são substituídas pelo caractere de substituição `U+FFFD`. Por exemplo, para a seguinte cadeia de consulta: ``` 'name=value&abc=xyz&abc=123' ``` O valor de retorno de `querystring.parse()` é: ``` { name: 'value', abc: ['xyz', '123'] } ``` `querystring.decode()` é um alias para `querystring.parse()`. `querystring.stringify(object[, separator[, equal[, options]]])` Serializa um `object` e retorna uma cadeia de consulta. O parâmetro `separator` é uma substring para delimitar pares de chaves e valores na cadeia de consulta. O padrão é `&`. O parâmetro `equal` é uma substring para delimitar chaves e valores na cadeia de consulta. O padrão é `=`. O parâmetro `options` é um objeto com as seguintes chaves: `encodeURIComponent function` A função a ser usada para converter caracteres URL-inseguros para codificação percentual na cadeia de consulta. O padrão é `querystring.escape()`. Por padrão, os caracteres que exigem percentual de codificação dentro da cadeia de consulta são codificados como UTF-8. Para usar uma codificação diferente, especifique a opção `encodeURIComponent`. Por exemplo, para o seguinte código: ``` querystring.stringify({ name: 'value', abc: ['xyz', '123'], anotherName: '' }); ``` O valor de retorno é: ``` 'name=value&abc=xyz&abc=123&anotherName=' ``` `querystring.encode()` é um alias para `querystring.stringify()`. `querystring.unescape(string)` Decodifica caracteres codificados por porcentagem de URL na `string` fornecida, retornando uma cadeia de consulta sem escapamento. Esse método é usado por `querystring.parse()` e não deve ser usado diretamente. ## Recursos restritos Os seguintes recursos de linguagem JavaScript não são compatíveis ou são restritos devido a preocupações de segurança. **Avaliação dinâmica do código** A avaliação dinâmica do código não é compatível. Ambos os construtores `eval()` e `Function` lançam um erro se forem tentados. Por exemplo, `const sum = new Function('a', 'b', 'return a + b')` lança um erro. **Temporizadores ** As funções `setTimeout()`, `setImmediate()` e `clearTimeout()` não são compatíveis. Não há provisão para adiar ou renderizar dentro de uma execução de função. Sua função deve ser executada de forma síncrona até a conclusão. **Data e carimbos de data/hora** Por razões de segurança, não há acesso a temporizadores de alta resolução. Todos os métodos `Date` para consultar a hora atual sempre retornam o mesmo valor durante o tempo de vida de uma única execução de função. O carimbo de data/hora retornado é o momento em que a função começou a ser executada. Consequentemente, você não pode medir o tempo decorrido em sua função. **Acesso ao sistema de arquivos** Não há acesso ao sistema de arquivos. Por exemplo, não há módulo `fs` para acesso ao sistema de arquivos como no Node.js. **Acesso a processos** Não há acesso a processos. Por exemplo, não há um objeto global `process` para processar o acesso às informações como no Node.js. **Variáveis de ambiente** Não há acesso às variáveis de ambiente. Em vez disso, é possível usar o KeyValueStore do CloudFront para criar um datastore centralizado de pares de chave-valor para o CloudFront Functions. O KeyValueStore do CloudFront permite atualizações dinâmicas nos dados de configuração sem a necessidade de implantar alterações no código. É necessário usar o [JavaScript runtime 2.0](functions-javascript-runtime-20.md) para usar o KeyValueStore do CloudFront. Para obter mais informações, consulte [Amazon CloudFront KeyValueStore](kvs-with-functions.md). **Acesso à rede** Não há suporte para chamadas de rede. Por exemplo, XHR, HTTP (S) e socket não são compatíveis. # Recursos de runtime 2.0 do JavaScript para CloudFront Functions O ambiente de runtime do JavaScript do CloudFront Functions é compatível com o [ECMAScript (ES) versão 5.1](https://262.ecma-international.org/5.1/) e também é compatível com alguns recursos das versões 6 a 12 do ES. Ele também fornece alguns métodos não padronizados que não fazem parte das especificações ES. Os tópicos a seguir listam todos os recursos compatíveis nesse runtime. **Topics** + [ ## Recursos principais ](#writing-functions-javascript-features-core-20) + [ ## Objetos primitivos ](#writing-functions-javascript-features-primitive-objects-20) + [ ## Objetos integrados ](#writing-functions-javascript-features-builtin-objects-20) + [ ## Tipos de erro ](#writing-functions-javascript-features-error-types-20) + [ ## Variáveis globais ](#writing-functions-javascript-features-globals-20) + [ ## Módulos integrados ](#writing-functions-javascript-features-builtin-modules-20) + [ ## Recursos restritos ](#writing-functions-javascript-features-restricted-features-20) ## Recursos principais Os seguintes recursos principais do ES são compatíveis. **Tipos** Todos os tipos ES 5.1 são compatíveis. Isso inclui valores boolianos, números, strings, objetos, matrizes, funções e expressões regulares. **Operadores** Todos os operadores ES 5.1 são compatíveis. O operador de exponenciação ES 7 (`**`) é compatível. **Declarações** As seguintes instruções ES 5.1 são compatíveis: + `break` + `catch` + `continue` + `do-while` + `else` + `finally` + `for` + `for-in` + `if` + `label` + `return` + `switch` + `throw` + `try` + `var` + `while` As seguintes instruções do ES 6 são compatíveis: + `const` + `let` As seguintes instruções do ES 8 são compatíveis: + `async` + `await` `async`, `await`, `const` e `let` são compatíveis com o runtime 2.0 do JavaScript. `await` pode ser usado apenas dentro de funções `async`. Encerramentos e argumentos `async` não são compatíveis. **Literais** Os literais de modelo ES 6 são compatíveis: cadeias de várias linhas, interpolação de expressão e modelos de aninhamento. **Funções** Todos os recursos de função ES 5.1 são compatíveis. As funções de seta ES 6 são compatíveis, assim como a sintaxe de parâmetro de descanso ES 6. **Unicode** Texto de origem e literais de cadeias de caracteres podem conter caracteres codificados em Unicode. Sequências de escape de ponto de código Unicode de seis caracteres (por exemplo, `\uXXXX`) também são compatíveis. **Modo estrito** As funções operam no modo estrito por padrão, então você não precisa adicionar uma instrução `use strict` ao seu código de função. Elas não podem ser alteradas. ## Objetos primitivos Os seguintes objetos primitivos de ES são compatíveis. **Objeto** Os seguintes métodos ES 5.1 em objetos são compatíveis: + `Object.create()` (sem lista de propriedades) + `Object.defineProperties()` + `Object.defineProperty()` + `Object.freeze()` + `Object.getOwnPropertyDescriptor()` + `Object.getOwnPropertyDescriptors()` + `Object.getOwnPropertyNames()` + `Object.getPrototypeOf()` + `Object.isExtensible()` + `Object.isFrozen()` + `Object.isSealed()` + `Object.keys()` + `Object.preventExtensions()` + `Object.seal()` Os seguintes métodos ES 6 em objetos são compatíveis: + `Object.assign()` Os seguintes métodos ES 8 em objetos são compatíveis: + `Object.entries()` + `Object.values()` Os seguintes métodos de protótipo do ES 5.1 em objetos são compatíveis: + `Object.prototype.hasOwnProperty()` + `Object.prototype.isPrototypeOf()` + `Object.prototype.propertyIsEnumerable()` + `Object.prototype.toString()` + `Object.prototype.valueOf()` Os seguintes métodos de protótipo do ES 6 em objetos são compatíveis: + `Object.prototype.is()` + `Object.prototype.setPrototypeOf()` **String** Os seguintes métodos ES 5.1 em cadeias de caracteres são compatíveis: + `String.fromCharCode()` Os seguintes métodos ES 6 em cadeias de caracteres são compatíveis: + `String.fromCodePoint()` Os seguintes métodos de protótipo do ES 5.1 em strings são compatíveis: + `String.prototype.charAt()` + `String.prototype.concat()` + `String.prototype.indexOf()` + `String.prototype.lastIndexOf()` + `String.prototype.match()` + `String.prototype.replace()` + `String.prototype.search()` + `String.prototype.slice()` + `String.prototype.split()` + `String.prototype.substr()` + `String.prototype.substring()` + `String.prototype.toLowerCase()` + `String.prototype.trim()` + `String.prototype.toUpperCase()` Os seguintes métodos de protótipo do ES 6 em strings são compatíveis: + `String.prototype.codePointAt()` + `String.prototype.endsWith()` + `String.prototype.includes()` + `String.prototype.repeat()` + `String.prototype.startsWith()` Os seguintes métodos de protótipo do ES 8 em strings são compatíveis: + `String.prototype.padStart()` + `String.prototype.padEnd()` Os seguintes métodos de protótipo do ES 9 em strings são compatíveis: + `String.prototype.trimStart()` + `String.prototype.trimEnd()` Os seguintes métodos de protótipo do ES 12 em strings são compatíveis: + `String.prototype.replaceAll()` **nota** `String.prototype.replaceAll()` é um recurso novo no runtime 2.0 do JavaScript. **Número** Todos os números do ES 5 são compatíveis. As seguintes propriedades do ES 6 em números são compatíveis: + `Number.EPSILON` + `Number.MAX_SAFE_INTEGER` + `Number.MIN_SAFE_INTEGER` + `Number.MAX_VALUE` + `Number.MIN_VALUE` + `Number.NaN` + `Number.NEGATIVE_INFINITY` + `Number.POSITIVE_INFINITY` Os seguintes métodos ES 6 em números são compatíveis: + `Number.isFinite()` + `Number.isInteger()` + `Number.isNaN()` + `Number.isSafeInteger()` + `Number.parseInt()` + `Number.parseFloat()` Os seguintes métodos de protótipo do ES 5.1 em números são compatíveis: + `Number.prototype.toExponential()` + `Number.prototype.toFixed()` + `Number.prototype.toPrecision()` Separadores numéricos ES 12 são compatíveis. Os separadores numéricos ES 12 são novos no runtime 2.0 do JavaScript. ## Objetos integrados Os seguintes objetos integrados do ES são compatíveis. **Matemática** Todos os métodos matemáticos ES 5.1 são compatíveis. No ambiente de tempo de execução do CloudFront Functions, a implementação `Math.random()` usa o OpenBSD `arc4random` propagado com o carimbo de data/hora de quando a função é executada. As seguintes propriedades matemáticas do ES 6 são compatíveis: + `Math.E` + `Math.LN10` + `Math.LN2` + `Math.LOG10E` + `Math.LOG2E` + `Math.PI` + `Math.SQRT1_2` + `Math.SQRT2` Os seguintes métodos matemáticos ES 6 são compatíveis: + `Math.abs()` + `Math.acos()` + `Math.acosh()` + `Math.asin()` + `Math.asinh()` + `Math.atan()` + `Math.atan2()` + `Math.atanh()` + `Math.cbrt()` + `Math.ceil()` + `Math.clz32()` + `Math.cos()` + `Math.cosh()` + `Math.exp()` + `Math.expm1()` + `Math.floor()` + `Math.fround()` + `Math.hypot()` + `Math.imul()` + `Math.log()` + `Math.log1p()` + `Math.log2()` + `Math.log10()` + `Math.max()` + `Math.min()` + `Math.pow()` + `Math.random()` + `Math.round()` + `Math.sign()` + `Math.sinh()` + `Math.sin()` + `Math.sqrt()` + `Math.tan()` + `Math.tanh()` + `Math.trunc()` **Data** Todos os recursos `Date` do ES 5.1 são compatíveis. Por razões de segurança, `Date` sempre retorna o mesmo valor, que seria o horário de início da função, durante o tempo de vida de uma única execução de função. Para obter mais informações, consulte [Recursos restritos](functions-javascript-runtime-10.md#writing-functions-javascript-features-restricted-features). **Função** Os seguintes métodos de protótipo do ES 5.1 são compatíveis: + `Function.prototype.apply()` + `Function.prototype.bind()` + `Function.prototype.call()` Os construtores de função não são compatíveis. **Expressões regulares** Todos os recursos de expressão regular ES 5.1 são compatíveis. A linguagem de expressão regular é compatível com Perl. As seguintes propriedades do acessador de protótipos do ES 5.1 são compatíveis: + `RegExp.prototype.global` + `RegExp.prototype.ignoreCase` + `RegExp.protoype.multiline` + `RegExp.protoype.source` + `RegExp.prototype.sticky` + `RegExp.prototype.flags` **nota** `RegExp.prototype.sticky` e `RegExp.prototype.flags` são recursos novos no runtime 2.0 do JavaScript. Os seguintes métodos de protótipo do ES 5.1 são compatíveis: + `RegExp.prototype.exec()` + `RegExp.prototype.test()` + `RegExp.prototype.toString()` + `RegExp.prototype[@@replace]()` + `RegExp.prototype[@@split]()` **nota** `RegExp.prototype[@@split]()` é um recurso novo no runtime 2.0 do JavaScript. As seguintes propriedades de instância do ES 5.1 são compatíveis: + `lastIndex` Os grupos de captura nomeados ES 9 são compatíveis. **JSON** Os seguintes métodos do ES 5.1 são compatíveis: + `JSON.parse()` + `JSON.stringify()` **Array** Os seguintes métodos ES 5.1 em matrizes são compatíveis: + `Array.isArray()` Os seguintes métodos ES 6 em matrizes são compatíveis: + `Array.of()` Os seguintes métodos de protótipo do ES 5.1 são compatíveis: + `Array.prototype.concat()` + `Array.prototype.every()` + `Array.prototype.filter()` + `Array.prototype.forEach()` + `Array.prototype.indexOf()` + `Array.prototype.join()` + `Array.prototype.lastIndexOf()` + `Array.prototype.map()` + `Array.prototype.pop()` + `Array.prototype.push()` + `Array.prototype.reduce()` + `Array.prototype.reduceRight()` + `Array.prototype.reverse()` + `Array.prototype.shift()` + `Array.prototype.slice()` + `Array.prototype.some()` + `Array.prototype.sort()` + `Array.prototype.splice()` + `Array.prototype.unshift()` Os seguintes métodos de protótipo do ES 6 são compatíveis + `Array.prototype.copyWithin()` + `Array.prototype.fill()` + `Array.prototype.find()` + `Array.prototype.findIndex()` Os seguintes métodos de protótipo do ES 7 são compatíveis: + `Array.prototype.includes()` **Matrizes digitadas** Os seguintes construtores de matriz de tipo do ES 6 são compatíveis: + `Float32Array` + `Float64Array` + `Int8Array` + `Int16Array` + `Int32Array` + `Uint8Array` + `Uint8ClampedArray` + `Uint16Array` + `Uint32Array` Os seguintes métodos do ES 6 são compatíveis: + `TypedArray.from()` + `TypedArray.of()` **nota** `TypedArray.from()` e `TypedArray.of()` são recursos novos no runtime 2.0 do JavaScript. Os seguintes métodos de protótipo do ES 6 são compatíveis + `TypedArray.prototype.copyWithin()` + `TypedArray.prototype.every()` + `TypedArray.prototype.fill()` + `TypedArray.prototype.filter()` + `TypedArray.prototype.find()` + `TypedArray.prototype.findIndex()` + `TypedArray.prototype.forEach()` + `TypedArray.prototype.includes()` + `TypedArray.prototype.indexOf()` + `TypedArray.prototype.join()` + `TypedArray.prototype.lastIndexOf()` + `TypedArray.prototype.map()` + `TypedArray.prototype.reduce()` + `TypedArray.prototype.reduceRight()` + `TypedArray.prototype.reverse()` + `TypedArray.prototype.some()` + `TypedArray.prototype.set()` + `TypedArray.prototype.slice()` + `TypedArray.prototype.sort()` + `TypedArray.prototype.subarray()` + `TypedArray.prototype.toString()` **nota** `TypedArray.prototype.every()`, `TypedArray.prototype.fill()`, `TypedArray.prototype.filter()`, `TypedArray.prototype.find()`, `TypedArray.prototype.findIndex()`, `TypedArray.prototype.forEach()`, `TypedArray.prototype.includes()`, `TypedArray.prototype.indexOf()`, `TypedArray.prototype.join()`, `TypedArray.prototype.lastIndexOf()`, `TypedArray.prototype.map()`, `TypedArray.prototype.reduce()`, `TypedArray.prototype.reduceRight()`, `TypedArray.prototype.reverse()` e `TypedArray.prototype.some()` são recursos novos no runtime 2.0 do JavaScript. **ArrayBuffer** Os seguintes métodos do ES 6 em ArrayBuffer são compatíveis: + `isView()` Os seguintes métodos de protótipo do ES 6 em ArrayBuffer são compatíveis: + `ArrayBuffer.prototype.slice()` **Promessa** Os seguintes métodos do ES 6 em promises são compatíveis: + `Promise.all()` + `Promise.allSettled()` + `Promise.any()` + `Promise.reject()` + `Promise.resolve()` + `Promise.race()` **nota** `Promise.all()`, `Promise.allSettled()`, `Promise.any()` e `Promise.race()` são recursos novos no runtime 2.0 do JavaScript. Os seguintes métodos de protótipo do ES 6 em promises são compatíveis: + `Promise.prototype.catch()` + `Promise.prototype.finally()` + `Promise.prototype.then()` **DataView** Os seguintes métodos de protótipo do ES 6 são compatíveis: + `DataView.prototype.getFloat32()` + `DataView.prototype.getFloat64()` + `DataView.prototype.getInt16()` + `DataView.prototype.getInt32()` + `DataView.prototype.getInt8()` + `DataView.prototype.getUint16()` + `DataView.prototype.getUint32()` + `DataView.prototype.getUint8()` + `DataView.prototype.setFloat32()` + `DataView.prototype.setFloat64()` + `DataView.prototype.setInt16()` + `DataView.prototype.setInt32()` + `DataView.prototype.setInt8()` + `DataView.prototype.setUint16()` + `DataView.prototype.setUint32()` + `DataView.prototype.setUint8()` **nota** Todos os métodos de protótipo do Dataview ES 6 são novos no runtime 2.0 do JavaScript. **Símbolo** Os seguintes métodos do ES 6 são compatíveis: + `Symbol.for()` + `Symbol.keyfor()` **nota** Todos os métodos do Symbol ES 6 são novos no runtime 2.0 do JavaScript. **Decodificador de texto** Os seguintes métodos de protótipo são compatíveis: + `TextDecoder.prototype.decode()` As seguintes propriedades do acessador de protótipos são compatíveis: + `TextDecoder.prototype.encoding` + `TextDecoder.prototype.fatal` + `TextDecoder.prototype.ignoreBOM` **Codificador de texto** Os seguintes métodos de protótipo são compatíveis: + `TextEncoder.prototype.encode()` + `TextEncoder.prototype.encodeInto()` ## Tipos de erro Os seguintes objetos de erro são compatíveis: + `Error` + `EvalError` + `InternalError` + `RangeError` + `ReferenceError` + `SyntaxError` + `TypeError` + `URIError` ## Variáveis globais O objeto `globalThis` é compatível. As seguintes funções globais do ES 5.1 são compatíveis: + `decodeURI()` + `decodeURIComponent()` + `encodeURI()` + `encodeURIComponent()` + `isFinite()` + `isNaN()` + `parseFloat()` + `parseInt()` As seguintes funções globais do ES 6 são compatíveis: + `atob()` + `btoa()` **nota** `atob()` e `btoa()` são recursos novos no runtime 2.0 do JavaScript. As seguintes restrições globais são válidas: + `NaN` + `Infinity` + `undefined` + `arguments` ## Módulos integrados Os seguintes módulos integrados são compatíveis: **Topics** + [ ### Buffer ](#writing-functions-javascript-features-builtin-modules-buffer-20) + [ ### String de consulta ](#writing-functions-javascript-features-builtin-modules-query-string-20) + [ ### Criptografia ](#writing-functions-javascript-features-builtin-modules-crypto-20) ### Buffer O módulo oferece os seguintes métodos: + `Buffer.alloc(size[, fill[, encoding]])` Aloque um `Buffer`. + `size`: tamanho do buffer. Insira um número inteiro. + `fill`: opcional. Insira uma string, `Buffer`, Uint8Array ou um número inteiro. O padrão é `0`. + `encoding`: opcional. Quando `fill` for uma string, insira uma das seguintes opções: `utf8`, `hex`, `base64` e `base64url`. O padrão é `utf8`. + `Buffer.allocUnsafe(size)` Aloque um `Buffer` não inicializado. + `size`: insira um número inteiro. + `Buffer.byteLength(value[, encoding])` Exibe o tamanho de um valor, em bytes. + `value`: uma string, `Buffer`, TypedArray, Dataview ou Arraybuffer. + `encoding`: opcional. Quando `value` for uma string, insira uma das seguintes opções: `utf8`, `hex`, `base64` e `base64url`. O padrão é `utf8`. + `Buffer.compare(buffer1, buffer2)` Compare dois `Buffer`s para ajudar a classificar matrizes. Exibirá `0` se forem iguais, `-1` se `buffer1` vier primeiro ou `1` se `buffer2` vier primeiro. + `buffer1`: insira um `Buffer`. + `buffer2`: insira um `Buffer` diferente. + `Buffer.concat(list[, totalLength])` Concatene vários `Buffer`s. Exibirá `0` se for nenhum. Exibe até `totalLength`. + `list`: insira uma lista de `Buffer`s. Observe que isso será truncado para `totalLength`. + `totalLength`: opcional. Insira um número inteiro não assinado. Use a soma das instâncias de `Buffer` na lista se estiver em branco. + `Buffer.from(array)` Crie um `Buffer` por uma matriz. + `array`: insira uma matriz de bytes de `0` a `255`. + `Buffer.from(arrayBuffer, byteOffset[, length]))` Crie uma visualização de `arrayBuffer` começando pelo deslocamento `byteOffset` com o tamanho `length`. + `arrayBuffer`: insira uma matriz `Buffer`. + `byteOffset`: insira um número inteiro. + `length`: opcional. Insira um número inteiro. + `Buffer.from(buffer)` Crie uma cópia do `Buffer`. + `buffer`: insira um `Buffer`. + `Buffer.from(object[, offsetOrEncoding[, length]])` Crie um `Buffer` por meio de um objeto. Exibirá `Buffer.from(object.valueOf(), offsetOrEncoding, length)` se `valueOf()` não for igual ao objeto. + `object`: insira um objeto. + `offsetOrEncoding`: opcional. Insira um número inteiro ou uma string de codificação. + `length`: opcional. Insira um número inteiro. + `Buffer.from(string[, encoding])` Crie um `Buffer` por meio de uma string. + `string`: insira uma string. + `encoding`: opcional. Insira uma das seguintes opções: `utf8`, `hex`, `base64` e `base64url`. O padrão é `utf8`. + `Buffer.isBuffer(object)` Confira se `object` é um buffer. Retorna `true` ou `false`. + `object`: insira um objeto. + `Buffer.isEncoding(encoding)` Confira se `encoding` é compatível. Retorna `true` ou `false`. + `encoding`: opcional. Insira uma das seguintes opções: `utf8`, `hex`, `base64` e `base64url`. O padrão é `utf8`. O módulo oferece os seguintes métodos de protótipo de buffer: + `Buffer.prototype.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])` Compare `Buffer` com o destino. Exibirá `0` se forem iguais, `1` se `buffer` vier primeiro ou `-1` se `target` vier primeiro. + `target`: insira um `Buffer`. + `targetStart`: opcional. Insira um número inteiro. O padrão é 0. + `targetEnd`: opcional. Insira um número inteiro. O padrão é o tamanho do `target`. + `sourceStart`: opcional. Insira um número inteiro. O padrão é 0. + `sourceEnd`: opcional. Insira um número inteiro. O padrão é o tamanho do `Buffer`. + `Buffer.prototype.copy(target[, targetStart[, sourceStart[, sourceEnd]]])` Copie o buffer em `target`. + `target`: insira um `Buffer` ou uma `Uint8Array`. + `targetStart`: opcional. Insira um número inteiro. O padrão é 0. + `sourceStart`: opcional. Insira um número inteiro. O padrão é 0. + `sourceEnd`: opcional. Insira um número inteiro. O padrão é o tamanho do `Buffer`. + `Buffer.prototype.equals(otherBuffer)` Compare `Buffer` com `otherBuffer`. Retorna `true` ou `false`. + `otherBuffer`: insira uma string. + `Buffer.prototype.fill(value[, offset[, end][, encoding])` Preencha `Buffer` com `value`. + `value`: insira uma string, um `Buffer` ou um número inteiro. + `offset`: opcional. Insira um número inteiro. + `end`: opcional. Insira um número inteiro. + `encoding`: opcional. Insira uma das seguintes opções: `utf8`, `hex`, `base64` e `base64url`. O padrão é `utf8`. + `Buffer.prototype.includes(value[, byteOffset][, encoding])` Pesquise `value` no `Buffer`. Retorna `true` ou `false`. + `value`: insira uma string, um `Buffer`, uma `Uint8Array` ou um número inteiro. + `byteOffset`: opcional. Insira um número inteiro. + `encoding`: opcional. Insira uma das seguintes opções: `utf8`, `hex`, `base64` e `base64url`. O padrão é `utf8`. + `Buffer.prototype.indexOf(value[, byteOffset][, encoding])` Procure o primeiro `value` em `Buffer`. Exibirá `index` se for encontrado; exibirá `-1` se não for encontrado. + `value`: insira uma string, `Buffer`, Unit8Array ou um número inteiro de 0 a 255. + `byteOffset`: opcional. Insira um número inteiro. + `encoding`: opcional. Insira uma das seguintes opções se `value` for uma string: `utf8`, `hex`, `base64` e `base64url`. O padrão é `utf8`. + `Buffer.prototype.lastIndexOf(value[, byteOffset][, encoding])` Procure o último `value` em `Buffer`. Exibirá `index` se for encontrado; exibirá `-1` se não for encontrado. + `value`: insira uma string, `Buffer`, Unit8Array ou um número inteiro de 0 a 255. + `byteOffset`: opcional. Insira um número inteiro. + `encoding`: opcional. Insira uma das seguintes opções se `value` for uma string: `utf8`, `hex`, `base64` e `base64url`. O padrão é `utf8`. + `Buffer.prototype.readInt8(offset)` Leia `Int8` em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readIntBE(offset, byteLength)` Leia `Int` como big-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `byteLength`: opcional. Insira um número inteiro de `1` a `6`. + `Buffer.prototype.readInt16BE(offset)` Leia `Int16` como big-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readInt32BE(offset)` Leia `Int32` como big-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readIntLE(offset, byteLength)` Leia `Int` como little-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.readInt16LE(offset)` Leia `Int16` como little-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readInt32LE(offset)` Leia `Int32` como little-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readUInt8(offset)` Leia `UInt8` em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readUIntBE(offset, byteLength)` Leia `UInt` como big-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.readUInt16BE(offset)` Leia `UInt16` como big-endian em `offset` de `Buffer`. + + `offset`: insira um número inteiro. + `Buffer.prototype.readUInt32BE(offset)` Leia `UInt32` como big-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readUIntLE(offset, byteLength)` Leia `UInt` como little-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.readUInt16LE(offset)` Leia `UInt16` como little-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readUInt32LE(offset)` Leia `UInt32` como little-endian em `offset` de `Buffer`. + `offset`: insira um número inteiro. + `Buffer.prototype.readDoubleBE([offset])` Leia um double de 64 bits como big-endian em `offset` de `Buffer`. + `offset`: opcional. Insira um número inteiro. + `Buffer.prototype.readDoubleLE([offset])` Leia um double de 64 bits como little-endian em `offset` de `Buffer`. + `offset`: opcional. Insira um número inteiro. + `Buffer.prototype.readFloatBE([offset])` Leia um float de 32 bits como big-endian em `offset` de `Buffer`. + `offset`: opcional. Insira um número inteiro. + `Buffer.prototype.readFloatLE([offset])` Leia um float de 32 bits como little-endian em `offset` de `Buffer`. + `offset`: opcional. Insira um número inteiro. + `Buffer.prototype.subarray([start[, end]])` Exibe uma cópia do `Buffer` que está deslocado e recortado com novos `start` e `end`. + `start`: opcional. Insira um número inteiro. O padrão é 0. + `end`: opcional. Insira um número inteiro. O padrão é o tamanho do buffer. + `Buffer.prototype.swap16()` Troque a ordem de bytes da matriz de `Buffer` tratando-a como uma matriz de números de 16 bits. O tamanho do `Buffer` deve ser divisível por 2, ou você receberá um erro. + `Buffer.prototype.swap32()` Troque a ordem de bytes da matriz de `Buffer` tratando-a como uma matriz de números de 32 bits. O tamanho do `Buffer` deve ser divisível por 4, ou você receberá um erro. + `Buffer.prototype.swap64()` Troque a ordem de bytes da matriz de `Buffer` tratando-a como uma matriz de números de 64 bits. O tamanho do `Buffer` deve ser divisível por 8, ou você receberá um erro. + `Buffer.prototype.toJSON()` Exibe `Buffer` como JSON. + `Buffer.prototype.toString([encoding[, start[, end]]])` Converta `Buffer`, de `start` em `end` em string codificada. + `encoding`: opcional. Insira uma das seguintes opções: `utf8`, `hex`, `base64` ou `base64url`. O padrão é `utf8`. + `start`: opcional. Insira um número inteiro. O padrão é 0. + `end`: opcional. Insira um número inteiro. O padrão é o tamanho do buffer. + `Buffer.prototype.write(string[, offset[, length]][, encoding])` Escreva `string` codificado em `Buffer` se houver espaço ou um `string` truncado se não houver espaço suficiente. + `string`: insira uma string. + `offset`: opcional. Insira um número inteiro. O padrão é 0. + `length`: opcional. Insira um número inteiro. O padrão é o tamanho da string. + `encoding`: opcional. Opcionalmente, insira uma das seguintes opções: `utf8`, `hex`, `base64` ou `base64url`. O padrão é `utf8`. + `Buffer.prototype.writeInt8(value, offset, byteLength)` Escreva `Int8` `value` de `byteLength` em `offset` para `Buffer`. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeIntBE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando big-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeInt16BE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando big-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeInt32BE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando big-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeIntLE(offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando little-endian. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeInt16LE(offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando little-endian. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeInt32LE(offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando little-endian. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeUInt8(value, offset, byteLength)` Escreva `UInt8` `value` de `byteLength` em `offset` para `Buffer`. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeUIntBE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando big-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeUInt16BE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando big-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeUInt32BE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando big-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeUIntLE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando little-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeUInt16LE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando little-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeUInt32LE(value, offset, byteLength)` Escreva `value` em `offset` para `Buffer`, usando little-endian. + `value`: insira um número inteiro. + `offset`: insira um número inteiro. + `byteLength`: insira um número inteiro de `1` a `6`. + `Buffer.prototype.writeDoubleBE(value, [offset])` Escreva `value` em `offset` para `Buffer`, usando big-endian. + `value`: insira um número inteiro. + `offset`: opcional. Insira um número inteiro. O padrão é 0. + `Buffer.prototype.writeDoubleLE(value, [offset])` Escreva `value` em `offset` para `Buffer`, usando little-endian. + `value`: insira um número inteiro. + `offset`: opcional. Insira um número inteiro. O padrão é 0. + `Buffer.prototype.writeFloatBE(value, [offset])` Escreva `value` em `offset` para `Buffer`, usando big-endian. + `value`: insira um número inteiro. + `offset`: opcional. Insira um número inteiro. O padrão é 0. + `Buffer.prototype.writeFloatLE(value, [offset])` Escreva `value` em `offset` para `Buffer`, usando little-endian. + `value`: insira um número inteiro. + `offset`: opcional. Insira um número inteiro. O padrão é 0. Os seguintes métodos de instância são compatíveis: + `buffer[index]` Obtenha e defina o octeto (byte) em `index` em `Buffer`. + Obtenha um número de `0` a `255`. Ou defina um número de `0` a `255`. As seguintes propriedades de instância são compatíveis: + `buffer` Obtenha o objeto `ArrayBuffer` para o buffer. + `byteOffset` Obtenha o `byteOffset` do objeto `Arraybuffer` do buffer. + `length` Obtenha a contagem de bytes do buffer. **nota** Todos os métodos do módulo de buffer são novos no runtime 2.0 do JavaScript. ### String de consulta **nota** O [objeto de evento CloudFront Functions](functions-event-structure.md) analisa automaticamente as cadeias de consulta de URL para você. Isso significa que na maioria dos casos você não precisa usar este módulo. O módulo cadeia de consulta (`querystring`) fornece métodos para analisar e formatar cadeias de consulta de URL. Você pode carregar o módulo usando `require('querystring')`. O módulo fornece os seguintes métodos: `querystring.escape(string)` O URL codifica a `string` fornecida, retornando uma cadeia de consulta escapada. O método é usado por `querystring.stringify()` e não deve ser usado diretamente. `querystring.parse(string[, separator[, equal[, options]]])` Analisa uma cadeia de consulta (`string`) e retorna um objeto. O parâmetro `separator` é uma substring para delimitar pares de chaves e valores na cadeia de consulta. O padrão é `&`. O parâmetro `equal` é uma substring para delimitar chaves e valores na cadeia de consulta. O padrão é `=`. O parâmetro `options` é um objeto com as seguintes chaves: `decodeURIComponent function` Uma função para decodificar caracteres codificados por percentual na cadeia de consulta. O padrão é `querystring.unescape()`. `maxKeys number` O número máximo de chaves a serem analisadas. O padrão é `1000`. Use um valor de `0` para remover as limitações para as chaves de contagem. Por padrão, os caracteres codificados por percentual dentro da cadeia de consulta são assumidos para usar a codificação UTF-8. Sequências UTF-8 inválidas são substituídas pelo caractere de substituição `U+FFFD`. Por exemplo, para a seguinte cadeia de consulta: ``` 'name=value&abc=xyz&abc=123' ``` O valor de retorno de `querystring.parse()` é: ``` { name: 'value', abc: ['xyz', '123'] } ``` `querystring.decode()` é um alias para `querystring.parse()`. `querystring.stringify(object[, separator[, equal[, options]]])` Serializa um `object` e retorna uma cadeia de consulta. O parâmetro `separator` é uma substring para delimitar pares de chaves e valores na cadeia de consulta. O padrão é `&`. O parâmetro `equal` é uma substring para delimitar chaves e valores na cadeia de consulta. O padrão é `=`. O parâmetro `options` é um objeto com as seguintes chaves: `encodeURIComponent function` A função a ser usada para converter caracteres URL-inseguros para codificação percentual na cadeia de consulta. O padrão é `querystring.escape()`. Por padrão, os caracteres que exigem percentual de codificação dentro da cadeia de consulta são codificados como UTF-8. Para usar uma codificação diferente, especifique a opção `encodeURIComponent`. Por exemplo, para o seguinte código: ``` querystring.stringify({ name: 'value', abc: ['xyz', '123'], anotherName: '' }); ``` O valor de retorno é: ``` 'name=value&abc=xyz&abc=123&anotherName=' ``` `querystring.encode()` é um alias para `querystring.stringify()`. `querystring.unescape(string)` Decodifica caracteres codificados por porcentagem de URL na `string` fornecida, retornando uma cadeia de consulta sem escapamento. Esse método é usado por `querystring.parse()` e não deve ser usado diretamente. ### Criptografia O módulo criptográfico (`crypto`) fornece auxiliares de código de autenticação de mensagens (HMAC) padrão e hash. Você pode carregar o módulo usando `require('crypto')`. **Métodos de hash** `crypto.createHash(algorithm)` Cria e retorna um objeto hash que você pode usar para gerar resumos de hash usando o algoritmo fornecido: `md5`, `sha1` ou `sha256`. `hash.update(data)` Atualiza o conteúdo de hash com os fornecido `data`. `hash.digest([encoding])` Calcula o resumo de todos os dados passados usando `hash.update()`. A codificação pode ser `hex`, `base64` ou `base64url`. **Métodos de HMAC** `crypto.createHmac(algorithm, secret key)` Cria e retorna um objeto HMAC que usa o `algorithm` e a `secret key` fornecidos. O algoritmo pode ser `md5`, `sha1` ou `sha256`. `hmac.update(data)` Atualiza o conteúdo HMAC com os fornecido `data`. `hmac.digest([encoding])` Calcula o resumo de todos os dados passados usando `hmac.update()`. A codificação pode ser `hex`, `base64` ou `base64url`. ## Recursos restritos Os seguintes recursos de linguagem JavaScript não são compatíveis ou são restritos devido a preocupações de segurança. **Avaliação dinâmica do código** A avaliação dinâmica do código não é compatível. Ambos os construtores `eval()` e `Function` lançam um erro se forem tentados. Por exemplo, `const sum = new Function('a', 'b', 'return a + b')` lança um erro. **Temporizadores ** As funções `setTimeout()`, `setImmediate()` e `clearTimeout()` não são compatíveis. Não há provisão para adiar ou renderizar dentro de uma execução de função. Sua função deve ser executada de forma síncrona até a conclusão. **Data e carimbos de data/hora** Por razões de segurança, não há acesso a temporizadores de alta resolução. Todos os métodos `Date` para consultar a hora atual sempre retornam o mesmo valor durante o tempo de vida de uma única execução de função. O carimbo de data/hora retornado é o momento em que a função começou a ser executada. Consequentemente, você não pode medir o tempo decorrido em sua função. **Acesso ao sistema de arquivos** Não há acesso ao sistema de arquivos. Por exemplo, não há módulo `fs` para acesso ao sistema de arquivos como no Node.js. **Acesso a processos** Não há acesso a processos. Por exemplo, não há um objeto global `process` para processar o acesso às informações como no Node.js. **Variáveis de ambiente** Não há acesso às variáveis de ambiente. Em vez disso, é possível usar o KeyValueStore do CloudFront para criar um datastore centralizado de pares de chave-valor para o CloudFront Functions. O KeyValueStore do CloudFront permite atualizações dinâmicas nos dados de configuração sem a necessidade de implantar alterações no código. Para obter mais informações, consulte [Amazon CloudFront KeyValueStore](kvs-with-functions.md). **Acesso à rede** Não há suporte para chamadas de rede. Por exemplo, XHR, HTTP (S) e socket não são compatíveis. # Métodos auxiliares para armazenamentos de chave-valor **nota** As chamadas do método auxiliar de armazenamento de chave-valor do CloudFront Functions não acionam um evento de dados do AWS CloudTrail. Esses eventos não são registrados em log no histórico de eventos do CloudTrail. Para obter mais informações, consulte [Registrar em log chamadas de API do Amazon CloudFront usando o AWS CloudTrail](logging_using_cloudtrail.md). Esta seção se aplicará se você usar o [Armazenamento de chave-valor do CloudFront](kvs-with-functions.md) para incluir chave-valor na função criada. O CloudFront Functions tem um módulo que oferece três métodos auxiliares para ler valores do armazenamento de chave-valor. Para usar esse módulo no código da função, verifique se você [associou um armazenamento de chave-valor](kvs-with-functions-associate.md) à função. Em seguida, inclua as seguintes declarações nas primeiras linhas do código da função: ``` import cf from 'cloudfront'; const kvsHandle = cf.kvs(); ``` ## `get()`Método Use esse método para retornar o valor do nome da chave especificado. **Solicitação** ``` get("key", options); ``` + `key`: o nome da chave cujo valor precisa ser buscado. + `options`: existe uma opção, `format`. Isso garante que a função analise os dados corretamente. Possíveis valores: + `string`: (padrão) codificado em UTF8. + `json` + `bytes`: buffer de dados binários brutos. **Exemplo de solicitação** ``` const value = await kvsHandle.get("myFunctionKey", { format: "string"}); ``` **Resposta** A resposta é uma `promise` que se resolve para um valor no formato solicitado usando `options`. Por padrão, o valor é retornado como uma string. ### Tratamento de erros O método `get()` retornará um erro quando a chave solicitada não existir no armazenamento de chave-valor associado. Para gerenciar esse caso de uso, é possível adicionar um bloco `try` e `catch` ao seu código. **Atenção** O uso de combinadores de promessa (por exemplo, `Promise.all` e `Promise.any`) e métodos de cadeia de promessa (por exemplo, `then` e `catch`) pode exigir alto uso de memória da função. Se sua função exceder a cota [máxima de memória da função](cloudfront-limits.md#limits-functions), ela não será executada. Para evitar esse erro, recomendamos que você use a sintaxe `await` sequencialmente ou em ciclos para solicitar vários valores. **Exemplo** ``` var value1 = await kvs.get('key1'); var value2 = await kvs.get('key2'); ``` No momento, o uso de combinadores de promessas para obter vários valores não melhorará o desempenho, como no exemplo a seguir. ``` var values = await Promise.all([kvs.get('key1'), kvs.get('key2'),]); ``` ## `exists()`Método Use esse método para identificar se a chave existe ou não no armazenamento de chave-valor. **Solicitação** ``` exists("key"); ``` **Exemplo de solicitação** ``` const exist = await kvsHandle.exists("myFunctionkey"); ``` **Resposta** A resposta é uma `promise` que retorna um booleano (`true` ou `false`). Esse valor especifica se a chave existe ou não no armazenamento de chave-valor. ## `meta()`Método Use esse método para retornar metadados sobre o armazenamento de chave-valor. **Solicitação** ``` meta(); ``` **Exemplo de solicitação** ``` const meta = await kvsHandle.meta(); ``` **Resposta** A resposta é uma `promise` que é resolvida em um objeto com as seguintes propriedades: + `creationDateTime`: a data e a hora no formato ISO 8601 em que o armazenamento de chave-valor foi criado. + `lastUpdatedDateTime`: a data e a hora em que o valor da chave armazenado foi sincronizado pela última vez a partir da origem, no formato ISO 8601. O valor não inclui o tempo de propagação até a borda. + `keyCount`: o número total de chaves no KVS após a última sincronização da origem. **Exemplo de resposta** ``` {keyCount:3,creationDateTime:2023-11-30T23:07:55.765Z,lastUpdatedDateTime:2023-12-15T03:57:52.411Z} ``` # 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 instruçã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](functions-javascript-runtime-20.md). **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](lambda-at-the-edge.md). ## 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](private-content-vpc-origins.md). 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. **hostHeader (opcional, para origens personalizadas não S3)** O cabeçalho do host a ser usado ao fazer a solicitação à origem. Se não for fornecido, será usado o valor do parâmetro domainName. Se nem o cabeçalho do host nem o parâmetro do nome de domínio forem fornecidos, será usado o nome de domínio da origem atribuída ou o cabeçalho do host da solicitação recebida se a política de encaminhamento à origem (FTO) incluir o host. O cabeçalho do host não pode incluir dois-pontos (`:`) e não pode ser um endereço IP. O cabeçalho do host pode ter até 253 caracteres. **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](add-origin-custom-headers.md#add-origin-custom-headers-denylist) e [Restrições das funções de borda](edge-functions-restrictions.md). 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](origin-shield.md). 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](origin-shield.md#choose-origin-shield-region). **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](private-content-restricting-access-to-origin.md). **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](private-content-restricting-access-to-s3.md#oac-advanced-settings-s3). 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](controlling-origin-requests.md). **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. A menos que seja especificado, esses tempos limite suportam origens personalizadas e origens do Amazon S3. **readTimeout (opcional)** O `readTimeout` aplica-se a ambos os valores a seguir: + 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 120 segundos. Para obter mais informações, consulte [Tempo limite de resposta](DownloadDistValuesOrigin.md#DownloadDistValuesOriginResponseTimeout). **responseCompletionTimeout (opcional)** O tempo (em segundos) em que uma solicitação do CloudFront para a origem pode permanecer aberta e aguardar uma resposta. Se a resposta completa não for recebida da origem até esse momento, o CloudFront encerrará a conexão. O valor para `responseCompletionTimeout` deve ser igual a ou maior que o valor especificado para `readTimeout`. Para obter mais informações, consulte [Tempo limite de conclusão da resposta](DownloadDistValuesOrigin.md#response-completion-timeout). **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.) A `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 120 segundos. Para obter mais informações, consulte [Tempo limite de keep alive (somente origens de VPC e personalizadas)](DownloadDistValuesOrigin.md#DownloadDistValuesOriginKeepaliveTimeout). **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](DownloadDistValuesOrigin.md#origin-connection-timeout). **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](DownloadDistValuesOrigin.md#DownloadDistValuesOriginSSLProtocols). **ipAddressType (opcional)** Especifica o tipo de endereço IP que o CloudFront usa para se conectar à origem. Os valores válidos são `ipv4`, `ipv6` e `dualstack`. Só é possível alterar o `ipAddressType` quando a propriedade `domainName` também está sendo alterada. **sni (opcional, para origens personalizadas não S3)** A Indicação de Nome de Servidor (SNI) é uma extensão do protocolo Transport Layer Security (TLS) por meio da qual um cliente indica a qual nome de host está tentando se conectar no início do processo de handshake do TLS. Esse valor deve corresponder a um nome comum em um certificado TLS no servidor de origem. Do contrário, o servidor de origem pode gerar um erro. Se não for fornecido, será usado o valor do parâmetro `hostHeader`. Se o cabeçalho do host não for fornecido, será usado o valor do parâmetro `domainName`. Se nem o cabeçalho do host nem o parâmetro do nome de domínio forem fornecidos, será usado o nome de domínio da origem atribuída ou o cabeçalho do host da solicitação recebida se a política de encaminhamento à origem (FTO) incluir o host. A SNI não pode incluir dois-pontos (`:`) e não pode ser um endereço IP. A SNI pode ter até 253 caracteres. **allowedCertificateNames (opcional, para origens personalizadas não S3)** É possível incluir uma lista de nomes de certificados válidos a serem usados pelo CloudFront para validar a correspondência de domínio do certificado TLS do servidor de origem durante o handshake do TLS com o servidor de origem. Esse campo requer uma matriz de nomes de domínio válidos e pode incluir domínios curinga, como `*.example.com`. É possível especificar até vinte nomes de certificados permitidos. O nome de cada certificado pode ter até 64 caracteres. **Example – 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": {} }); ``` **Example – 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" } }); ``` **Example – 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" }); ``` **Example : atualizar o cabeçalho do host, a SNI e o nome dos certificados permitidos** Na maioria dos casos de uso, não será necessário usar esse tipo de modificação nas solicitações encaminhadas à sua origem. Esses parâmetros não devem ser usados, a menos que você entenda o impacto de alterar esses valores. O exemplo a seguir altera o nome de domínio, o cabeçalho do host, a SNI e os certificados permitidos na solicitação para a origem. ``` cf.updateRequestOrigin({ "domainName": "www.example.com", "hostHeader": "test.example.com", "sni": "test.example.net", "allowedCertificateNames": ["*.example.com", "*.example.net"], }); ``` ## 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.](private-content-vpc-origins.md). **Observações** A função `selectRequestOriginById()` não pode selecionar uma origem que tenha a TLS mútua (origem) habilitada. A tentativa de selecionar uma origem com a TLS mútua (origem) habilitada por meio dessa função gera um erro de validação. Se seu caso de uso exigir seleção dinâmica de origem com TLS mútua (origem), use `updateRequestOrigin()` em vez disso, para garantir que todas as origens de destino usem o mesmo certificado de cliente. **Solicitação** ``` cf.selectRequestOriginById(origin_id, {origin_overrides}) ``` No exemplo anterior, `origin_id` é uma string que aponta para o nome de uma origem na distribuição que está executando a função. O parâmetro `origin_overrides `pode conter o seguinte: **hostHeader (opcional, para origens personalizadas não S3)** O cabeçalho do host a ser usado ao fazer a solicitação à origem. Se não for fornecido, será usado o valor do parâmetro `domainName`. Se nem o cabeçalho do host nem o parâmetro do nome de domínio forem fornecidos, será usado o nome de domínio da origem atribuída ou o cabeçalho do host da solicitação recebida se a política de encaminhamento à origem (FTO) incluir o host. O cabeçalho do host não pode incluir dois-pontos (`:`) e não pode ser um endereço IP. O cabeçalho do host pode ter até 253 caracteres. **sni (opcional, para origens personalizadas não S3)** A Indicação de Nome de Servidor (SNI) é uma extensão do protocolo Transport Layer Security (TLS) por meio da qual um cliente indica a qual nome de host está tentando se conectar no início do processo de handshake do TLS. Esse valor deve corresponder a um nome comum em um certificado TLS no servidor de origem. Do contrário, o servidor de origem pode gerar um erro. Se não for fornecido, será usado o valor do parâmetro `hostHeader`. Se o cabeçalho do host não for fornecido, será usado o valor do parâmetro `domainName`. Se nem o cabeçalho do host nem o parâmetro do nome de domínio forem fornecidos, será usado o nome de domínio da origem atribuída ou o cabeçalho do host da solicitação recebida se a política de encaminhamento à origem (FTO) incluir o host. A SNI não pode incluir dois-pontos (`:`) e não pode ser um endereço IP. A SNI pode ter até 253 caracteres. **allowedCertificateNames (opcional, para origens personalizadas não S3)** É possível incluir uma lista de nomes de certificados válidos a serem usados pelo CloudFront para validar a correspondência de domínio do certificado TLS do servidor de origem durante o handshake do TLS com o servidor de origem. Esse campo requer uma matriz de nomes de domínio válidos e pode incluir domínios curinga, como `*.example.com`. É possível especificar até vinte nomes de certificados permitidos. O nome de cada certificado pode ter até 64 caracteres. **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. **Example – 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"); ``` **Example – 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"); ``` **Example : selecionar a origem da solicitação do Application Load Balancer e substituir o cabeçalho do host** Como no exemplo anterior, 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. No entanto, este exemplo substitui o valor do cabeçalho do host usando `origin_overrides`. ``` cf.overrideRequestOrigin("myALB-prod",{ "hostHeader" : "test.example.com" }); ``` ## Método createRequestOriginGroup() Use `createRequestOriginGroup()` para definir duas origens a serem usadas como um [grupo de origens](high_availability_origin_failover.md#concept_origin_groups.creating) 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.](private-content-vpc-origins.md). **Observações** A função `createRequestOriginGroup()` não permite a criação de grupos de origens que incluam origens com a TLS mútua (origem) habilitada. Grupos de origens que incluem origens com TLS mútua (origem) não podem ser criados dinamicamente por meio do CloudFront Functions. Se você precisar de recursos de failover de origem com TLS mútua (origem), configure grupos de origens diretamente nas configurações de distribuição do CloudFront em vez de criá-los dinamicamente em funções. ### 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. **originOverrides (opcional)** Algumas configurações avançadas podem ser substituídas usando o parâmetro `{origin_overrides}`. A chave `origin overrides` pode conter os seguintes valores: **hostHeader (opcional, para origens personalizadas não S3)** O cabeçalho do host a ser usado ao fazer a solicitação à origem. Se não for fornecido, será usado o valor do parâmetro `domainName`. Se nem o cabeçalho do host nem o parâmetro do nome de domínio forem fornecidos, será usado o nome de domínio da origem atribuída ou o cabeçalho do host da solicitação recebida se a política de encaminhamento à origem (FTO) incluir o host. O cabeçalho do host não pode incluir dois-pontos (`:`) e não pode ser um endereço IP. O cabeçalho do host pode ter até 253 caracteres. **sni (opcional, para origens personalizadas não S3)** A Indicação de Nome de Servidor (SNI) é uma extensão do protocolo Transport Layer Security (TLS) por meio da qual um cliente indica a qual nome de host está tentando se conectar no início do processo de handshake do TLS. Esse valor deve corresponder a um nome comum em um certificado TLS no servidor de origem. Do contrário, o servidor de origem pode gerar um erro. Se não for fornecido, será usado o valor do parâmetro `hostHeader`. Se o cabeçalho do host não for fornecido, será usado o valor do parâmetro `domainName`. Se nem o cabeçalho do host nem o parâmetro do nome de domínio forem fornecidos, será usado o nome de domínio da origem atribuída ou o cabeçalho do host da solicitação recebida se a política de encaminhamento à origem (FTO) incluir o host. A SNI não pode incluir dois-pontos (`:`) e não pode ser um endereço IP. A SNI pode ter até 253 caracteres. **allowedCertificateNames (opcional, para origens personalizadas não S3)** É possível incluir uma lista de nomes de certificados válidos a serem usados pelo CloudFront para validar a correspondência de domínio do certificado TLS do servidor de origem durante o handshake do TLS com o servidor de origem. Esse campo requer uma matriz de nomes de domínio válidos e pode incluir domínios curinga, como `*.example.com`. É possível especificar até vinte nomes de certificados permitidos. O nome de cada certificado pode ter até 64 caracteres. **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. **Example : 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. Opcionalmente, é possível usar `originOverrides` para substituir as configurações de `sni`, `hostHeader` e `allowedCertificateNames` do grupo de origem. ``` import cf from 'cloudfront'; function handler(event) { cf.createRequestOriginGroup({ "originIds": [ { "originId": "origin-1", "originOverrides": { "hostHeader": "hostHeader.example.com", "sni": "sni.example.com", "allowedCertificateNames": ["cert1.example.com", "cert2.example.com", "cert3.example.com"] } }, { "originId": "origin-2", "originOverrides": { "hostHeader": "hostHeader2.example.com", "sni": "sni2.example.com", "allowedCertificateNames": ["cert4.example.com", "cert5.example.com"] } } ], "failoverCriteria": { "statusCodes": [500] } }); event.request.headers['x-hookx'] = { value: 'origin-overrides' }; return event.request; } ``` # Métodos auxiliares para propriedades do CloudFront SaaS Manager Use as funções auxiliares do CloudFront SaaS Manager a seguir para recuperar valores referentes às suas distribuições multilocatário na função que você criar. Para usar exemplos nessa página, é necessário criar primeiro uma função do CloudFront usando o runtime 2.0 do JavaScript. Para obter mais informações, [Recursos de runtime 2.0 do JavaScript para CloudFront Functions](functions-javascript-runtime-20.md). **Topics** + [ ## Grupos de conexões ](#connection-groups-helper-function) + [ ## Locatários da distribuição ](#distribution-tenants-helper-functions) ## Grupos de conexões O grupo de conexões associado aos locatários da distribuição tem um nome de domínio. Para obter esse valor, use o campo `endpoint` do subobjeto `context` do objeto do evento. **Solicitação** ``` const value = event.context.endpoint; ``` **Resposta** A resposta é uma `string` que contém o nome de domínio do grupo de conexões, como d111111abcdef8.cloudfront.net. O campo `endpoint` é exibido somente quando a função é invocada para uma distribuição multilocatário com um grupo de conexões associado. Para obter mais informações, consulte [Objeto de contexto](functions-event-structure.md#functions-event-structure-context). ## Locatários da distribuição O CloudFront Functions tem um módulo que oferece acesso a valores específicos de locatários da distribuição. Para usar esse módulo, inclua a seguinte instrução na primeira linha do código da função: ``` import cf from 'cloudfront'; ``` Você pode usar os exemplos a seguir somente na função `handler`, tanto diretamente quanto por meio de qualquer função de chamada aninhada. ### `distributionTenant.id`Campo Use esse campo para obter o valor do ID do locatário da distribuição. **Solicitação** ``` const value = cf.distributionTenant.id; ``` **Resposta** A resposta é uma `string` que contém o ID do locatário da distribuição, como `dt_1a2b3c4d5e6f7`. **Tratamento de erros** Se a função for invocada para uma distribuição padrão, ao especificar o campo `distributionTenant.id`, o erro de tipo `distributionTenant module is not available` será exibido. Para lidar com esse caso de uso, é possível adicionar um bloco `try` e `catch` ao seu código. ### Método `distributionTenant.parameters.get()` Use esse método para retornar o valor dos nomes de parâmetro de locatários da distribuição que você especificou. ``` distributionTenant.parameters.get("key"); ``` `key`: o nome do parâmetro de locatário da distribuição para o qual você deseja buscar o valor. **Solicitação ** ``` const value = distributionTenant.parameters.get("key"); ``` **Resposta** A resposta é uma `string` que contém o valor do parâmetro do locatário da distribuição. Por exemplo, se o nome da chave for `TenantPath`, o valor desse parâmetro poderá ser `tenant1`. **Tratamento de erros** Você poderá receber os seguintes erros: + Se sua função for invocada para uma distribuição padrão, o método `distributionTenant.parameters.get()` exibirá o erro de tipo `distributionTenant module is not available`. + O erro `DistributionTenantParameterKeyNotFound` é exibido quando o parâmetro do locatário da distribuição que você especificou não existe. Para gerenciar esses casos de uso, é possível adicionar um bloco `try` e `catch` ao código. # Utilizar async e await As funções do JavaScript runtime 2.0 do CloudFront Functions oferecem as sintaxes `async` e `await` para lidar com objetos `Promise`. Promises representam resultados atrasados que podem ser acessados por meio da palavra-chave `await` nas funções marcadas como `async`. Várias novas funções do WebCrypto usam Promises. Para obter mais informações sobre objetos `Promise`, consulte [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). **nota** É necessário usar o JavaScript runtime 2.0 para os exemplos de código a seguir. `await` pode ser usado apenas dentro de funções `async`. Encerramentos e argumentos `async` não são compatíveis. ``` async function answer() { return 42; } // Note: async, await can be used only inside an async function. async arguments and closures are not supported. async function handler(event) { // var answer_value = answer(); // returns Promise, not a 42 value let answer_value = await answer(); // resolves Promise, 42 console.log("Answer"+answer_value); event.request.headers['answer'] = { value : ""+answer_value }; return event.request; } ``` O exemplo de código JavaScript a seguir mostra como visualizar Promises com o método de cadeia `then`. É possível usar `catch` para visualizar erros. **Atenção** O uso de combinadores de promessa (por exemplo, `Promise.all` e `Promise.any`) e métodos de cadeia de promessa (por exemplo, `then` e `catch`) pode exigir alto uso de memória da função. Se sua função exceder a cota [máxima de memória da função](cloudfront-limits.md#limits-functions), ela não será executada. Para evitar esse erro, recomendamos usar a sintaxe `await` em vez dos métodos `promise`. ``` async function answer() { return 42; } async function squared_answer() { return answer().then(value => value * value) } // Note: async, await can be used only inside an async function. async arguments and closures are not supported. async function handler(event) { // var answer_value = answer(); // returns Promise, not a 42 value let answer_value = await squared_answer(); // resolves Promise, 42 console.log("Answer"+answer_value); event.request.headers['answer'] = { value : ""+answer_value }; return event.request; } ``` # Suporte a CWT para o CloudFront Functions Esta seção apresenta detalhes sobre o suporte a CBOR Web Tokens (CWT) no CloudFront Functions, o que permite autenticação e autorização seguras baseadas em tokens nos locais da borda do CloudFront. Esse suporte é fornecido como um módulo, acessível em sua função do CloudFront. Para usar esse módulo, crie uma função do CloudFront usando o Runtime 2.0 do JavaScript e inclua a seguinte instrução na primeira linha do código da função: ``` import cf from 'cloudfront'; ``` Os métodos associados a este módulo podem ser acessados por meio de cf.cwt.\$1 (em que \$1 é um curinga representando as diferentes funções presentes no módulo): ``` cf.cwt.* ``` Para ter mais informações, consulte [Recursos de runtime 2.0 do JavaScript para CloudFront Functions](functions-javascript-runtime-20.md). No momento, o módulo aceita apenas a estrutura MAC0 com o algoritmo HS256 (HMAC-SHA256), com um limite de 1 KB para o tamanho máximo do token. ## Estrutura do tokens Esta seção aborda a estrutura de tokens que é esperada pelo módulo CWT. O módulo espera que o token seja corretamente marcado e identificável (p. ex., COSE MAC0). Além disso, para a estrutura de tokens, o módulo segue os padrões definidos pela [CBOR Object Signing and Encryption (COSE) [RFC 8152](https://datatracker.ietf.org/doc/html/rfc8152)]. ``` ( // CWT Tag (Tag value: 61) --- optional ( // COSE MAC0 Structure Tag (Tag value: 17) --- required [ protectedHeaders, unprotectedHeaders, payload, tag, ] ) ) ``` **Example : CWT usando a estrutura COSE MAC0** ``` 61( // CWT tag 17( // COSE_MAC0 tag [ { // Protected Headers 1: 4 // algorithm : HMAC-256-64 }, { // Unprotected Headers 4: h'53796d6d6574726963323536' // kid : Symmetric key id }, { // Payload 1: "https://iss.example.com", // iss 2: "exampleUser", // sub 3: "https://aud.example.com", // aud 4: 1444064944, // exp 5: 1443944944, // nbf 6: 1443944944, // iat }, h'093101ef6d789200' // tag ] ) ) ``` A tag CWT é opcional ao gerar tokens. No entanto, a tag da estrutura COSE é necessária. ## Método validateToken() A função decodifica e valida um CWT usando a chave especificada. Se o comando tiver êxito, ela exibirá um CWT decodificado. Do contrário, gerará um erro. Observe que essa função não valida o conjunto de instruções. ### Solicitação ``` cf.cwt.validateToken(token, handlerContext{key}) ```Parâmetros **token (obrigatório)** Token codificado para validação. Deve ser um buffer em JavaScript. **handlerContext (obrigatório)** Um objeto JavaScript que armazena o contexto para a chamada validateToken. No momento, somente a propriedade key é permitida. **key (obrigatório)** Chave secreta para computação de resumo de mensagens. Pode ser fornecido como uma string ou como um buffer em JavaScript. ### Resposta Quando o método `validateToken()` exibe um token validado com êxito, a resposta da função é um `CWTObject` no formato a seguir. Depois de decodificadas, todas as chaves de solicitação são representadas como strings. ``` CWTObject { protectedHeaders, unprotectedHeaders, payload } ``` ### Exemplo: validar o token com kid enviado como parte do token Este exemplo demonstra a validação de um CWT, em que kid (key ID) é extraído do cabeçalho. Em seguida, o kid é encaminhado ao KeyValueStore do CloudFront Functions para buscar a chave secreta usada para validar o token. ``` import cf from 'cloudfront' const CwtClaims = { iss: 1, aud: 3, exp: 4 } async function handler(event) { try { let request = event.request; let encodedToken = request.headers['x-cwt-token'].value; let kid = request.headers['x-cwt-kid'].value; // Retrieve the secret key from the kvs let secretKey = await cf.kvs().get(kid); // Now you can use the secretKey to decode & validate the token. let tokenBuffer = Buffer.from(encodedToken, 'base64url'); let handlerContext = { key: secretKey, } try { let cwtObj = cf.cwt.validateToken(tokenBuffer, handlerContext); // Check if token is expired const currentTime = Math.floor(Date.now() / 1000); // Current time in seconds if (cwtObj[CwtClaims.exp] && cwtObj[CwtClaims.exp] < currentTime) { return { statusCode: 401, statusDescription: 'Token expired' }; } } catch (error) { return { statusCode: 401, statusDescription: 'Invalid token' }; } } catch (error) { return { statusCode: 402, statusDescription: 'Token processing failed' }; } return request; } ``` ## Método generateToken() Essa função gera um novo CWT usando a carga útil e as configurações de contexto fornecidas. ### Solicitação ``` cf.cwt.generateToken(generatorContext, payload) ```Parâmetros **generatorContext (obrigatório)** Esse é um objeto JavaScript usado como contexto para gerar o token e contém os seguintes pares de chave-valor: **cwtTag (opcional)** Esse valor é um booliano que, se for `true`, especifica que `cwtTag` deve ser adicionado. **coseTag (obrigatório)** Especifica o tipo de tag COSE. No momento, oferece suporte apenas a `MAC0`. **key (obrigatório)** Chave secreta para computar resumo de mensagens. Esse valor pode ser uma string ou `Buffer` em JavaScript. **payload (obrigatório)** Carga útil do token para codificação. A carga útil deve estar no seguinte formato `CWTObject`. ### Resposta Exibe um buffer em JavaScript contendo o token codificado. **Example : gerar um CWT** ``` import cf from 'cloudfront'; const CwtClaims = { iss: 1, sub: 2, exp: 4 }; const CatClaims = { catu: 401, catnip: 402, catm: 403, catr: 404 }; const Catu = { host: 1, path: 2, ext: 3 }; const CatuMatchTypes = { prefix_match: 1, suffix_match: 2, exact_match: 3 }; const Catr = { renewal_method: 1, next_renewal_time: 2, max_uses: 3 }; async function handler(event) { try { const response = { statusCode: 200, statusDescription: 'OK', headers: {} }; const commonAccessToken = { protected: { 1: "5", }, unprotected: {}, payload: { [CwtClaims.iss]: "cloudfront-documentation", [CwtClaims.sub]: "cwt-support-on-cloudfront-functions", [CwtClaims.exp]: 1740000000, [CatClaims.catu]: { [Catu.host]: { [CatuMatchTypes.suffix_match]: ".cloudfront.net" }, [Catu.path]: { [CatuMatchTypes.prefix_match]: "/media/live-stream/cf-4k/" }, [Catu.ext]: { [CatuMatchTypes.exact_match]: [ ".m3u8", ".ts", ".mpd" ] } }, [CatClaims.catnip]: [ "[IP_ADDRESS]", "[IP_ADDRESS]" ], [CatClaims.catm]: [ "GET", "HEAD" ], [CatClaims.catr]: { [Catr.renewal_method]: "header_renewal", [Catr.next_renewal_time]: 1750000000, [Catr.max_uses]: 5 } } }; if (!request.headers['x-cwt-kid']) { throw new Error('Missing x-cwt-kid header'); } const kid = request.headers['x-cwt-kid'].value; const secretKey = await cf.kvs().get(kid); if (!secretKey) { throw new Error('Secret key not found for provided kid'); } try { const genContext = { cwtTag: true, coseTag: "MAC0", key: secretKey }; const tokenBuffer = cf.cwt.generateToken(commonAccessToken, genContext); response.headers['x-generated-cwt-token'] = { value: tokenBuffer.toString('base64url') }; return response; } catch (tokenError) { return { statusCode: 401, statusDescription: 'Could not generate the token' }; } } catch (error) { return { statusCode: 402, statusDescription: 'Token processing failed' }; } } ``` **Example : atualizar o token com base em alguma lógica** ``` import cf from 'cloudfront' const CwtClaims = { iss: 1, aud: 3, exp: 4 } async function handler(event) { try { let request = event.request; let encodedToken = request.headers['x-cwt-token'].value; let kid = request.headers['x-cwt-kid'].value; let secretKey = await cf.kvs().get(kid); // Retrieve the secret key from the kvs // Now you can use the secretKey to decode & validate the token. let tokenBuffer = Buffer.from(encodedToken, 'base64url'); let handlerContext = { key: secretKey, } try { let cwtJSON = cf.cwt.validateToken(tokenBuffer, handlerContext); // Check if token is expired const currentTime = Math.floor(Date.now() / 1000); // Current time in seconds if (cwtJSON[CwtClaims.exp] && cwtJSON[CwtClaims.exp] < currentTime) { // We can regnerate the token and add 8 hours to the expiry time cwtJSON[CwtClaims.exp] = Math.floor(Date.now() / 1000) + (8 * 60 * 60); let genContext = { coseTag: "MAC0", key: secretKey } let newTokenBuffer = cf.cwt.generateToken(cwtJSON, genContext); request.headers['x-cwt-regenerated-token'] = newTokenBuffer.toString('base64url'); } } catch (error) { return { statusCode: 401, statusDescription: 'Invalid token' }; } } catch (error) { return { statusCode: 402, statusDescription: 'Token processing failed' }; } return request; } ``` # métodos auxiliares gerais Esta página apresenta outros métodos auxiliares dentro do CloudFront Functions. Para usar esses métodos, crie uma função do CloudFront usando o Runtime 2.0 do JavaScript. ``` import cf from 'cloudfront'; ``` Para ter mais informações, consulte [Recursos de runtime 2.0 do JavaScript para CloudFront Functions](functions-javascript-runtime-20.md). ## `edgeLocation`Metadados do Esse método requer o uso do módulo `cloudfront`. **nota** Somente é possível usar esse método para funções de solicitação de visualizador. Para funções de resposta ao visualizador, esse método está vazio. Use esse objeto JavaScript para obter o código do aeroporto do local da borda, a região do [cache de borda regional](HowCloudFrontWorks.md#CloudFrontRegionaledgecaches) que deve ser usada ou o endereço IP do servidor do CloudFront usado para processar a solicitação. Esses metadados estão disponíveis somente no acionador de eventos de solicitação de visualizador. ``` cf.edgeLocation = { name: SEA serverIp: 1.2.3.4 region: us-west-2 } ``` O objeto `cf.edgeLocation` contém os seguintes campos: **name** O [código da IATA](https://en.wikipedia.org/wiki/IATA_airport_code) de três letras do local da borda que processou a solicitação. **serverIp** O endereço IPv4 ou IPv6 do servidor que processou a solicitação. **region** O cache de borda regional (REC) do CloudFront que a solicitação deve usar se não houver acerto no cache. Esse valor não é atualizado caso o REC a ser usado não esteja disponível e um REC de backup seja usado para a solicitação. Isso não inclui o local do Origin Shield que está sendo usado, exceto nos casos em que o REC primário e o Origin Shield estão no mesmo local. **nota** O CloudFront Functions não é invocado pela segunda vez quando o CloudFront está configurado para usar o failover de origem. Para ter mais informações, consulte [Otimizar a alta disponibilidade com o failover de origem do CloudFront](high_availability_origin_failover.md). ## Método `rawQueryString()` Esse método não requer o módulo `cloudFront`. Use o método `rawQueryString()` para recuperar a string de consulta não analisada e não alterada como uma string. **Solicitação** ``` function handler(event) { var request = event.request; const qs = request.rawQueryString(); } ``` **Resposta** Exibe a string de consulta completa da solicitação de entrada como um valor de string sem o `?` inicial. + Se não houver uma string de consulta, mas houver um `?`, as funções exibirão uma string vazia. + Se não houver uma string de consulta e houver um `?`, a função exibirá `undefined`. **Caso 1: string de consulta completa exibida (sem o `?` inicial)** URL da solicitação de entrada: `https://example.com/page?name=John&age=25&city=Boston`. `rawQueryString()` exibe: `"name=John&age=25&city=Boston"`. **Caso 2: string vazia exibida (quando há um `?`, mas sem parâmetros)** URL da solicitação de entrada: `https://example.com/page?`. `rawQueryString()` exibe: `""`. **Caso 3: `undefined` exibido (sem string de consulta e nenhum `?`)** URL da solicitação de entrada: `https://example.com/page`. `rawQueryString()` exibe: `undefined`. # Criar funções Você deve criar uma função em dois estágios: 1. Crie o código da função como JavaScript. É possível usar o exemplo padrão do console do CloudFront ou crie seu próprio. Para obter mais informações, consulte os tópicos a seguir. + [Escrever código de função](writing-function-code.md) + [Estrutura de eventos do CloudFront Functions](functions-event-structure.md) + [Exemplos do CloudFront Functions para o CloudFront](service_code_examples_cloudfront_functions_examples.md) 1. Use o CloudFront para criar a função e incluir o código. O código existe dentro da função (não como referência). ------ #### [ Console ] **Como criar uma função do** 1. Faça login no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) e selecione a página **Funções**. 1. Escolha a opção **Criar função**. 1. Insira um nome de função exclusivo na Conta da AWS, selecione a versão do JavaScript e escolha **Continuar**. A página de detalhes da nova função é exibida. **nota** Para usar [pares de chave-valor](kvs-with-functions.md) na função, será necessário selecionar JavaScript runtime 2.0. 1. Na seção **Código da função**, selecione a guia **Criar** e insira o código da função. O exemplo de código incluído na guia **Criar** ilustra a sintaxe básica do código da função. 1. Escolha **Salvar alterações**. 1. Se o código da função usar pares de chave–valor, será necessário associar um armazenamento de valores de chave. É possível associar o armazenamento de chave-valor durante a criação inicial da função. Ou é possível associá-lo posteriormente, [atualizando a função](update-function.md). Para associar um armazenamento de chave-valor agora, siga estas etapas: + Acesse a seção **Associar KeyValueStore** e selecione **Associar KeyValueStore existente**. + Selecione o armazenamento de chave-valor que contém os pares de chave-valor na função e escolha **Associar KeyValueStore**. O CloudFront associa imediatamente o armazenamento à função. Não é necessário salvar a função. ------ #### [ CLI ] Se você usa a CLI, normalmente primeiro cria o código da função em um arquivo e, depois, cria a função com a AWS CLI. **Como criar uma função do** 1. Crie o código da função em um arquivo e armazene-o em um diretório ao qual o computador possa se conectar. 1. Execute o comando conforme mostrado no exemplo. Este exemplo usa a notação `fileb://` para transmitir o arquivo. Ele também inclui quebras de linha para tornar o comando mais legível. ``` aws cloudfront create-function \ --name MaxAge \ --function-config '{"Comment":"Max Age 2 years","Runtime":"cloudfront-js-2.0","KeyValueStoreAssociations":{"Quantity":1,"Items":[{"KeyValueStoreARN":"arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"}]}}' \ --function-code fileb://function-max-age-v1.js ``` **Observações** `Runtime`: a versão do JavaScript. Para usar [pares de chave-valor](kvs-with-functions.md) na função, é necessário especificar a versão 2.0. `KeyValueStoreAssociations`: se a função usar pares de chave-valor, será possível associar o armazenamento de chave-valor durante a criação inicial da função. Ou é possível associá-lo posteriormente, usando `update-function`. A `Quantity` é sempre `1` porque cada função pode ter apenas um armazenamento de chave-valor associado a ela. Quando o comando é bem-sucedido, a saída é semelhante à seguinte: ``` ETag: ETVABCEXAMPLE FunctionSummary: FunctionConfig: Comment: Max Age 2 years Runtime: cloudfront-js-2.0 KeyValueStoreAssociations= \ {Quantity=1, \ Items=[{KeyValueStoreARN='arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111'}]} \ FunctionMetadata: CreatedTime: '2021-04-18T20:38:56.915000+00:00' FunctionARN: arn:aws:cloudfront::111122223333:function/MaxAge LastModifiedTime: '2023-11-19T20:38:56.915000+00:00' Stage: DEVELOPMENT Name: MaxAge Status: UNPUBLISHED Location: https://cloudfront.amazonaws.com/2020-05-31/function/arn:aws:cloudfront:::function/MaxAge ``` A maioria das informações é repetida a partir da solicitação. Outras informações são adicionadas pelo CloudFront. **Observações** `ETag`: esse valor muda sempre que você modifica o armazenamento de valores de chave. Use esse valor e o nome da função para referenciar a função futuramente. Sempre use a `ETag` atual. `FunctionARN`: o ARN da função do CloudFront. 111122223333: a Conta da AWS. `Stage`: o estágio da função (`LIVE` ou `DEVELOPMENT`). `Status`: o status da função (`PUBLISHED` ou `UNPUBLISHED`). ------ Depois de criar a função, ela é adicionada ao estágio `DEVELOPMENT`. Recomendamos [testar sua função](test-function.md) antes de [publicá-la](publish-function.md). Depois de publicar a função, ela muda para o estágio `LIVE`. # Testar funções Antes de implantar a função no estágio ativo (produção), é possível testar a função para verificar se ela funciona conforme o esperado. Para testar uma função, especifique um *objeto de evento* que represente uma solicitação ou uma resposta HTTP que a distribuição do CloudFront pode receber em produção. O CloudFront Functions faz o seguinte: 1. Executa a função usando o objeto de evento fornecido como entrada. 1. Retorna o resultado da função (o objeto de evento modificado), bem como os logs de função ou as mensagens de erro e a *utilização de computação* da função. Para obter mais informações sobre as métricas de utilização de computação, consulte [Noções básicas de utilização de computação](#compute-utilization). **nota** Quando você testa uma função, o CloudFront valida apenas os erros de execução da função. O CloudFront não valida se a solicitação fluirá com sucesso depois de publicada. Por exemplo, se sua função excluir um cabeçalho obrigatório, o teste será bem-sucedido porque não há um problema com o código. Entretanto, se você publicar a função e associá-la a uma distribuição, a função falhará quando uma solicitação for feita por meio do CloudFront. **Contents** + [ ## Configurar o objeto de evento ](#test-function-create-event) + [ ## Testar a função ](#test-function-step-test) + [ ## Noções básicas de utilização de computação ](#compute-utilization) ## Configurar o objeto de evento Antes de testar uma função, é necessário configurar o objeto de evento com o qual testá-la. Há várias opções. **Opção 1: configurar um objeto de evento sem salvá-lo** É possível configurar um objeto de evento no editor visual no console do CloudFront e não salvá-lo. É possível usar esse objeto de evento para testar a função no console do CloudFront, mesmo que ele não esteja salvo. **Opção 2: criar um objeto de evento no editor visual** É possível configurar um objeto de evento no editor visual no console do CloudFront e não salvá-lo. É possível criar dez objetos de evento para cada função para poder, por exemplo, testar diferentes entradas possíveis. Ao criar o objeto de evento dessa forma, é possível usar o objeto de evento para testar a função no console do CloudFront. Não é possível usá-lo para testar a função usando uma API ou um SDK da AWS. **Opção 3: criar um objeto de evento usando um editor de texto** É possível usar um editor de texto para criar um objeto de evento no formato JSON. Para obter informações sobre a estrutura de um objeto de evento, consulte [Estrutura de eventos](functions-event-structure.md). É possível usar esse objeto de evento para testar a função usando a CLI. Mas não é possível usá-lo para testar a função no console do CloudFront. **Como criar um objeto de evento (opção 1 ou 2)** 1. Faça login no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) e selecione a página **Funções**. Escolha a função que você deseja testar. 1. Na página de detalhes da função, selecione a guia **Testar**. 1. Em **Tipo de evento**, selecione uma das seguintes opções: + Selecione **Solicitação do visualizador** se a função modificar uma solicitação HTTP ou gerar uma resposta com base na solicitação. A seção **Solicitação** é exibida. + Selecione **Resposta do visualizador**. As seções **Solicitação** e **Resposta** são exibidas. 1. Preencha todos os campos a serem incluídos no evento. É possível selecionar **Editar JSON** para visualizar o JSON bruto. 1. (Opcional) Para salvar o evento, escolha **Salvar** e, em **Salvar evento de teste**, insira um nome e escolha **Salvar**. Também é possível selecionar **Editar JSON**, copiar o JSON bruto e salvá-lo no próprio arquivo, fora do CloudFront. **Como criar um objeto de evento (opção 3)** Crie o objeto de evento usando um editor de texto. Armazene o arquivo em um diretório ao qual o computador possa se conectar. Siga estas diretrizes: + Omita os campos `distributionDomainName`, `distributionId` e `requestId`. + Os nomes de cabeçalhos, os cookies e as strings de consulta devem estar em letras minúsculas. Uma opção para criar um objeto de evento dessa forma é criar um exemplo usando o editor visual. O exemplo deve estar formatado corretamente. Depois, copie o JSON bruto, cole-o em um editor de texto e salve o arquivo. Para ter mais informações sobre a estrutura de um evento, consulte [Estrutura de eventos](functions-event-structure.md). ## Testar a função Você pode testar uma função no console do CloudFront ou com a AWS Command Line Interface (AWS CLI). ------ #### [ Console ] **Para testar a função** 1. Faça login no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) e selecione a página **Funções**. 1. Escolha a função que você deseja testar. 1. Selecione a guia **Testar**. 1. Verifique se o evento correto é exibido. Para sair do evento exibido no momento, selecione outro evento no campo **Selecionar evento de teste**. 1. Escolha **Testar função**. O console mostra a saída da função, incluindo os logs da função e a utilização de computação. ------ #### [ CLI ] É possível testar uma função usando o comando **aws cloudfront test-function**. **Para testar a função** 1. Abra a janela de linha de comando. 1. Execute o comando a seguir no diretório que contém o arquivo especificado. Este exemplo usa a notação `fileb://` para transmitir o arquivo de objeto de evento. Ele também inclui quebras de linha para tornar o comando mais legível. ``` aws cloudfront test-function \ --name MaxAge \ --if-match ETVABCEXAMPLE \ --event-object fileb://event-maxage-test01.json \ --stage DEVELOPMENT ``` **Observações** Você faz referência à função pelo nome e pela ETag (no parâmetro `if-match`). Você faz referência ao objeto de evento pela localização no sistema de arquivos. O estágio pode ser `DEVELOPMENT` ou `LIVE`. Quando o comando é bem-sucedido, a saída é semelhante à seguinte: ``` TestResult: ComputeUtilization: '21' FunctionErrorMessage: '' FunctionExecutionLogs: [] FunctionOutput: '{"response":{"headers":{"cloudfront-functions":{"value":"generated-by-CloudFront-Functions"},"location":{"value":"https://aws.amazon.com/cloudfront/"}},"statusDescription":"Found","cookies":{},"statusCode":302}}' FunctionSummary: FunctionConfig: Comment: MaxAge function Runtime: cloudfront-js-2.0 KeyValueStoreAssociations= \ {Quantity=1, \ Items=[{KeyValueStoreARN='arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111'}]} \ FunctionMetadata: CreatedTime: '2021-04-18T20:38:56.915000+00:00' FunctionARN: arn:aws:cloudfront::111122223333:function/MaxAge LastModifiedTime: '2023-17-20T10:38:57.057000+00:00' Stage: DEVELOPMENT Name: MaxAge Status: UNPUBLISHED ``` ------ **Observações** `FunctionExecutionLogs` contém uma lista de linhas de log que a função escreveu em instruções `console.log()` (se houver). `ComputeUtilization` contém informações sobre como executar a função. Consulte [Noções básicas de utilização de computação](#compute-utilization). `FunctionOutput`O contém o objeto de evento que a função retornou. ## Noções básicas de utilização de computação **Compute utilization** (Utilização de computação) é a quantidade de tempo que a função levou para ser executada como uma porcentagem do tempo máximo permitido. Por exemplo, um valor de 35 significa que a função foi concluída em 35% do tempo máximo permitido. Se uma função exceder continuamente o tempo máximo permitido, o CloudFront limitará a função. A lista a seguir explica a probabilidade de uma função ser limitada com base no valor de utilização da computação. **Valor de utilização de computação:** + **1 – 50** – De 1 a 50: a função está confortavelmente abaixo do tempo máximo permitido e deve funcionar sem controle de utilização. + **51 – 70** – De 51 a 70: a função está próxima do tempo máximo permitido. É aconselhável otimizar o código da função. + **71 – 100** – De 71 a 100: a função está muito próxima ou excede o tempo máximo permitido. É provável que o CloudFront restrinja essa função se você a associar a uma distribuição. # Atualizar funções É possível atualizar uma função a qualquer momento. As alterações são feitas somente na versão da função que está no estágio `DEVELOPMENT`. Para copiar as atualizações do estágio `DEVELOPMENT` em `LIVE`, é necessário [publicar a função](publish-function.md). É possível atualizar o código de uma função no console do CloudFront ou com a AWS Command Line Interface (AWS CLI). ------ #### [ Console ] **Como atualizar um código de função** 1. Faça login no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) e selecione a página **Funções**. Escolha a função a ser atualizada. 1. Escolha **Editar** e faça as seguintes alterações: + Atualize todos os campos na seção **Detalhes**. + Altere ou remova o armazenamento de valores de chave associado. Para obter mais informações sobre armazenamentos de chave-valor, consulte [Amazon CloudFront KeyValueStore](kvs-with-functions.md). + Altere o código da função. Selecione a guia **Criar**, faça alterações e, depois, escolha **Salvar alterações** para salvar as alterações no código. ------ #### [ CLI ] **Para atualizar o código da função** 1. Abra a janela de linha de comando. 1. Execute o comando a seguir. Este exemplo usa a notação `fileb://` para transmitir o arquivo. Ele também inclui quebras de linha para tornar o comando mais legível. ``` aws cloudfront update-function \ --name MaxAge \ --function-config '{"Comment":"Max Age 2 years","Runtime":"cloudfront-js-2.0","KeyValueStoreAssociations":{"Quantity":1,"Items":[{"KeyValueStoreARN":"arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"}]}}' \ --function-code fileb://function-max-age-v1.js \ --if-match ETVABCEXAMPLE ``` **Observações** É possível identificar a função pelo nome e pela ETag (no parâmetro `if-match`). Use a ETag atual. Você pode obter esse valor com a operação de API [DescribeApplication](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeFunction.html). É necessário incluir o `function-code`, mesmo que não deseje alterá-lo. Tenha cuidado com a `function-config`. É necessário transmitir tudo o que deseja manter na configuração. Especificamente, trate o armazenamento de chave-valor da seguinte forma: Para reter a associação do armazenamento de valores de chave existente (se houver), especifique o nome do armazenamento *existente*. Para alterar a associação, especifique o nome do *novo* armazenamento de valores de chave. Para remover a associação, omita o parâmetro `KeyValueStoreAssociations`. Quando o comando é bem-sucedido, a saída é semelhante à seguinte: ``` ETag: ETVXYZEXAMPLE FunctionSummary: FunctionConfig: Comment: Max Age 2 years \ Runtime: cloudfront-js-2.0 \ KeyValueStoreAssociations= \ {Quantity=1, \ Items=[{KeyValueStoreARN='arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111'}]} \ FunctionMetadata: \ CreatedTime: '2021-04-18T20:38:56.915000+00:00' \ FunctionARN: arn:aws:cloudfront::111122223333:function/MaxAge \ LastModifiedTime: '2023-12-19T23:41:15.389000+00:00' \ Stage: DEVELOPMENT \ Name: MaxAge \ Status: UNPUBLISHED ``` ------ A maioria das informações é repetida a partir da solicitação. Outras informações são adicionadas pelo CloudFront. **Observações** `ETag`: esse valor muda sempre que você modifica o armazenamento de valores de chave. `FunctionARN`: o ARN da função do CloudFront. `Stage`: o estágio da função (`LIVE` ou `DEVELOPMENT`). `Status`: o status da função (`PUBLISHED` ou `UNPUBLISHED`). # Publicar as funções Quando você publica a função, ela é copiada do estágio `DEVELOPMENT` para `LIVE`. Se nenhum comportamento de cache estiver associado à função, a publicação dela permitirá associá-la a um comportamento de cache. Você só pode associar comportamentos de cache a funções que estão na etapa `LIVE`. **Importante** Antes de publicar, recomendamos [testar a função](test-function.md). Quando você publicar a função, todos os comportamentos de cache associados a ela começarão automaticamente a usar a cópia recém-publicada assim que as distribuições terminarem de ser implantadas. Você pode publicar uma função no console do CloudFront ou com a AWS CLI. ------ #### [ Console ] **Como publicar uma função** 1. Faça login no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) e selecione a página **Funções**. 1. Escolha a função a ser atualizada. 1. Selecione a guia **Publicar** e, depois, **Publicar função**. Se a função já estiver anexada a um ou mais comportamentos de cache, selecione **Publicar e atualizar**. 1. (Opcional) Para ver as distribuições associadas à função, selecione **Associated CloudFront distributions** (Distribuições associadas do CloudFront) para expandir essa seção. Quando for bem-sucedido, será exibido um banner na parte superior da página que diz ***Nome da função* publicada com êxito**. Você também pode escolher a guia **Build (Criar)** e, em seguida, escolher **Live (Ao vivo)** para ver a versão ao vivo do código de função. ------ #### [ CLI ] **Como publicar uma função** 1. Abra a janela de linha de comando. 1. Execute o seguinte comando **aws cloudfront publish-function**. No exemplo, as quebras de linha são fornecidas para tornar o exemplo mais legível. ``` aws cloudfront publish-function \ --name MaxAge \ --if-match ETVXYZEXAMPLE ``` Quando o comando é bem-sucedido, a saída é semelhante à seguinte: ``` FunctionSummary: FunctionConfig: Comment: Max Age 2 years Runtime: cloudfront-js-2.0 FunctionMetadata: CreatedTime: '2021-04-18T21:24:21.314000+00:00' FunctionARN: arn:aws:cloudfront::111122223333:function/ExampleFunction LastModifiedTime: '2023-12-19T23:41:15.389000+00:00' Stage: LIVE Name: MaxAge Status: UNASSOCIATED ``` ------ # Associar funções a distribuições Para usar uma função com uma distribuição, associe 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. É possível associar uma função a qualquer um dos seguintes itens: + Um comportamento de cache existente. + Um novo comportamento de cache em uma distribuição existente. + Um novo comportamento de cache em uma nova distribuição. 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 executa a função. É possível escolher entre os seguintes tipos de evento: + **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. Não é possível usar tipos de evento voltados para a origem (*solicitação de origem* e *resposta de origem*) com o CloudFront Functions. Em vez disso, você pode usar o Lambda@Edge. Para ter mais informações, consulte [Eventos do CloudFront que podem acionar uma função do Lambda@Edge](lambda-cloudfront-trigger-events.md). **nota** Antes de associar uma função, você deve [publicá-la](publish-function.md) na fase `LIVE`. É possível associar uma função a uma distribuição no console do CloudFront ou à AWS Command Line Interface (AWS CLI). O procedimento a seguir mostra como associar uma função a um comportamento de cache existente. ------ #### [ Console ] **Como associar uma função a um comportamento de cache existente** 1. Faça login no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) e selecione a página **Funções**. 1. Escolha a função que você deseja associar. 1. Na página **Função**, selecione a guia **Publicar**. 1. Selecione a **função Publish** (Publicar). 1. Escolha **Add association**. Na caixa de diálogo exibida, selecione uma distribuição, um tipo de evento e/ou um comportamento de cache. Para o tipo de evento, selecione quando deseja que essa função seja executada: + **Solicitação do visualizador**: execute a função sempre que o CloudFront receber uma solicitação. + **Resposta do visualizador**: execute a função sempre que o CloudFront exibir uma resposta. 1. Para salvar a configuração, selecione **Adicionar associação**. O CloudFront associa a distribuição à função. Aguarde alguns minutos para que a distribuição associada termine a implantação. É selecionar **Visualizar distribuição** na página de detalhes da função para conferir o andamento. ------ #### [ CLI ] **Como associar uma função a um comportamento de cache existente** 1. Abra a janela de linha de comando. 1. Insira o comando a seguir para salvar a configuração da 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. 1. Abra o arquivo chamado `dist-config.yaml` que você criou. Edite o arquivo para fazer as alterações a seguir. 1. Renomeie o campo `ETag` para `IfMatch`, mas não altere o valor do campo. 1. 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 ``` 1. Depois de fazer essas alterações, salve o arquivo. 1. 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 ``` ------ O `Status` da distribuição muda para `InProgress` enquanto a distribuição é reimplantada. Quando a nova configuração de distribuição atingir um local da borda do CloudFront, esse local começará a usar a função associada. Quando a distribuição estiver totalmente implantada, o `Status` mudará de volta para `Deployed`. Isso indica que a função do CloudFront associada está ativa em todos os locais da borda do CloudFront no mundo todo. Normalmente, isso demora alguns minutos. # Amazon CloudFront KeyValueStore O KeyValueStore do CloudFront é um datastore de valor de chave seguro, global e de baixa latência que permite acesso de leitura por meio do [CloudFront Functions](cloudfront-functions.md), viabilizando uma lógica personalizada avançada nos locais da borda do CloudFront. Com o KeyValueStore do CloudFront, você faz atualizações no código da função e nos dados associados a uma função, de modo independente uns dos outros. Essa separação simplifica o código da função e facilita a atualização dos dados sem a necessidade de implantar alterações no código. **nota** Para usar o CloudFront KeyValueStore, a função do CloudFront deve usar o [runtime 2.0 do JavaScript.](functions-javascript-runtime-20.md) Veja a seguir o procedimento geral para usar pares de chave-valor: + Crie armazenamentos de chave-valor e preencha-os com um conjunto de pares de chave-valor. É possível adicionar seus armazenamentos de chave-valor a um bucket do Amazon S3 ou inseri-los manualmente. + Associe os armazenamentos de chave-valor ao CloudFront Functions. + No código da função, use o nome da chave para recuperar o valor associado a ela ou para avaliar se existe uma chave. Consulte mais informações sobre o uso de pares de chave-valor no código da função e sobre métodos auxiliares em [Métodos auxiliares para armazenamentos de chave-valor](functions-custom-methods.md). ## Casos de uso É possível usar pares de chave-valor para os seguintes exemplos: + **Regravações ou redirecionamentos de URL**: o par de chave-valor pode conter os URLs regravados ou os URLs de redirecionamento. + **Testes A/B e sinalizadores de recursos**: é possível criar uma função para realizar experimentos atribuindo uma porcentagem do tráfego a uma versão específica do site. + **Autorização de acesso**: é possível implementar o controle de acesso para permitir ou negar solicitações com base nos critérios definidos e nos dados armazenados no armazenamento de chave-valor. ## Formatos compatíveis de valores É possível armazenar o valor em um par de chave-valor em qualquer um dos seguintes formatos: + String + String codificada por bytes + JSON ## Segurança O CloudFront Functions e todos os dados de armazenamento de chave-valor são tratados com segurança, da seguinte forma: + O CloudFront criptografa cada armazenamento de chave-valor em repouso e em trânsito (ao ler ou gravar no armazenamento de chave-valor) ao chamar as operações da API [KeyValueStore do CloudFront](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_Operations_Amazon_CloudFront_KeyValueStore.html). + Quando a função é executada, o CloudFront descriptografa cada par de chave-valor na memória nos locais da borda do CloudFront. Para começar a usar o KeyValueStore do CloudFront, consulte os tópicos a seguir. **Topics** + [ ## Casos de uso ](#key-value-store-use-cases) + [ ## Formatos compatíveis de valores ](#key-value-store-supported-formats) + [ ## Segurança ](#key-value-store-security) + [ # Trabalhar com o armazenamento de chave-valor ](kvs-with-functions-kvs.md) + [ # Trabalhar com dados de chave-valor ](kvs-with-functions-kvp.md) + Para ter mais informações sobre os conceitos básicos do KeyValueStore do CloudFront, consulte a postagem do blog [Apresentação do KeyValueStore do Amazon CloudFront.](https://aws.amazon.com/blogs/aws/introducing-amazon-cloudfront-keyvaluestore-a-low-latency-datastore-for-cloudfront-functions/)AWS # Trabalhar com o armazenamento de chave-valor É necessário criar um armazenamento de chave-valor para armazenar os pares de chave-valor que você deseja usar no CloudFront Functions. Depois de criar os armazenamentos de chave-valor e adicionar os pares de chave-valor, você pode usar os elementos de chave-valor no código da função do CloudFront. Para começar, consulte os seguintes tópicos: **Topics** + [ # Criar um armazenamento de chave-valor ](kvs-with-functions-create.md) + [ # Associar o armazenamento de chave-valor à função ](kvs-with-functions-associate.md) + [ # Atualizar um armazenamento de chave-valor ](kvs-with-functions-edit.md) + [ # Obter uma referência a um armazenamento de chave-valor ](kvs-with-functions-get-reference.md) + [ # Excluir um armazenamento de chave-valor ](kvs-with-functions-delete.md) + [ # Formato de arquivo para pares de chave-valor ](kvs-with-functions-create-s3-kvp.md) **nota** O JavaScript runtime 2.0 inclui alguns métodos auxiliares para trabalhar com chave-valor no código da função. Para obter mais informações, consulte [Métodos auxiliares para armazenamentos de chave-valor](functions-custom-methods.md). # Criar um armazenamento de chave-valor Você pode criar um armazenamento de chave-valor e os pares de chave-valor ao mesmo tempo. Também é possível criar um armazenamento de chave-valor vazio e adicionar pares de chave-valor posteriormente. **nota** Se você especificar sua fonte de dados a partir de um bucket do Amazon S3, deverá ter as permissões `s3:GetObject` e `s3:GetBucketLocation` para esse bucket. Se você não tiver essas permissões, o CloudFront não poderá criar seu armazenamento de chave-valor com êxito. Decida se deseja adicionar pares de chave-valor ao mesmo tempo em que cria o armazenamento de chave-valor. É possível importar os pares de chave-valor usando o console do CloudFront, a API do CloudFront ou os SDKs da AWS. No entanto, só é possível importar o arquivo de pares de chave-valor ao criar *inicialmente* o armazenamento de chave-valor. Para criar um arquivo de pares de chave-valor, consulte [Formato de arquivo para pares de chave-valor](kvs-with-functions-create-s3-kvp.md). ------ #### [ Console ] **Como criar um armazenamento de chave-valor** 1. Faça login no Console de gerenciamento da AWS e abra a página **Functions** (Funções) no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions). 1. Escolha a guia **KeyValueStores** e selecione **Criar KeyValueStore**. 1. Informe um nome e uma descrição opcional para o armazenamento de valores de chave. 1. Preencha o **URI do S3**: + Se você tem um arquivo de pares de chave-valor, insira o caminho para o bucket do Amazon S3 no qual armazenou o arquivo. + Deixe esse campo em branco se planeja inserir os pares de chave-valor manualmente. 1. Escolha **Criar**. O armazenamento de chave-valor existe agora. A página de detalhes do novo armazenamento de valores de chave é exibida. As informações na página incluem o ID e o ARN do armazenamento de valores de chave. + O ID é uma string de caracteres aleatória exclusiva na Conta da AWS. + O ARN tem esta sintaxe: *Conta da AWS*`:key-value-store/`*o ID de armazenamentos de chave-valor* 1. Veja a seção **Pares de chave-valor**. Se você importou um arquivo, essa seção mostrará alguns pares de chave-valor. Você pode fazer o seguinte: + Se você importou um arquivo, também poderá adicionar mais valores manualmente. + Se você não importou um arquivo de um bucket do Amazon S3 e deseja adicionar pares de chave-valor agora, poderá concluir a próxima etapa. + É possível ignorar essa etapa e adicionar os pares de chave-valor posteriormente. 1. Como adicionar os pares agora: 1. Selecione **Adicionar pares de chave-valor**. 1. Selecione **Adicionar par** e insira um nome e um valor. Repita essa etapa para adicionar mais pares. 1. Ao terminar, selecione **Salvar alterações** para salvar todos os pares de chave-valor no armazenamento de valores de chave. Na caixa de diálogo exibida, selecione **Concluído**. 1. Para associar agora o armazenamento de valores de chave a uma função agora, preencha a seção **Funções associadas**. Para ter mais informações, consulte [Criar funções](create-function.md) ou [Atualizar funções](update-function.md). Também é possível associar a função posteriormente, na página de detalhes do armazenamento de valores de chave ou na página de detalhes da função. ------ #### [ AWS CLI ] **Como criar um armazenamento de chave-valor** + Execute o comando a seguir para criar um armazenamento de chave-valor e importar os pares de chave-valor de um bucket do Amazon S3. ``` aws cloudfront create-key-value-store \ --name=keyvaluestore1 \ --comment="This is my key value store file" \ --import-source=SourceType=S3,SourceARN=arn:aws:s3:::amzn-s3-demo-bucket1/kvs-input.json ``` **Resposta** ``` { "ETag": "ETVABCEXAMPLE", "Location": "https://cloudfront.amazonaws.com/2020-05-31/key-value-store/arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example", "KeyValueStore": { "Name": "keyvaluestore1", "Id": "8aa76c93-3198-462c-aaf6-example", "Comment": "This is my key value store file", "ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example", "Status": "PROVISIONING", "LastModifiedTime": "2024-08-06T22:19:10.813000+00:00" } } ``` ------ #### [ API ] **Como criar um armazenamento de chave-valor** 1. Use a operação [CreateKeyValueStore do CloudFront](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateKeyValueStore.html). A operação usa vários parâmetros: + Um `name` do armazenamento de chave-valor. + Um parâmetro `comment` que inclua um comentário. + Um parâmetro `import-source` que permita importar pares de chave-valor de um arquivo armazenado em um bucket do Amazon S3. É possível importar de um arquivo somente durante a criação inicial do armazenamento de chave-valor. Para ter informações sobre a estrutura de arquivos, consulte [Formato de arquivo para pares de chave-valor](kvs-with-functions-create-s3-kvp.md). A resposta da operação inclui as seguintes informações: + Os valores transmitidos na solicitação, incluindo o nome atribuído. + Dados, como o horário de criação. + Uma `ETag` (por exemplo, `ETVABCEXAMPLE`), o ARN que inclui o nome do armazenamento de chave-valor (por exemplo, `arn:aws:cloudfront::123456789012:key-value-store/keyvaluestore1`). Você usará alguma combinação da `ETag`, do ARN e do nome para trabalhar com o armazenamento de chave-valor de forma programática. ------ ## Status do armazenamento de chave-valor Ao criar um armazenamento de chave-valor, o armazenamento de dados pode apresentar os seguintes valores de status. **** | Valor | Descrição | | --- | --- | | **Provisionamento** | O armazenamento de chave-valor foi criado e o CloudFront está processando a fonte de dados especificada. | | **Ready** | O armazenamento de chave-valor foi criado e o CloudFront processou com êxito a fonte de dados especificada. | | **Falha na importação** | O CloudFront não conseguiu processar a fonte de dados especificada. Esse status pode aparecer se o formato do arquivo não for válido ou exceder o limite de tamanho. Para obter mais informações, consulte [Formato de arquivo para pares de chave-valor](kvs-with-functions-create-s3-kvp.md). | # Associar o armazenamento de chave-valor à função Depois de criar o armazenamento de chave-valor, é possível atualizar a função para associá-la a esse armazenamento. É necessário fazer essa associação para usar os pares de chave-valor desse armazenamento nessa função. As seguintes regras se aplicam: + Uma função pode ter apenas um armazenamento de chave-valor. + É possível associar o mesmo armazenamento de chave-valor a várias funções. ------ #### [ Console ] **Como associar o armazenamento de chave-valor a uma função** 1. Faça login no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) e selecione a página **Funções**. 1. Escolha o nome da função. 1. Acesse a seção **Associar KeyValueStore** e selecione **Associar KeyValueStore existente**. 1. Selecione o armazenamento de chave-valor que contém os pares de chave-valor na função e escolha **Associar KeyValueStore**. O CloudFront associa imediatamente o armazenamento à função. Não é necessário salvar a função. 1. Para especificar um armazenamento de chave-valor diferente, escolha **Atualizar KeyValueStore associado**, selecione outro nome de armazenamento de chave-valor e escolha **Associar KeyValueStore**. Para obter mais informações, consulte [Atualizar funções](update-function.md). ------ #### [ AWS CLI ] **Como associar o armazenamento de chave-valor a uma função** + Execute o comando a seguir para atualizar a função `MaxAge` e associar um recurso de armazenamento de chave-valor. ``` aws cloudfront update-function \ --name MaxAge \ --function-config '{"Comment":"Max Age 2 years","Runtime":"cloudfront-js-2.0","KeyValueStoreAssociations":{"Quantity":1,"Items":[{"KeyValueStoreARN":"arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example"}]}}' \ --function-code fileb://function-max-age-v1.js \ --if-match ETVABCEXAMPLE ``` + Para associar um armazenamento de chave-valor a uma função, especifique o parâmetro `KeyValueStoreAssociations` e o ARN do armazenamento de chave-valor. + Para alterar a associação, especifique outro ARN de armazenamento de chave-valor. + Para remover a associação, remova o parâmetro `KeyValueStoreAssociations`. Para obter mais informações, consulte [Atualizar funções](update-function.md). ------ #### [ API ] **Como associar o armazenamento de chave-valor a uma função** + Use a operação de API [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html). Para obter mais informações, consulte [Atualizar funções](update-function.md). ------ **Observações** Se você modificar um armazenamento de chave-valor sem alterar os pares de chave-valor, ou se você modificar somente os pares de chave-valor no armazenamento de chave-valor, não será necessário associar esse armazenamento novamente. Você também não precisa republicar a função. No entanto, recomendamos que você teste a função para verificar se ela funciona conforme o esperado. Para obter mais informações, consulte [Testar funções](test-function.md). É possível visualizar todas as funções que usam armazenamentos de chave-valor específicos. No console do CloudFront, selecione a página de detalhes do armazenamento de chave-valor. # Atualizar um armazenamento de chave-valor Ao atualizar um armazenamento de chave-valor, é possível alterar os pares de chave-valor ou alterar a associação entre esse armazenamento e a função. ------ #### [ Console ] **Como atualizar um armazenamento de chave-valor** 1. Faça login no Console de gerenciamento da AWS e abra a página **Functions** (Funções) no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions). 1. Selecione a guia **KeyValueStores**. 1. Selecione o armazenamento de chave-valor que deseja atualizar. + Para atualizar os pares de chave-valor, selecione **Editar** na seção **Pares de chave-valor**. É possível adicionar ou excluir qualquer par de chave-valor. Também é possível alterar o valor de um par de chave-valor existente. Ao concluir, escolha **Salvar alterações**. + Para atualizar a associação desse armazenamento de chave-valor, selecione **Ir para funções**. Para obter mais informações, consulte [Associar o armazenamento de chave-valor à função](kvs-with-functions-associate.md). ------ #### [ AWS CLI ] **Como atualizar um armazenamento de chave-valor** 1. **Alterar pares de chave-valor**: é possível adicionar mais pares de chave-valor, excluir um ou mais pares de chave-valor e alterar o valor de um par existente. Para obter mais informações, consulte [Trabalhar com dados de chave-valor](kvs-with-functions-kvp.md). 1. **Alterar a associação da função para o armazenamento de chave-valor**: para atualizar a associação da função para o armazenamento de chave-valor, consulte [Associar o armazenamento de chave-valor à função](kvs-with-functions-associate.md). **dica** Você precisará do ARN do armazenamento de valores de chave. Para obter mais informações, consulte [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md). ------ #### [ API ] **Como atualizar um armazenamento de chave-valor** 1. **Alterar pares de chave-valor**: é possível adicionar mais pares de chave-valor, excluir um ou mais pares de chave-valor e alterar o valor de um par existente. Para obter mais informações, consulte [Trabalhar com dados de chave-valor](kvs-with-functions-kvp.md). 1. **Alterar a associação da função para o armazenamento de chave-valor**: para atualizar a associação da função para o armazenamento de chave-valor, use a operação de API [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html). Para obter mais informações, consulte [Atualizar funções](update-function.md). **dica** Você precisará do ARN do armazenamento de valores de chave. Para obter mais informações, consulte [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md). ------ # Obter uma referência a um armazenamento de chave-valor Para trabalhar com os armazenamentos de chave-valor de forma programática, é necessário ter a `ETag` e o nome do armazenamento de chave-valor. Para ter os dois valores, é possível usar a AWS Command Line Interface (AWS CLI) ou a API do CloudFront. ------ #### [ AWS CLI ] **Como obter uma referência do armazenamento de chave-valor** 1. Para exibir uma lista de armazenamentos de chave-valor, execute o comando para encontrar o nome do armazenamento de chave-valor que deseja alterar. ``` aws cloudfront list-key-value-stores ``` 1. Na resposta, encontre o nome do armazenamento de chave-valor desejado. **Resposta** ``` { "KeyValueStoreList": { "Items": [ { "Name": "keyvaluestore3", "Id": "37435e19-c205-4271-9e5c-example3", "ARN": "arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example3", "Status": "READY", "LastModifiedTime": "2024-05-08T14:50:18.876000+00:00" }, { "Name": "keyvaluestore2", "Id": "47970d59-6408-474d-b850-example2", "ARN": "arn:aws:cloudfront::123456789012:key-value-store/47970d59-6408-474d-b850-example2", "Status": "READY", "LastModifiedTime": "2024-05-30T21:06:22.113000+00:00" }, { "Name": "keyvaluestore1", "Id": "8aa76c93-3198-462c-aaf6-example", "ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example", "Status": "READY", "LastModifiedTime": "2024-08-06T22:19:30.510000+00:00" } ] } } ``` 1. Execute o comando a seguir para exibir a `ETag` do armazenamento de chave-valor especificado. ``` aws cloudfront describe-key-value-store \ --name=keyvaluestore1 ``` **Resposta** ``` { "ETag": "E3UN6WX5RRO2AG", "KeyValueStore": { "Name": "keyvaluestore1", "Id": "8aa76c93-3198-462c-aaf6-example", "Comment": "This is an example KVS", "ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example", "Status": "READY", "LastModifiedTime": "2024-08-06T22:19:30.510000+00:00" } } ``` ------ #### [ API ] **Como obter uma referência do armazenamento de chave-valor** 1. Use a operação de API [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html) para retornar uma lista de armazenamentos de valores-chave. Encontre o nome do armazenamento de chave-valor que deseja alterar. 1. Use a operação de API [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html) e especifique o nome do armazenamento de chave-valor que você retornou da etapa anterior. ------ A resposta inclui um UUID, o ARN do armazenamento de chave-valor e a `ETag` do armazenamento de chave-valor. + Uma `ETag`, como `E3UN6WX5RRO2AG`. + O UUID tem 128 bits, como `8aa76c93-3198-462c-aaf6-example`. + O ARN inclui o número da Conta da AWS, o `key-value-store` constante e o UUID, como o seguinte exemplo: `arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example` Consulte mais informações sobre a operação `DescribeKeyValueStore` em [Sobre o KeyValueStore do CloudFront](kvs-with-functions-kvp.md#kvs-with-functions-api-describe). # Excluir um armazenamento de chave-valor É possível excluir o armazenamento de chave-valor usando a API ou o console do Amazon CloudFront. ------ #### [ Console ] **Como excluir um armazenamento de chave-valor** 1. Faça login no Console de gerenciamento da AWS e abra a página **Functions** (Funções) no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions). 1. Escolha o nome da função. 1. Na seção **KeyValueStore associado**, verifique se um armazenamento de chave-valor está associado à função. Se estiver, remova a associação escolhendo **Dissociar KeyValueStore** e selecione **Remover associação**. 1. No painel de navegação, selecione a página **Funções** e escolha a guia **KeyValueStores**. 1. Selecione o armazenamento de chave-valor que deseja excluir e selecione **Excluir**. ------ #### [ AWS CLI ] **Como excluir um armazenamento de chave-valor** 1. Obtenha a `ETag` e o nome dos armazenamentos de chave-valor. Para obter mais informações, consulte [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md). 1. Verifique se os armazenamentos de chave-valor estão associados a uma função. Se estiver, remova a associação. Para obter mais informações sobre essas duas etapas, consulte [Atualizar funções](update-function.md). 1. Depois que você tiver o nome e a `ETag` do armazenamento de chave-valor e ele não estiver mais associado a uma função, você poderá excluí-lo. Execute o comando a seguir para excluir o armazenamento de chave-valor especificado. ``` aws cloudfront delete-key-value-store \ --name=keyvaluestore1 \ --if-match=E3UN6WX5RRO2AG ``` ------ #### [ API ] **Como excluir um armazenamento de chave-valor** 1. Obtenha a `ETag` e o nome dos armazenamentos de chave-valor. Para obter mais informações, consulte [Obter uma referência a um armazenamento de chave-valor](kvs-with-functions-get-reference.md). 1. Verifique se os armazenamentos de chave-valor estão associados a uma função. Se estiver, remova a associação. Para obter mais informações sobre essas duas etapas, consulte [Atualizar funções](update-function.md). 1. Para excluir o armazenamento de chave-valor, use a operação de API [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html) do CloudFront. ------ # Formato de arquivo para pares de chave-valor Ao criar um arquivo codificado em UTF-8, use o seguinte formato JSON: ``` { "data":[ { "key":"key1", "value":"value" }, { "key":"key2", "value":"value" } ] } ``` Seu arquivo não pode incluir chaves duplicadas. Se você especificou um arquivo inválido em seu bucket do Amazon S3, é possível atualizar o arquivo para remover quaisquer duplicatas e, em seguida, tentar criar seu armazenamento de chave-valor novamente. Para obter mais informações, consulte [Criar um armazenamento de chave-valor](kvs-with-functions-create.md). **nota** O arquivo da fonte de dados e os pares de chave-valor têm os seguintes limites: Tamanho do arquivo: 5 MB Tamanho da chave: 512 caracteres Tamanho da chave: 1.024 caracteres # Trabalhar com dados de chave-valor Este tópico descreve como adicionar pares de chave-valor a um armazenamento de chave-valor existente. Para incluir pares de chave-valor ao criar inicialmente armazenamentos de chave-valor, consulte [Criar um armazenamento de chave-valor](kvs-with-functions-create.md). **Topics** + [ ## Trabalhar com pares de chave-valor (console) ](#kvs-with-functions-kvp-using-console) + [ ## Sobre o KeyValueStore do CloudFront ](#kvs-with-functions-api-describe) + [ ## Trabalhar com pares de chave-valor (AWS CLI) ](#work-with-kvs-cli-keys) + [ ## Trabalhar com pares de chave-valor (API) ](#kvs-with-functions-kvp-using-api) ## Trabalhar com pares de chave-valor (console) É possível usar o console do CloudFront para trabalhar com os seus pares de chave-valor. **Como trabalhar com pares de chave-valor** 1. Faça login no Console de gerenciamento da AWS e abra a página **Functions** (Funções) no console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions). 1. Selecione a guia **KeyValueStores**. 1. Selecione o armazenamento de chave-valor que deseja alterar. 1. Na seção **Pares de chave-valor**, selecione **Editar**. 1. É possível adicionar um par de chave-valor, excluir um par de chave-valor ou alterar o valor de um par existente. 1. Ao concluir, escolha **Salvar alterações**. ## Sobre o KeyValueStore do CloudFront **dica** A API KeyValueStore do CloudFront é um serviço global que usa o Signature Version 4A (SigV4A) para autenticação. O uso de credenciais temporárias com o SigV4A requer tokens de sessão da versão 2. Para obter mais informações, consulte [Usar credenciais temporárias com a API KeyValueStore do CloudFront](cloudfront-function-restrictions.md#regional-endpoint-for-key-value-store). Se você estiver usando a AWS Command Line Interface (AWS CLI) ou seu próprio código para chamar a API KeyValueStore do CloudFront, consulte as seções a seguir. Quando você trabalha com um armazenamento de chave-valor e seus pares de chave-valor, o serviço que você chama depende do seu caso de uso: + Para trabalhar com pares de chave-valor em um armazenamento de chave-valor *existente*, use o serviço KeyValueStore do CloudFront. + Para incluir pares de chave-valor no armazenamento de chave-valor ao criá-lo *inicialmente*, use o serviço CloudFront. Tanto a API do CloudFront quanto a API KeyValueStore do CloudFront têm uma operação `DescribeKeyValueStore`. Você pode chamá-los por diferentes motivos. Para entender as diferenças, consulte a tabela a seguir. | | API DescribeKeyValueStore do CloudFront | API KeyValueStore DescribeKeyValueStore do CloudFront | | --- | --- | --- | | Dados sobre o armazenamento de chave-valor | Retorna dados, como o status e a data em que o próprio armazenamento de chave-valor foi modificado pela última vez. | Retorna dados sobre o *conteúdo* do recurso de armazenamento: os pares de chave-valor no armazenamento e o tamanho do conteúdo. | | Dados que identificam o armazenamento de chave-valor | Exibe uma `ETag`, o UUID e o ARN do armazenamento de chave-valor. | Exibe uma `ETag` e o ARN do armazenamento de chave-valor. | **Observações** Cada operação DescribeKeyValueStore exibe uma `ETag` *diferente*. As `ETags` não são intercambiáveis. Ao chamar uma operação de API para concluir uma ação, é necessário especificar a `ETag` da API apropriada. Por exemplo, na operação [DeleteKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DeleteKey.html) do KeyValueStore do CloudFront, é possível especificar a `ETag` exibida da operação [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html) do KeyValueStore do CloudFront. Quando você invoca CloudFront Functions usando o KeyValueStore do CloudFront, os valores no armazenamento de chave-valor não são atualizados nem alterados durante a invocação da função. As atualizações são processadas entre as invocações de uma função. ## Trabalhar com pares de chave-valor (AWS CLI) É possível executar os comandos da AWS Command Line Interface a seguir no KeyValueStore do CloudFront. **Contents** + [ ### Listar pares de chave-valor ](#kvs-cli-list-keys) + [ ### Obter pares de chave-valor ](#kvs-cli-get-keys) + [ ### Descrever um armazenamento de chave-valor ](#kvs-cli-describe-keys) + [ ### Criar um par de chave-valor ](#kvs-cli-create-keys) + [ ### Excluir um par de chave-valor ](#kvs-cli-delete-keys) + [ ### Atualizar pares de chave-valor ](#kvs-cli-update-key) ### Listar pares de chave-valor Para listar pares de chave-valor no armazenamento de chave-valor, execute o comando a seguir. ``` aws cloudfront-keyvaluestore list-keys \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example ``` **Resposta** ``` { "Items": [ { "Key": "key1", "Value": "value1" } ] } ``` ### Obter pares de chave-valor Para obter um par de chave-valor no armazenamento de chave-valor, execute o comando a seguir. ``` aws cloudfront-keyvaluestore get-key \ --key=key1 \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example ``` **Resposta** ``` { "Key": "key1", "Value": "value1", "ItemCount": 1, "TotalSizeInBytes": 11 } ``` ### Descrever um armazenamento de chave-valor Para descrever um armazenamento de chave-valor, execute o comando a seguir. ``` aws cloudfront-keyvaluestore describe-key-value-store \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example ``` **Resposta** ``` { "ETag": "KV1F83G8C2ARO7P", "ItemCount": 1, "TotalSizeInBytes": 11, "KvsARN": "arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example", "Created": "2024-05-08T07:48:45.381000-07:00", "LastModified": "2024-08-05T13:50:58.843000-07:00", "Status": "READY" } ``` ### Criar um par de chave-valor Para criar um par de chave-valor no armazenamento de chave-valor, execute o comando a seguir. ``` aws cloudfront-keyvaluestore put-key \ --if-match=KV1PA6795UKMFR9 \ --key=key2 \ --value=value2 \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example ``` **Resposta** ``` { "ETag": "KV13V1IB3VIYZZH", "ItemCount": 3, "TotalSizeInBytes": 31 } ``` ### Excluir um par de chave-valor Para excluir um par de chave-valor, execute o comando a seguir. ``` aws cloudfront-keyvaluestore delete-key \ --if-match=KV13V1IB3VIYZZH \ --key=key1 \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example ``` **Output** ``` { "ETag": "KV1VC38T7YXB528", "ItemCount": 2, "TotalSizeInBytes": 22 } ``` ### Atualizar pares de chave-valor É possível usar o comando `update-keys` para atualizar mais de um par de chave-valor. Por exemplo, para excluir um par de chave-valor e criar outro, execute o comando a seguir. ``` aws cloudfront-keyvaluestore update-keys \ --if-match=KV2EUQ1WTGCTBG2 \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example \ --deletes '[{"Key":"key2"}]' \ --puts '[{"Key":"key3","Value":"value3"}]' ``` **Resposta** ``` { "ETag": "KV3AEGXETSR30VB", "ItemCount": 3, "TotalSizeInBytes": 28 } ``` ## Trabalhar com pares de chave-valor (API) Siga esta seção para trabalhar com os pares de chave-valor de forma programática. **Contents** + [ ### Obter uma referência a um armazenamento de chave-valor ](#kvs-with-functions-api-ref) + [ ### Alterar pares de chave-valor em um armazenamento de chave-valor ](#kvs-with-functions-api-actions) + [ ### Exemplo de código de KeyValueStore do CloudFront ](#example-code-key-value-store) ### Obter uma referência a um armazenamento de chave-valor Ao usar a API KeyValueStore do CloudFront para chamar uma operação de gravação, é necessário especificar o ARN e a `ETag` do armazenamento de chave-valor. Para obter esses dados, faça o seguinte: **Como obter uma referência a um armazenamento de chave-valor** 1. Use a operação de API [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html) para obter uma lista de armazenamentos de chave-valor. Encontre o armazenamento de chave-valor que deseja alterar. 1. Use a [operação de API CloudFrontKeyValueStore DescribeKeyValueStore](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html) e especifique o armazenamento de chave-valor da etapa anterior. A resposta inclui o ARN e a `ETag` do armazenamento de chave-valor. + O ARN inclui o número da Conta da AWS, o `key-value-store` constante e o UUID, como o seguinte exemplo: `arn:aws:cloudfront::123456789012:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` + Uma `ETag` que se parece com o seguinte exemplo: `ETVABCEXAMPLE2` ### Alterar pares de chave-valor em um armazenamento de chave-valor É possível especificar o armazenamento de chave-valor que contém o par de chave-valor que você deseja atualizar. Veja as seguintes operações da API KeyValueStore do CloudFront: + [CloudFrontKeyValueStore DeleteKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DeleteKey.html): exclui um par de chave-valor + [CloudFrontKeyValueStore GetKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_GetKey.html): retorna um par de chave-valor + [CloudFrontKeyValueStore ListKeys](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_ListKeys.html): retorna uma lista de pares de chave-valor + [CloudFrontKeyValueStore PutKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_PutKey.html): é possível realizar as seguintes tarefar: + Criar um par de chave-valor em um armazenamento de chave-valor especificando um novo nome e valor da chave. + Defina um valor diferente em um par de chave-valor especificando um nome de chave existente e um novo valor de chave. + [CloudFrontKeyValueStore UpdateKeys](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_UpdateKeys.html): é possível executar uma ou mais das seguintes ações em uma operação de tudo ou nada: + Excluir um ou mais pares de chave-valor. + Criar um ou mais pares de chave-valor. + Definir um valor diferente em um ou mais pares de chave-valor existentes. ### Exemplo de código de KeyValueStore do CloudFront **Example** O código a seguir mostra como chamar a operação de API `DescribeKeyValueStore` para um armazenamento de chave-valor. ``` const { CloudFrontKeyValueStoreClient, DescribeKeyValueStoreCommand, } = require("@aws-sdk/client-cloudfront-keyvaluestore"); require("@aws-sdk/signature-v4-crt"); (async () => { try { const client = new CloudFrontKeyValueStoreClient({ region: "us-east-1" }); const input = { KvsARN: "arn:aws:cloudfront::123456789012:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", }; const command = new DescribeKeyValueStoreCommand(input); const response = await client.send(command); } catch (e) { console.log(e); } })(); ``` # Personalizar com funções de conexão do CloudFront Functions As funções de conexão do CloudFront permitem escrever funções leves em JavaScript para validação de certificados mTLS e lógica de autenticação personalizada. As funções de conexão são executadas durante o estabelecimento da conexão mTLS para validar certificados de cliente, implementar regras de autenticação específicas de dispositivo e lidar com cenários de revogação de certificados. O ambiente de runtime das funções de conexão oferece tempos de inicialização abaixo de 1 milissegundo, escala imediatamente para lidar com milhões de solicitações por segundo e é altamente seguro. As funções de conexão são um recurso nativo do CloudFront, o que significa que é possível criar, testar e implantar código inteiramente no CloudFront. Quando uma função de conexão é associada a uma distribuição do CloudFront habilitada para mTLS, o CloudFront intercepta solicitações de conexão TLS nos locais da borda do CloudFront e transmite informações dos certificados à função. É possível invocar funções de conexão quando ocorrem os seguintes eventos: + Durante o estabelecimento da conexão TLS (solicitação de conexão): para conexão TLS mútua (mTLS). Para ter mais informações sobre as funções de conexão, consulte os tópicos a seguir. **Topics** + [ # Visão geral e fluxo de trabalho ](connection-functions-overview.md) + [ # Configuração e limites ](connection-function-configuration-limits.md) + [ # Crie funções de conexão do CloudFront para validação de TLS mútua (visualizador) ](create-connection-functions.md) + [ # Escrever o código da função de conexão do CloudFront para validação de TLS mútua (visualizador) ](write-connection-function-code.md) + [ # Testar as funções de conexão do CloudFront antes da implantação ](test-connection-functions.md) + [ # Associar funções de conexão a distribuições ](associate-connection-functions.md) + [ # Implementar a revogação de certificados para TLS mútua (visualizador) com o CloudFront Functions e o KeyValueStore ](implement-certificate-revocation.md) # Visão geral e fluxo de trabalho As funções de conexão do CloudFront são um tipo especializado de CloudFront Functions executadas durante o handshake do TLS quando um cliente tenta estabelecer uma conexão mTLS. A função de conexão pode acessar informações sobre certificados de cliente, os parâmetros de configuração da mTLS, os resultados da verificação de revogação de certificados e o endereço IP do cliente. As funções de conexão são invocadas depois que o CloudFront realiza a validação padrão do certificado (cadeia de confiança, expiração e verificação de assinatura), mas podem ser executadas mesmo se as verificações de revogação de certificados falharem. Isso permite implementar uma lógica personalizada para lidar com certificados revogados ou adicionar outros critérios de validação. Quando você criar e publicar uma função de conexão, adicione uma associação para o tipo de evento de solicitação de conexão com uma distribuição habilitada para mTLS. Isso faz com que a função seja executada sempre que um cliente tenta estabelecer uma conexão mTLS com o CloudFront. As funções de conexão do CloudFront seguem um ciclo de vida de dois estágios que permite desenvolver e testar funções antes de implantá-las na produção. Esse fluxo de trabalho garante que as funções de conexão funcionem corretamente e não afetem o tráfego em tempo real. **Topics** + [ ## Estágios da função ](#connection-function-stages) + [ ## Fluxo de trabalho de desenvolvimento ](#connection-function-development-workflow) + [ ## Diferenças em relação a outros tipos de função ](#connection-function-differences) ## Estágios da função As funções de conexão podem estar em um de dois estágios: + **DESENVOLVIMENTO**: as funções neste estágio podem ser modificadas, testadas e atualizadas. Use esse estágio para escrever e depurar o código da função. + **ATIVO**: as funções neste estágio são somente leitura e lidam com o tráfego de produção. Não é possível modificar as funções diretamente no estágio ATIVO. Quando você cria uma função de conexão, ela começa no estágio **DESENVOLVIMENTO**. Depois de testar e validar, você deve publicá-la para movê-la para o estágio **ATIVO**. ## Fluxo de trabalho de desenvolvimento Siga este fluxo de trabalho para desenvolver e implantar funções de conexão: 1. **Criar**: crie uma função de conexão no estágio DESENVOLVIMENTO com seu código e configuração iniciais. 1. **Testar**: antes da implantação, use a funcionalidade de teste para validar a função com exemplos de eventos de conexão. 1. **Atualizar**: modifique o código e a configuração da função conforme necessário com base nos resultados do teste. 1. **Publicar**: quando a função estiver pronta para produção, publique-a para movê-la do estágio DESENVOLVIMENTO para o ATIVO. 1. **Associar**: associe a função publicada à sua distribuição habilitada para mTLS para lidar com conexões em tempo real. Para fazer alterações em uma função ATIVA, é necessário atualizar a versão de DESENVOLVIMENTO e publicá-la novamente. Isso cria uma versão no estágio ATIVO. ## Diferenças em relação a outros tipos de função As funções de conexão diferem das funções de solicitação de visualizador e resposta ao visualizador de várias maneiras importantes: + As funções de conexão são executadas após o handshake do mTLS, antes que qualquer processamento HTTP ocorra. + As funções de conexão têm acesso às informações do certificado TLS, e não aos dados de solicitação/resposta HTTP. + As funções de conexão só podem permitir ou negar conexões, não modificar dados HTTP. + As funções de conexão são invocadas somente para novas conexões TLS, não para reutilização de conexão. + Para garantir que a validação de certificados ocorra em todas as conexões, não é possível retomar a sessão TLS na mTLS. + As funções de conexão são executadas complementarmente às funções padrão de solicitação de visualizador e resposta ao visualizador. + As funções de conexão são associadas em nível de distribuição, em vez de em nível de comportamento de cache. + É possível usar funções de conexão somente com o Runtime 2.0 do JavaScript. # Configuração e limites As funções de conexão do CloudFront têm requisitos de configuração e limites de serviço específicos devido ao papel especializado que elas desempenham na validação de conexões TLS e aos requisitos de desempenho da computação de borda. **Topics** + [ ## Requisitos de código da função ](#connection-function-code-requirements) + [ ## Limites do serviço ](#connection-function-service-limits) + [ ## Opções de filtragem de função ](#connection-function-filtering-options) ## Requisitos de código da função As funções de conexão exigem código JavaScript que processe eventos de conexão TLS. O código da função deve: + Ser escrito em JavaScript. + Processar eventos de conexão e tomar decisões permitir/negar. + Concluir a execução de acordo com os limites de tempo. + Lidar com a lógica de validação de certificados e conexões. ## Limites do serviço As funções de conexão estão sujeitas aos seguintes limites: + **Tamanho da função**: o código e a configuração da função têm uma limitação de tamanho. + **Tempo de execução**: as funções têm limites estritos de tempo de execução para o processamento de conexões TLS. + **Limites de associação**: cada distribuição pode ter somente uma função de conexão associada. + **Restrições de estágio**: somente funções no estágio ATIVO podem ser associadas a distribuições. ## Opções de filtragem de função Ao listar funções de conexão, use os seguintes filtros: + **Filtro de estágio**: filtre pelo estágio DESENVOLVIMENTO ou ATIVO. + **Filtro de associação**: filtre por associação de ID de distribuição ou ID de armazenamento de chave-valor. Esses filtros ajudam a organizar e gerenciar as funções de conexão em diferentes ambientes e casos de uso. # Crie funções de conexão do CloudFront para validação de TLS mútua (visualizador) A função de conexão do CloudFront é criada em dois estágios: 1. Crie o código da função como JavaScript. É possível usar o exemplo padrão do console do CloudFront ou crie seu próprio. Para saber mais, consulte os seguintes tópicos: + Escrever o código da função de conexão do CloudFront para validação de mTLS + Estrutura de eventos e formato de resposta da função de conexão do CloudFront + Exemplo de código de função de conexão 1. Use o CloudFront para criar a função de conexão e incluir o código. O código existe dentro da função (não como referência). **Topics** + [ ## Console do CloudFront ](#create-connection-function-console) + [ ## AWS CLI ](#create-connection-function-cli) ## Console do CloudFront **Como criar uma função de conexão** 1. Faça login no Console de gerenciamento da AWS e abra o console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. Escolha a opção **Criar função**. 1. Insira um nome de função que seja exclusivo dentro da Conta da AWS, escolha **Função de conexão** como o tipo de função e selecione **Continuar**. 1. A página de detalhes da nova função de conexão é exibida. **nota** É possível usar funções de conexão somente com o Runtime 2.0 do JavaScript. Para usar a integração entre o KeyValueStore e a função de conexão do CloudFront na função, é necessário usar essa versão de runtime. 1. Na seção **Código da função**, selecione a guia **Compilar** e insira o código da função de conexão. O exemplo de código incluído na guia “Compilar” ilustra a sintaxe básica do código da função de conexão. 1. Escolha **Salvar alterações**. 1. Se o código da função de conexão usar KeyValueStore para verificação de revogação de certificados ou validação de dispositivos, será necessário associar um KeyValueStore. É possível associar o KeyValueStore durante a criação inicial da função. Ou é possível associá-lo posteriormente, associando funções de conexão. Para associar um KeyValueStore agora, siga estas etapas: + Acesse a seção **Associar KeyValueStore** e selecione **Associar KeyValueStore existente**. + Selecione o KeyValueStore que contém os dados do certificado para sua função de conexão e escolha **Associar KeyValueStore**. O CloudFront associa imediatamente o armazenamento à função. Não é necessário salvar a função. ## AWS CLI Quando usamos a CLI, costumamos primeiro criar o código da função em um arquivo e, depois, criar a função com a AWS CLI. **Como criar uma função de conexão** 1. Crie o código da função de conexão em um arquivo e armazene-o em um diretório ao qual o computador possa se conectar. 1. Execute o comando conforme mostrado no exemplo. Este exemplo usa a notação `fileb://` para transmitir o arquivo. Ele também inclui quebras de linha para tornar o comando mais legível. ``` aws cloudfront create-connection-function \ --name CertificateValidator \ --connection-function-config '{ "Comment":"Device certificate validation", "Runtime":"cloudfront-js-2.0", "KeyValueStoreAssociations":{ "Quantity":1, "Items":[{ "KeyValueStoreARN":"arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" }] } }' \ --connection-function-code fileb://certificate-validator.js ``` **nota** **Runtime**: as funções de conexão são compatíveis somente com o Runtime 2.0 do JavaScript (cloudfront-js-2.0). **KeyValueStoreAssociations**: se a função de conexão usar o KeyValueStore para validação de certificados, será possível associar o KeyValueStore durante a criação inicial da função. Ou é possível associá-lo posteriormente, usando update-connection-function. A quantidade é sempre 1 porque cada função de conexão pode ter apenas um KeyValueStore associado a ela. 1. Quando o comando é bem-sucedido, a saída é semelhante à seguinte: ``` ETag: ETVABCEXAMPLE ConnectionFunctionSummary: ConnectionFunctionConfig: Comment: Device certificate validation Runtime: cloudfront-js-2.0 KeyValueStoreAssociations: Quantity: 1 Items: - KeyValueStoreARN: arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ConnectionFunctionMetadata: CreatedTime: '2024-09-04T16:32:54.292000+00:00' ConnectionFunctionARN: arn:aws:cloudfront::111122223333:connection-function/CertificateValidator LastModifiedTime: '2024-09-04T16:32:54.292000+00:00' Stage: DEVELOPMENT Name: CertificateValidator Status: UNPUBLISHED Location: https://cloudfront.amazonaws.com/2020-05-31/connection-function/arn:aws:cloudfront:::connection-function/CertificateValidator ``` A maioria das informações é repetida a partir da solicitação. Outras informações são adicionadas pelo CloudFront. **nota** **ETag**: esse valor muda sempre que a função de conexão é modificada. Esse valor é necessário para atualizar ou publicar a função. **Estágio**: as novas funções de conexão começam no estágio DESENVOLVIMENTO. Antes de associar a função a uma distribuição, é necessário publicá-la para movê-la para o estágio ATIVO. **Status**: o status da função se mantém como NÃO PUBLICADA até que ela seja publicada no estágio ATIVO. # Escrever o código da função de conexão do CloudFront para validação de TLS mútua (visualizador) As funções de conexão do CloudFront possibilitam escrever funções leves em JavaScript para validação de certificados mTLS e lógica de autenticação personalizada. O código da função de conexão pode validar certificados de cliente, implementar regras de autenticação específicas do dispositivo, lidar com cenários de revogação de certificados e tomar decisões para permitir/negar conexões TLS nos locais da borda do CloudFront ao redor do mundo. As funções de conexão oferecem um método eficaz para estender a validação integrada de certificados do CloudFront com sua própria lógica de negócios. Diferentemente das funções de solicitação de visualizador e resposta ao visualizador que processam dados HTTP, as funções de conexão operam na camada de TLS e têm acesso a informações do certificado, ao endereço IP do cliente e a detalhes da conexão TLS. Isso as torna ideais para implementar modelos de segurança de confiança zero, sistemas de autenticação de dispositivos e políticas personalizadas de validação de certificados que vão além da validação padrão de PKI. O código da função de conexão é executado em um ambiente seguro e isolado com tempos de inicialização de menos de 1 milissegundo e pode ser escalado para lidar com milhões de conexões por segundo. O runtime é otimizado para workloads de validação de certificados e oferece integração incorporada com o KeyValueStore do CloudFront para operações de pesquisa de dados em tempo real, permitindo cenários de autenticação sofisticados, como verificação da lista de revogação de certificados e validação da lista de permissões de dispositivos. Para escrever um código de função de conexão eficaz, consulte os tópicos a seguir para obter ajuda. Para ver exemplos completos de código e tutoriais detalhados, consulte as seções do tutorial neste guia e explore os exemplos de função de conexão disponíveis no console do CloudFront. **Topics** + [ ## Casos de uso e propósitos das funções de conexão do CloudFront ](#connection-function-use-cases) + [ ## Estrutura de eventos e formato de resposta da função de conexão do CloudFront ](#connection-function-event-structure) + [ ## Recursos do runtime do JavaScript para funções de conexão do CloudFront ](#connection-function-javascript-runtime) + [ ## Métodos auxiliares e APIs de função de conexão do CloudFront ](#connection-function-helper-methods) + [ ## Integração entre o KeyValueStore e a função de integração do CloudFront ](#connection-function-kvs-integration) + [ ## Utilizar async e await ](#connection-function-async-await) + [ ## Exemplo de código de função de conexão ](#connection-function-code-examples) ## Casos de uso e propósitos das funções de conexão do CloudFront Antes de escrever uma função de conexão do CloudFront, determine cuidadosamente que tipo de validação de certificados ou lógica de autenticação é necessário implementar. As funções de conexão são projetadas para casos de uso específicos que exigem validação personalizada além da verificação padrão de certificados PKI. Entender seu caso de uso ajuda a criar um código eficiente que atenda aos seus requisitos de segurança e, ao mesmo tempo, mantenha o desempenho ideal. Entre os casos de uso comuns de função de conexão estão: + **Tratamento de revogação de certificados**: implemente políticas personalizadas para lidar com certificados revogados, como períodos de carência para alternância de certificados, exceções de rede confiável para dispositivos internos ou cenários de acesso de emergência em que certificados revogados possam precisar de acesso temporário. + **Suporte opcional à mTLS**: gerencie conexões mTLS e não mTLS com políticas de autenticação diferentes para oferecer segurança aprimorada a clientes que usam certificados e, ao mesmo tempo, manter a compatibilidade com clientes legados. + **Autenticação baseada em IP**: combine a validação de certificados com as verificações de endereço IP de clientes para aumentar a segurança restringindo, por exemplo, o acesso de regiões geográficas específicas, redes empresariais ou intervalos de IP mal-intencionados conhecidos. + **Validação de certificado multilocatário**: implemente regras de validação específicas de locatário, nas quais diferentes autoridades de certificação ou critérios de validação se aplicam com base no emissor do certificado do cliente ou nos atributos do assunto. + **Controle de acesso baseado em tempo**: aplique restrições com base no tempo em situações em que os certificados são válidos somente durante horários, janelas de manutenção ou períodos comerciais específicos, mesmo que o certificado em si não tenha expirado. As funções de conexão são executadas depois que o CloudFront realiza a validação padrão de certificados (verificação da cadeia de confiança, verificações de expiração e validação de assinatura), mas antes do estabelecimento da conexão TLS. Com essa regulação de tempo, você tem flexibilidade para adicionar critérios de validação personalizados e, ao mesmo tempo, se beneficiar da validação de certificados integrada do CloudFront. A função recebe os resultados da validação padrão e pode tomar decisões respaldadas sobre se deve permitir ou negar a conexão com base em critérios padrão e personalizados. Ao projetar sua função de conexão, considere as implicações de desempenho da lógica de validação. Como as funções têm um limite de execução de 5 milissegundos, é necessário otimizar operações complexas para ganhar velocidade. Use o KeyValueStore para pesquisas rápidas de dados em vez de cálculos complexos e estruture a lógica de validação para antecipar-se à falha no caso de certificados inválidos. ## Estrutura de eventos e formato de resposta da função de conexão do CloudFront As funções de conexão do CloudFront recebem uma estrutura de eventos diferente das funções de solicitação de visualizador e de resposta ao visualizador. Em vez de dados de solicitação/resposta HTTP, as funções de conexão recebem informações de certificado e conexão que podem ser usadas para tomar decisões de autenticação. **Topics** + [ ### Estrutura de eventos para funções de conexão ](#connection-function-event-structure-details) + [ ### Formato de resposta da função de conexão ](#connection-function-response-format) ### Estrutura de eventos para funções de conexão As funções de conexão recebem um objeto de evento que contém informações de certificado e conexão. A estrutura de eventos da função é mostrada abaixo: ``` { "clientCertificate": { "certificates": { "leaf": { "serialNumber": "string", "issuer": "string", "subject": "string", "validity": { "notBefore": "string", "notAfter": "string", }, "sha256Fingerprint": "string" } } }, "clientIp": "string", "endpoint": "string", "distributionId": "string", "connectionId": "string" } ``` Abaixo é apresentado um exemplo da estrutura do objeto de evento: ``` { "clientCertificate": { "certificates": { "leaf": { "serialNumber": "00:9e:2a:af:16:56:e5:47:25:7d:2e:38:c3:f9:9d:57:fa", "issuer": "C=US, O=Ram, OU=Edge, ST=WA, CN=mTLS-CA, L=Snoqualmie", "subject": "C=US, O=Ram, OU=Edge, ST=WA, CN=mTLS-CA, L=Snoqualmie", "validity": { "notBefore": "2025-09-10T23:43:10Z", "notAfter": "2055-09-11T00:43:02Z" }, "sha256Fingerprint": "_w6bJ7aOAlGOj7NUhJxTfsfee-ONg_xop3_PTgTJpqs=" } } }, "clientIp": "127.0.0.1", "endpoint": "d3lch071jze0cb.cloudfront.net", "distributionId": "E1NXS4MQZH501R", "connectionId": "NpvTe1925xfj24a67sPQr7ae42BIq03FGhJJKfrQYWZcWZFp96SIIg==" } ``` ### Formato de resposta da função de conexão A função de conexão deve exibir um objeto de resposta que indique se a conexão deve ser permitida ou negada. Use os métodos auxiliares para tomar decisões sobre conexão: ``` function connectionHandler(connection) { // Helper methods to allow or deny connections if (/* some logic to determine if function should allow connection */) { connection.allow(); } else { connection.deny(); } } ``` Diferentemente das funções de solicitação de visualizador e resposta ao visualizador, as funções de conexão não podem modificar solicitações ou respostas HTTP. Elas só podem permitir ou negar a conexão TLS. ## Recursos do runtime do JavaScript para funções de conexão do CloudFront As funções de conexão do CloudFront usam o Runtime 2.0 do JavaScript para o CloudFront Functions, que oferece um ambiente seguro e de alto desempenho especificamente otimizado para workloads de validação de certificados. O runtime foi projetado para ser iniciado em menos de 1 milissegundo e processar milhões de execuções simultâneas na rede de borda global do CloudFront. O ambiente de runtime inclui suporte abrangente à linguagem JavaScript: + **Suporte ao ECMAScript 2020 (ES11)**: recursos modernos de JavaScript, como encadeamento opcional (?.), coalescência nula (??) e BigInt, para processar números de série extensos de certificado. + **Objetos integrados**: objetos JavaScript padrão, como Object, Array, JSON, Math e Date. + **Registro em log do console**: use console.log() para depurar e monitorar decisões de validação de certificados. Os logs são disponibilizados em tempo real durante o teste e podem ajudar a solucionar problemas de lógica de validação no desenvolvimento. + **Integração com o KeyValueStore**: acesso nativo ao KeyValueStore do CloudFront para operações de pesquisa de dados ultrarrápidas, o que permite a verificação de revogação de certificados em tempo real, a validação da lista de permissões de dispositivos e a recuperação da configuração específica do locatário. As funções de conexão são otimizadas para oferecer alto desempenho em cenários de validação de certificados. O runtime gerencia automaticamente o gerenciamento de memória, a coleta de resíduos e a limpeza de recursos para garantir um desempenho consistente em milhões de conexões simultâneas. Todas as operações são projetadas para serem determinísticas e rápidas. Prova disso são as pesquisas no KeyValueStore, que normalmente são concluídas em questão de microssegundos. O ambiente de runtime é completamente isolado entre as execuções de função, garantindo que não haja vazamento de dados entre diferentes conexões de cliente. Cada execução de função começa com um estado limpo e não tem acesso aos resultados da execução anterior ou aos dados do cliente de outras conexões. ## Métodos auxiliares e APIs de função de conexão do CloudFront As funções de conexão do CloudFront oferecem métodos auxiliares especializados projetados para simplificar as decisões de validação de certificados e aprimorar a observabilidade. Esses métodos são otimizados para o fluxo de trabalho de validação de conexão e se integram perfeitamente aos sistemas de monitoramento e registro em log de conexões do CloudFront. + **connection.allow()**: permite que a conexão TLS continue. Esse método sinaliza ao CloudFront para concluir o handshake do TLS e permitir que o cliente estabeleça a conexão. Use-o quando a validação do certificado for aprovada e qualquer lógica de autenticação personalizada for satisfeita. + **connection.deny()**: nega a conexão TLS e encerra o handshake. Esse método encerra imediatamente a conexão e impede que qualquer tráfego HTTP flua. O cliente receberá um erro de conexão TLS. Use-o para certificados inválidos, falha na autenticação ou violações de política. + **connection.logCustomData ()**: adiciona dados personalizados aos logs de conexão (até 800 bytes de texto UTF-8). Esse método permite incluir resultados de validação, detalhes do certificado ou justificação de decisão nos logs de conexão do CloudFront para monitoramento de segurança, auditoria de conformidade e solução de problemas. Esses métodos oferecem uma interface limpa e declarativa para tomar decisões de conexão e registrar em log informações relevantes para monitoramento e depuração. O padrão de permitir/negar garante que a intenção da função seja clara e que o CloudFront possa otimizar o tratamento de conexões com base em sua decisão. Os dados de registro em log personalizado estão imediatamente disponíveis nos logs de conexão do CloudFront e podem ser usados com ferramentas de análise de log para monitoramento de segurança e insights operacionais. Sempre chame connection.allow() ou connection.deny() antes que sua função seja concluída. Se nenhum método for chamado, o CloudFront negará a conexão por padrão como medida de segurança. ## Integração entre o KeyValueStore e a função de integração do CloudFront As funções de conexão do CloudFront podem usar o KeyValueStore do CloudFront para realizar pesquisas de dados ultrarrápidas em cenários de validação de certificados. O KeyValueStore é particularmente eficaz para funções de conexão porque oferece acesso global e com consistência final aos dados com tempos de pesquisa de microssegundos em todos os locais da borda do CloudFront. Isso o torna ideal para manter listas de revogação de certificados, listas de permissões de dispositivos, configurações de locatários e outros dados de validação que precisam estar acessíveis durante o handshake do TLS. A integração do KeyValueStore foi projetada especificamente para fluxos de trabalho de validação de conexão de alto desempenho: + **KVSHandle.exists (key)**: verifica se existe uma chave no KeyValueStore sem recuperar o valor. Esse é o método mais eficiente para cenários de validação binária, como verificação de revogação de certificados, em que somente é necessário saber se o número de série do certificado está em uma lista de revogação. + **KVSHandle.get(key)**: recupera um valor do KeyValueStore para cenários de validação mais complexos. Use-o quando precisar acessar dados de configuração, regras de validação ou metadados associados a um certificado ou identificador de dispositivo. As operações do KeyValueStore são assíncronas e devem ser usadas com a sintaxe async/await. O KeyValueStore tem um limite de tamanho total de 10 MB e comporta até 10 milhões de pares de chave-valor. Os dados do KeyValueStore têm consistência final em todos os locais da borda e as atualizações normalmente se propagam em questão de segundos. Para ter um desempenho ideal, estruture as chaves do KeyValueStore para minimizar as operações de pesquisa. Use o número de série dos certificados como chave para simplificar a verificação de revogação ou crie chaves compostas combinando o hash do emissor e o número de série para ambientes com várias CAs. Considere as vantagens e desvantagens entre a complexidade das chaves e a capacidade do KeyValueStore ao projetar sua estrutura de dados. ## Utilizar async e await As funções de conexão permitem operações assíncronas usando a sintaxe async/await, que é essencial ao trabalhar com operações do KeyValueStore ou outras tarefas assíncronas. O padrão async/await garante que a função aguarde a conclusão das pesquisas do KeyValueStore antes de tomar decisões de conexão, mantendo as características de alto desempenho necessárias para o processamento de handshake do TLS. O uso adequado de async/await é fundamental para as funções de conexão porque as operações do KeyValueStore, embora muito rápidas, ainda são operações de rede que exigem coordenação em toda a infraestrutura distribuída do CloudFront. O runtime processa automaticamente a resolução de promises e garante que a função seja concluída dentro do limite de execução de 5 milissegundos. **Example : função de conexão async com o KeyValueStore** ``` import cf from 'cloudfront'; async function connectionHandler(connection) { const kvsHandle = cf.kvs(); // Async operation to check KeyValueStore for certificate revocation const isRevoked = await kvsHandle.exists(connection.clientCertificate.certificates.leaf.serialNumber); if (isRevoked) { // Log the revocation decision with certificate details connection.logCustomData(`REVOKED_CERT:${connection.clientCertificate.certificates.leaf.serialNumber}:${connection.clientCertificate.certificates.leaf.issuer}`); console.log(`Denying connection for revoked certificate: ${connection.clientCertificate.certificates.leaf.serialNumber}`); return connection.deny(); } // Log successful validation for monitoring connection.logCustomData(`VALID_CERT:${connection.clientCertificate.certificates.leaf.serialNumber}`); console.log(`Allowing connection for valid certificate: ${connection.clientCertificate.certificates.leaf.serialNumber}`); return connection.allow(); } ``` Sempre use async/await ao chamar métodos do KeyValueStore ou outras operações assíncronas. O runtime da função de conexão processa a resolução de promises automaticamente e garante o fluxo de execução adequado, de acordo com as rígidas restrições de tempo de processamento de handshake do TLS. Evite usar .then() ou padrões de retorno de chamada, pois async/await oferece um tratamento de erros mais claro e melhor desempenho no ambiente da função de conexão. Ao criar funções de conexão assíncronas, estruture o código para minimizar o número de operações do KeyValueStore e execute-as o mais cedo possível em sua lógica de validação. Isso garante máximo desempenho e reduz o risco de problemas de tempo limite durante períodos de tráfego intenso. Considere a possibilidade de agrupar verificações de validação relacionadas em lote e usar o método do KeyValueStore [exists() versus get()] mais eficiente para seu caso de uso. ## Exemplo de código de função de conexão Os exemplos a seguir demonstram padrões de função de conexão comuns para diferentes cenários de validação. Use esses exemplos como pontos de partida para suas próprias implementações de função de conexão. **Example : validação de certificado de dispositivo** Este exemplo valida números de série de dispositivo e campos de assunto de certificado para dispositivos de IoT, consoles de jogos e outros cenários de autenticação de clientes: ``` async function connectionHandler(connection) { // Custom validation: check device serial number format const serialNumber = connection.clientCertificate.certificates.leaf.serialNumber; if (!serialNumber.startsWith("DEV")) { connection.logCustomData(`INVALID_SERIAL:${serialNumber}`); return connection.deny(); } // Validate certificate subject contains required organizational unit const subject = connection.clientCertificate.certificates.leaf.subject; if (!subject.includes("OU=AuthorizedDevices")) { connection.logCustomData(`INVALID_OU:${subject}`); return connection.deny(); } // Allow connection for valid devices connection.logCustomData(`VALID_DEVICE:${serialNumber}`); return connection.allow(); } ``` Essa função executa várias verificações de validação, além da validação padrão de certificados, como o formato do número de série do dispositivo e a verificação da unidade organizacional. **Example : mTLS opcional com autenticação mista** Este exemplo lida com conexões mTLS e não mTLS com políticas de autenticação diferentes: ``` async function connectionHandler(connection) { if (connection.clientCertificate) { // mTLS connection - enhanced validation for certificate holders const subject = connection.clientCertificate.certificates.leaf.subject; connection.logCustomData(`MTLS_SUCCESS:${subject}:${connection.clientIp}`); console.log(`mTLS connection from: ${subject}`); return connection.allow(); } else { // Non-mTLS connection - apply IP-based restrictions const clientIp = connection.clientIp; // Only allow non-mTLS from specific IP ranges if (clientIp.startsWith("203.0.113.") || clientIp.startsWith("198.51.100.")) { connection.logCustomData(`NON_MTLS_ALLOWED:${clientIp}`); console.log(`Non-mTLS connection allowed from: ${clientIp}`); return connection.allow(); } connection.logCustomData(`NON_MTLS_DENIED:${clientIp}`); return connection.deny(); } } ``` Essa função oferece segurança aprimorada para clientes com certificados, mantendo a compatibilidade com clientes legados de intervalos de IP confiáveis. # Testar as funções de conexão do CloudFront antes da implantação É possível testar a função de conexão do CloudFront no estágio DESENVOLVIMENTO usando a operação de API TestConnectionFunction. O teste permite validar a lógica da função com exemplos de evento de conexão antes da publicação no estágio ATIVO. **Topics** + [ ## Processo de teste ](#connection-function-testing-process) + [ ## Resultados do teste ](#connection-function-test-results) + [ ## Objeto de teste de conexão ](#connection-test-object) ## Processo de teste Para testar uma função de conexão: 1. Crie uma função de conexão no estágio DESENVOLVIMENTO. 1. Prepare um objeto de conexão de teste que represente o evento de conexão TLS. 1. Use a operação de API TestConnectionFunction para executar a função com os dados de teste. 1. Analise os resultados do teste, inclusive a saída da função, os logs de execução e quaisquer mensagens de erro. 1. Atualize o código da função conforme necessário e repita o processo de teste. ## Resultados do teste Ao testar uma função de conexão, alguns dos resultados são: + **Resumo da função**: metadados sobre a função que foi testada. + **Utilização de computação**: métricas de desempenho que mostram o uso de recursos. + **Logs de execução**: saída do console da função, inclusive quaisquer instruções de registro em log. + **Saída da função**: o resultado exibido pela função. + **Mensagens de erro**: quaisquer erros ou exceções de runtime que ocorreram durante a execução. ## Objeto de teste de conexão O objeto de teste de conexão é um blob binário (de até 40 KB) que representa o evento de conexão TLS que a função processará. Esse objeto contém as informações de certificado e conexão que a função usa para tomar decisões de autenticação. **nota** A estrutura e o formato específicos do objeto de teste de conexão são definidos pelo runtime das funções de conexão do CloudFront. Consulte a documentação do CloudFront Functions ou entre em contato com o AWS Support para obter detalhes sobre a criação de objetos de teste apropriados para seu caso de uso. Depois de criar a função de conexão, você pode: + **Testar a função**: use a funcionalidade de teste no console ou na CLI para validar a função com exemplos de evento de conexão. Para ter mais informações, consulte “Testar funções de conexão”. + **Atualizar a função**: modifique o código e a configuração da função conforme necessário. As funções de conexão no estágio DESENVOLVIMENTO podem ser atualizadas a qualquer momento. + **Publicar a função**: quando a função estiver pronta para produção, publique-a para movê-la do estágio DESENVOLVIMENTO para o ATIVO. Para ter mais informações, consulte “Associar funções de conexão”. + **Associar a uma distribuição**: associe a função publicada à sua distribuição habilitada para mTLS para lidar com conexões ativas. Para ter mais informações, consulte “Associar funções de conexão”. # Associar funções de conexão a distribuições Após a publicação de uma função de conexão no estágio ATIVO, é necessário associá-la a uma distribuição habilitada para mTLS para lidar com conexões ativas. As funções de conexão estão associadas em nível de distribuição, diferentemente das funções de solicitação de visualizador e de resposta ao visualizador, que estão associadas a comportamentos de cache. **Topics** + [ ## Requisitos de associação ](#connection-function-association-requirements) + [ ## Organizar funções com filtros ](#connection-function-organizing-filters) + [ ## Considerações de implantação ](#connection-function-deployment-considerations) ## Requisitos de associação Para associar uma função de conexão a uma distribuição: + A função deve estar no estágio ATIVO. + A distribuição deve ter mTLS habilitada. + A distribuição deve ter um armazenamento confiável válido configurado. + Você pode associar somente uma função de conexão por distribuição. ## Organizar funções com filtros O CloudFront oferece recursos de filtragem para ajudar a organizar e gerenciar funções de conexão: + **Filtro de ID de distribuição**: encontra funções associadas a distribuições específicas. + **Filtro de armazenamento de chave-valor**: encontra funções que usam armazenamentos de chave-valor específicos para pesquisa de dados. + **Filtro de estágio**: lista as funções no estágio DESENVOLVIMENTO ou ATIVO. Use esses filtros ao gerenciar várias funções de conexão em diferentes distribuições ou ambientes de desenvolvimento. ## Considerações de implantação Considere estes fatores ao implantar as funções de conexão: + **Implantação global**: as funções de conexão são implantadas em todos os locais da borda do CloudFront ao redor do mundo, o que pode levar vários minutos. + **Gerenciamento de versões**: cada versão publicada cria uma função ATIVA que substitui a versão anterior + **Estratégia de reversão**: planeje a reversão mantendo as versões operacionais anteriores do código da função. + **Teste na produção**: considere a possibilidade de usar distribuições separadas para ambientes de preparação e produção. # Implementar a revogação de certificados para TLS mútua (visualizador) com o CloudFront Functions e o KeyValueStore É possível funções de conexão do CloudFront com o KeyValueStore para implementar a verificação de revogação de certificados. Isso permite manter uma lista de números de série de certificados revogados e comparar os certificados de cliente com essa lista durante o handshake do TLS. Para implementar a revogação de certificados, os seguintes componentes são necessário: + Uma distribuição configurada com mTLS de visualizador. + Um KeyValueStore contendo números de série de certificados revogados. + Uma função de conexão que consulta o KeyValueStore para verificar o status do certificado. Quando um cliente se conecta, o CloudFront valida o certificado em relação ao armazenamento confiável e, em seguida, executa a função de conexão. A função compara o número de série do certificado com o número de série no KeyValueStore e permite ou nega a conexão. **Topics** + [ # Etapa 1: criar um KeyValueStore para certificados revogados ](create-kvs-revoked-certificates.md) + [ # Etapa 2: criar a função de conexão de revogação ](create-revocation-connection-function.md) + [ # Etapa 3: testar a função de revogação ](test-revocation-function.md) + [ # Etapa 4: associar a função à distribuição ](associate-function-distribution.md) + [ # Cenários avançados de revogação ](advanced-revocation-scenarios.md) # Etapa 1: criar um KeyValueStore para certificados revogados Crie um KeyValueStore para armazenar números de série de certificados revogados que a função de conexão possa verificar durante conexões mTLS. Primeiro, prepare os números de série de certificados revogados no formato JSON: ``` { "data": [ { "key": "ABC123DEF456", "value": "" }, { "key": "789XYZ012GHI", "value": "" } ] } ``` Faça upload desse arquivo JSON em um bucket do S3 e, em seguida, crie o KeyValueStore: ``` aws s3 cp revoked-serials.json s3://your-bucket-name/revoked-serials.json aws cloudfront create-key-value-store \ --name revoked-serials-kvs \ --import-source '{ "SourceType": "S3", "SourceARN": "arn:aws:s3:::your-bucket-name/revoked-serials.json" }' ``` Aguarde até que o KeyValueStore conclua o provisionamento. Verifique o status com: ``` aws cloudfront get-key-value-store --name "revoked-serials-kvs" ``` # Etapa 2: criar a função de conexão de revogação Crie uma função de conexão que compare os números de série de certificado em relação ao KeyValueStore para determinar se os certificados foram revogados. Crie uma função de conexão que compare o número de série dos certificados com os números presentes no KeyValueStore: ``` aws cloudfront create-connection-function \ --name "revocation-control" \ --connection-function-config file://connection-function-config.json \ --connection-function-code file://connection-function-code.txt ``` O arquivo de configuração especifica a associação do KeyValueStore: ``` { "Runtime": "cloudfront-js-2.0", "Comment": "A function that implements revocation control via KVS", "KeyValueStoreAssociations": { "Quantity": 1, "Items": [ { "KeyValueStoreArn": "arn:aws:cloudfront::account-id:key-value-store/kvs-id" } ] } } ``` O código da função de conexão verifica se há certificados revogados no KeyValueStore: ``` import cf from 'cloudfront'; async function connectionHandler(connection) { const kvsHandle = cf.kvs(); // Get parsed client serial number from client certificate const clientSerialNumber = connection.clientCertInfo.serialNumber; // Check KVS to see if serial number exists as a key const serialNumberExistsInKvs = await kvsHandle.exists(clientSerialNumber); // Deny connection if serial number exists in KVS if (serialNumberExistsInKvs) { console.log("Connection denied - certificate revoked"); return connection.deny(); } // Allow connections that don't exist in kvs console.log("Connection allowed"); return connection.allow(); } ``` # Etapa 3: testar a função de revogação Use o console do CloudFront para testar a função de conexão com certificados de exemplo. Acesse a função de conexão no console e use a guia “Testar”. **Teste com certificados de exemplo** 1. Cole um certificado de exemplo no formato PEM na interface de teste. 1. Opcionalmente, especifique um endereço IP de cliente para testar a lógica baseada em IP. 1. Selecione **Detalhes** para visualizar os resultados da execução da função. 1. Analise os logs de execução para verificar a lógica de função. Teste com certificados válidos e revogados para garantir que a função gerencie os dois cenários corretamente. Os logs de execução mostram a saída console.log e quaisquer erros que ocorram durante a execução da função. # Etapa 4: associar a função à distribuição Depois de publicar a função de conexão, associe-a à sua distribuição habilitada para mTLS para ativar a verificação de revogação de certificados. É possível associar a função na página de configurações de distribuição ou na tabela de distribuições associadas à função de conexão. Navegue até suas configurações de distribuição, acesse a seção **Autenticação mútua (mTLS) de visualizador**, selecione a função de conexão e salve as alterações. # Cenários avançados de revogação Com relação a requisitos de revogação de certificados mais complexos, considere estas configurações adicionais: **Topics** + [ ## Converter listas de revogação de certificados (CRLs) no formato do KeyValueStore ](#convert-crl-kvs-format) + [ ## Lidar com várias autoridades de certificação ](#handle-multiple-cas) + [ ## Adicionar dados personalizados aos logs de conexão ](#add-custom-data-logs) + [ ## Gerenciar atualizações de CRL ](#manage-crl-updates) + [ ## Planejar a capacidade do KeyValueStore ](#plan-kvs-capacity) ## Converter listas de revogação de certificados (CRLs) no formato do KeyValueStore Se você tiver um arquivo de lista de revogação de certificados (CRL), poderá convertê-lo no formato JSON do KeyValueStore usando OpenSSL e jq: **Converter CRLs no formato do KeyValueStore** Extraia os números de série do arquivo de CRL: ``` openssl crl -text -noout -in rfc5280_CRL.crl | \ awk '/Serial Number:/ {print $3}' | \ cut -d'=' -f2 | \ sed 's/../&:/g;s/:$//' >> serialnumbers.txt ``` Converta os números de série no formato JSON do KeyValueStore: ``` jq -R -s 'split("\n") | map(select(length > 0)) | {data: map({"key": ., "value": ""})}' \ serialnumbers.txt >> serialnumbers_kvs.json ``` Faça upload do arquivo formatado no S3 e crie o KeyValueStore conforme descrito na Etapa 1. ## Lidar com várias autoridades de certificação Quando sua TrustStore contém várias autoridades de certificação (CAs), inclua as informações do emissor nas chaves do KeyValueStore para evitar conflitos entre certificados de CAs diferentes que possam ter o mesmo número de série. Em cenários com várias CAs, use uma combinação do hash SHA1 do emissor e o número de série como chave: ``` import cf from 'cloudfront'; async function connectionHandler(connection) { const kvsHandle = cf.kvs(); const clientCert = connection.clientCertInfo; // Create composite key with issuer hash and serial number const issuer = clientCert.issuer.replace(/[^a-zA-Z0-9]/g, '').substring(0, 20); const serialno = clientCert.serialNumber; const compositeKey = `${issuer}_${serialno}`; const cert_revoked = await kvsHandle.exists(compositeKey); if (cert_revoked) { console.log(`Blocking revoked cert: ${serialno} from issuer: ${issuer}`); connection.deny(); } else { connection.allow(); } } ``` **nota** O uso do identificador do emissor e do número de série cria chaves mais longas, o que pode reduzir o número total de entradas que é possível armazenar no KeyValueStore. ## Adicionar dados personalizados aos logs de conexão As funções de conexão podem adicionar dados personalizados aos logs de conexão do CloudFront usando o método logCustomData. Isso permite incluir resultados da verificação de revogação, informações do certificado ou outros dados relevantes nos logs. ``` async function connectionHandler(connection) { const kvsHandle = cf.kvs(); const clientSerialNumber = connection.clientCertInfo.serialNumber; const serialNumberExistsInKvs = await kvsHandle.exists(clientSerialNumber); if (serialNumberExistsInKvs) { // Log revocation details to connection logs connection.logCustomData(`REVOKED:${clientSerialNumber}:DENIED`); console.log("Connection denied - certificate revoked"); return connection.deny(); } // Log successful validation connection.logCustomData(`VALID:${clientSerialNumber}:ALLOWED`); console.log("Connection allowed"); return connection.allow(); } ``` Os dados personalizados são limitados a 800 bytes de texto UTF-8 válido. Se você exceder esse limite, o CloudFront truncará os dados até o limite UTF-8 válido mais próximo. **nota** O registro em log de dados personalizados só funciona quando os logs de conexão estão habilitados para a distribuição. Se os logs de conexão não estiverem configurados, o método logCustomData não fará nada. ## Gerenciar atualizações de CRL As autoridades de certificação podem emitir dois tipos de CRL: + **CRLs completas**: contêm uma lista completa de todos os certificados revogados. + **CRLs delta**: listam somente certificados revogados desde a última CRL completa. Para atualizações de CRLs completas, crie um KeyValueStore com os dados atualizados e redirecione a associação da função de conexão para o novo KeyValueStore. Essa abordagem é mais simples do que calcular diferenças e realizar atualizações incrementais. Para atualizações de CRLs delta, use o comando update-keys para adicionar novos certificados revogados ao KeyValueStore existente: ``` aws cloudfront update-key-value-store \ --name "revoked-serials-kvs" \ --if-match "current-etag" \ --put file://delta-revoked-serials.json ``` ## Planejar a capacidade do KeyValueStore O KeyValueStore tem um limite de tamanho total de 5 MB e comporta até 10 milhões de pares de chave-valor. Planeje a capacidade da lista de revogação com base no formato da chave e no tamanho dos dados: + **Somente número de série**: armazenamento eficiente para verificação simples de revogação. + **Identificador do emissor \$1 número de série**: chaves mais longas para ambientes com várias CAs. Para listas de revogação extensas, considere a possibilidade de implementar uma abordagem em camadas em que você mantenha os KeyValueStores separados para diferentes categorias de certificado ou períodos. # Personalização na borda com o Lambda@Edge O Lambda@Edge é uma extensão do AWS Lambda. O Lambda@Edge é um serviço de computação que permite executar funções que personalizam o conteúdo fornecido pelo Amazon CloudFront. É possível criar funções do Node.js ou Python no console do Lambda em uma Região da AWS, Leste dos EUA (Norte da Virgínia). Depois de criar a função, é possível adicionar acionadores usando o console do Lambda ou do CloudFront para que as funções sejam executadas nos locais da AWS mais próximos do visualizador, sem provisionar ou gerenciar servidores. Se desejar, você poderá usar as operações de API do Lambda e do CloudFront para configurar as funções e os acionadores de forma programática. O Lambda@Edge é automaticamente dimensionado, desde algumas solicitações por dia até milhares por segundo. O processamento de solicitações em locais da AWS mais próximos do visualizador, em vez de servidores de origem, reduz significativamente a latência e melhora a experiência do usuário. **nota** O Lambda@Edge não é compatível com solicitações gRPC. Para ter mais informações, consulte [Usar gRPC com distribuições do CloudFront](distribution-using-grpc.md). **Topics** + [ # Como o Lambda@Edge funciona com solicitações e respostas ](lambda-edge-event-request-response.md) + [ # Maneiras de usar o Lambda@Edge ](lambda-edge-ways-to-use.md) + [ # Começar a usar funções do Lambda@Edge (console) ](lambda-edge-how-it-works.md) + [ # Configurar permissões e perfis do IAM para o Lambda@Edge ](lambda-edge-permissions.md) + [ # Escrever e criar uma função do Lambda@Edge ](lambda-edge-create-function.md) + [ # Adicionar acionadores para uma função do Lambda@Edge ](lambda-edge-add-triggers.md) + [ # Testar e depurar as funções do Lambda@Edge ](lambda-edge-testing-debugging.md) + [ # Excluir funções e réplicas do Lambda@Edge ](lambda-edge-delete-replicas.md) + [ # Estrutura de eventos do Lambda@Edge ](lambda-event-structure.md) + [ # Trabalho com solicitações e respostas ](lambda-generating-http-responses.md) + [ # Funções de exemplo do Lambda@Edge ](lambda-examples.md) # Como o Lambda@Edge funciona com solicitações e respostas Ao associar uma distribuição do CloudFront a uma função do Lambda@Edge, o CloudFront intercepta solicitações e respostas nos pontos de presença do CloudFront. É possível executar funções do Lambda quando ocorrem os seguintes eventos do CloudFront: + Quando o CloudFront receber uma solicitação de um visualizador (solicitação do visualizador) + Antes do CloudFront encaminhar uma solicitação para a origem (solicitação da origem) + Quando o CloudFront receber uma resposta da origem (resposta da origem) + Antes de o CloudFront exibir a resposta para o visualizador (resposta ao visualizador). Se você estiver usando o AWS WAF, a solicitação do visualizador do Lambda@Edge será executada após a aplicação de qualquer regra do AWS WAF. Para obter mais informações, consulte [Trabalho com solicitações e respostas](lambda-generating-http-responses.md) e [Estrutura de eventos do Lambda@Edge](lambda-event-structure.md). # Maneiras de usar o Lambda@Edge Há diversos usos para o processamento do Lambda@Edge com sua distribuição do Amazon CloudFront, como os seguintes exemplos: + Uma função do Lambda pode inspecionar cookies e reescrever URLs para que os usuários vejam diferentes versões de um site para testes A/B. + O CloudFront pode retornar objetos diferentes aos visualizadores dependendo do dispositivo que estão usando, verificando o cabeçalho `User-Agent`, que inclui informações sobre os dispositivos. Por exemplo, o CloudFront pode retornar imagens diferentes com base no tamanho da tela do seu dispositivo. Da mesma forma, a função pode considerar o valor do cabeçalho `Referer` e fazer com que o CloudFront retorne imagens com a menor resolução disponível a bots. + Ou você pode verificar cookies para outros critérios. Por exemplo, em um site de varejo que vende roupas, se você usar cookies para indicar a cor de uma jaqueta escolhida por um usuário, a função do Lambda poderá alterar a solicitação para que o CloudFront retorne a imagem de uma jaqueta na cor selecionada. + Uma função do Lambda pode gerar respostas HTTP quando ocorrerem os eventos da solicitação de origem ou do visualizador do CloudFront. + Uma função pode inspecionar cabeçalhos ou tokens de autorização e inserir um cabeçalho para controlar o acesso ao seu conteúdo antes de o CloudFront encaminhar uma solicitação para a origem. + Uma função do Lambda também pode fazer chamadas de rede para recursos externos a fim de confirmar as credenciais do usuário ou obter conteúdo adicional para personalizar uma resposta. Consulte mais informações, incluindo exemplos de código em [Funções de exemplo do Lambda@Edge](lambda-examples.md). Consulte mais informações sobre como configurar o Lambda@Edge no console em [Tutorial: criar uma função básica do Lambda@Edge (console)](lambda-edge-how-it-works-tutorial.md). # Começar a usar funções do Lambda@Edge (console) Com o Lambda@Edge, é possível usar acionadores do CloudFront para invocar uma função do Lambda. Quando você associa uma distribuição do CloudFront a uma função do Lambda, o CloudFront [intercepta solicitações e respostas](https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html) nos pontos de presença do CloudFront e executa a função. As funções do Lambda podem melhorar a segurança ou personalizar informações próximas aos visualizadores para melhorar a performance. A lista a seguir fornece uma visão geral básica de como criar e usar as funções do Lambda com o CloudFront. **Visão geral: como criar e usar funções do Lambda com o CloudFront** 1. Crie uma função do Lambda na região Leste dos EUA (N. da Virgínia). 1. Salve e publique uma versão numerada da função. Para alterar a função, edite a versão \$1LATEST da função na região Leste dos EUA (Norte da Virgínia). A seguir, antes de configurá-la para funcionar com o CloudFront, publique uma nova versão numerada. 1. Associe a função a uma distribuição do CloudFront e ao comportamento de cache. Depois, especifique um ou mais eventos do CloudFront (*triggers*) que fazem com que a função seja executada. Por exemplo, você pode criar um trigger para que a função seja executada quando o CloudFront receber uma solicitação de um visualizador. 1. Quando você cria um acionador, o Lambda cria réplicas da função em locais da AWS em todo o mundo. **dica** Consulte mais informações em [criar e atualizar funções](lambda-edge-create-function.md), [a estrutura de eventos](lambda-event-structure.md) e [adicionar acionadores do CloudFront](lambda-edge-add-triggers.md). Você também pode encontrar mais ideias e obter amostras de código em [Funções de exemplo do Lambda@Edge](lambda-examples.md). Consulte um tutorial detalhado no seguinte tópico: **Topics** + [ # Tutorial: criar uma função básica do Lambda@Edge (console) ](lambda-edge-how-it-works-tutorial.md) # Tutorial: criar uma função básica do Lambda@Edge (console) Esse tutorial mostra como começar a usar o Lambda@Edge criando e configurando um exemplo de função do Node.js que é executado no CloudFront. Este exemplo adiciona cabeçalhos de segurança HTTP a uma resposta quando o CloudFront recupera um arquivo. (Isso pode melhorar a segurança e a privacidade de um site.) Você não precisa de seu próprio site para esse tutorial. No entanto, ao optar por criar sua própria solução do Lambda@Edge, você segue etapas semelhantes e escolhe entre as mesmas opções. **Topics** + [ ## Etapa 1: cadastrar-se com uma Conta da AWS ](#lambda-edge-how-it-works-tutorial-AWS) + [ ## Etapa 2: Criar uma distribuição do CloudFront ](#lambda-edge-how-it-works-tutorial-cloudfront) + [ ## Etapa 3: criar sua função ](#lambda-edge-how-it-works-tutorial-create-function) + [ ## Etapa 4: adicionar um acionador do CloudFront para executar a função ](#lambda-edge-how-it-works-tutorial-add-trigger) + [ ## Etapa 5: verificar se a função é executada ](#lambda-edge-how-it-works-tutorial-verify) + [ ## Etapa 6: solução de problemas ](#lambda-edge-how-it-works-tutorial-troubleshoot) + [ ## Etapa 7: apagar recursos de exemplo ](#lambda-edge-how-it-works-tutorial-cleanup-resources) + [ ## Informações relacionadas ](#lambda-edge-how-it-works-tutorial-resources) ## Etapa 1: cadastrar-se com uma Conta da AWS Se ainda não tiver feito isso, cadastre-se para uma Conta da AWS. Para obter mais informações, consulte [Inscrever-se para uma Conta da AWS](setting-up-cloudfront.md#sign-up-for-aws). ## Etapa 2: Criar uma distribuição do CloudFront Antes de criar o exemplo de função do Lambda@Edge, você deve ter um ambiente do CloudFront para trabalhar com o que inclui uma origem para servir conteúdo. Para este exemplo, crie uma distribuição do CloudFront que use um bucket do Amazon S3 como a origem da distribuição. Se já tiver um ambiente para usar, você pode ignorar esta etapa. **Como criar uma distribuição do CloudFront com uma origem do Amazon S3** 1. Crie um bucket do Amazon S3 com um ou dois arquivos, como arquivos de imagem, para exemplo de conteúdo. Para obter ajuda, siga as etapas em [Fazer upload do conteúdo no Amazon S3](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html#GettingStartedUploadContent). Certifique-se de ter definido permissões para conceder acesso público de leitura aos objetos do seu bucket. 1. Crie uma distribuição do CloudFront e adicione o bucket do S3 como uma origem, seguindo as etapas em [Criar uma distribuição na Web do CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html#GettingStartedCreateDistribution). Se você já tiver uma distribuição, pode adicionar o bucket como origem para essa distribuição. **dica** Anote seu ID de distribuição. Posteriormente neste tutorial, ao adicionar um acionador do CloudFront para a função, você deve escolher o ID da distribuição em uma lista suspensa; por exemplo, `E653W22221KDDL`. ## Etapa 3: criar sua função Nesta etapa, você cria uma função do Lambda, começando com um modelo de esquema no console do Lambda. A função adiciona o código para atualizar os cabeçalhos de segurança na distribuição do CloudFront. **Como criar uma função do Lambda** 1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). **Importante** Verifique se você está na Região da AWS **US-East-1 (Norte da Virgínia)** (**us-east-1**). Você deve estar nessa região para criar as funções do Lambda@Edge. 1. Escolha **Create function**. 1. Na página **Create function (Criar função)**, escolha **Use a blueprint (Usar um esquema)** e filtre os esquemas do CloudFront inserindo **cloudfront** no campo de pesquisa. **nota** Os esquemas do CloudFront estão disponíveis somente na região **US-East-1 (N. Virgínia) (Leste dos EUA-1 (Norte da Virgínia))** (**us-east-1**). 1. Escolha o esquema **Modify HTTP response header** (Modificar cabeçalho de resposta HTTP) como modelo para sua função. 1. Insira as seguintes informações sobre sua função: + **Nome da função**: insira um nome para a função. + **Perfil de execução**: escolha como definir as permissões para a função. Para usar o modelo básico de política de permissões recomendado do Lambda@Edge, selecione **Criar uma função de modelos de política da AWS**. + **Nome do perfil**: insira um nome para o perfil que o modelo de política cria. + **Modelos de política**: o Lambda adiciona automaticamente o modelo de política **Permissões básicas do Lambda@Edge** porque você escolheu um esquema do CloudFront como a base da função. Esse modelo de política adiciona permissões de função de execução que permitem que o CloudFront execute sua função do Lambda para você em locais do CloudFront em todo o mundo. Para obter mais informações, consulte [Configurar permissões e perfis do IAM para o Lambda@Edge](lambda-edge-permissions.md). 1. Selecione **Criar função** na parte inferior da página. 1. No painel **Implantar no Lambda@Edge** exibido, escolha **Cancelar**. (Para este tutorial, você deve modificar o código da função antes de implantá-la no Lambda@Edge.) 1. Role para baixo até a seção **Code source** (Origem do código) da página. 1. Substitua o código do modelo por uma função que modifica os cabeçalhos de segurança que sua origem retorna. Por exemplo, você pode usar um código semelhante ao seguinte: ``` 'use strict'; export const handler = (event, context, callback) => { //Get contents of response const response = event.Records[0].cf.response; const headers = response.headers; //Set new headers headers['strict-transport-security'] = [{key: 'Strict-Transport-Security', value: 'max-age= 63072000; includeSubdomains; preload'}]; headers['content-security-policy'] = [{key: 'Content-Security-Policy', value: "default-src 'none'; img-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'"}]; headers['x-content-type-options'] = [{key: 'X-Content-Type-Options', value: 'nosniff'}]; headers['x-frame-options'] = [{key: 'X-Frame-Options', value: 'DENY'}]; headers['x-xss-protection'] = [{key: 'X-XSS-Protection', value: '1; mode=block'}]; headers['referrer-policy'] = [{key: 'Referrer-Policy', value: 'same-origin'}]; //Return modified response callback(null, response); }; ``` 1. Selecione **File** (Arquivo), **Save** (Salvar) para salvar o código atualizado. 1. Escolha **Implantar**. Prossiga para a próxima seção para adicionar um trigger do CloudFront para executar a função. ## Etapa 4: adicionar um acionador do CloudFront para executar a função Agora que você tem uma função do Lambda para atualizar os cabeçalhos de segurança, configure o trigger do CloudFront que executa a função para adicionar cabeçalhos em qualquer resposta recebida pelo CloudFront da origem para sua distribuição. **Como configurar o trigger do CloudFront para sua função** 1. No console do Lambda, na página de **Function overview** (Visão geral da função) da função, escolha **Add trigger** (Adicionar acionador). 1. Em **Trigger configuration** (Configuração do acionador), escolha **CloudFront**. 1. Escolha **Implantar no Lambda@Edge**. 1. No painel **Implantar no Lambda@Edge**, em **Configurar acionador do CloudFront**, insira as seguintes informações: + **Distribuição**: o ID de distribuição do CloudFront a ser associado à função. Na lista suspensa, escolha o ID da distribuição. + **Comportamento de cache**: o comportamento de cache para usar com o acionador. Para este exemplo, deixe o valor definido como **\$1**, que indica o comportamento de cache padrão da distribuição. Para obter mais informações, consulte [Configurações de comportamento de cache](DownloadDistValuesCacheBehavior.md)[Referência de configurações de todas as distribuições](distribution-web-values-specify.md) no tópico. + **Evento do CloudFront**: o acionador que especifica quando a função é executada. Queremos que os cabeçalhos de segurança da função sejam executados sempre que o CloudFront retornar uma resposta da origem. Na lista suspensa, escolha **Resposta da origem**. Para obter mais informações, consulte [Adicionar acionadores para uma função do Lambda@Edge](lambda-edge-add-triggers.md). 1. Marque a caixa de seleção **Confirmar implantação no Lambda@Edge**. 1. Escolha **Deploy (Implantar)** para adicionar o trigger e replicar a função para os locais da AWS em todo o mundo. 1. Aguarde até que a função seja replicada. Isso normalmente demora vários minutos. Você pode verificar se a replicação foi concluída [acessando o console do CloudFront](https://console.aws.amazon.com/cloudfront/v4/home) e visualizando a distribuição. Aguarde o status de distribuição mudar de **Implantando** para uma data e hora, o que significa que sua função foi replicada. Para verificar se a função funciona, siga as etapas na próxima seção. ## Etapa 5: verificar se a função é executada Agora que você criou a função do Lambda e configurou um trigger para executá-la em uma distribuição do CloudFront, verifique se a função está realizando o que você espera. Neste exemplo, verificamos os cabeçalhos HTTP que o CloudFront retorna, para garantir que os cabeçalhos de segurança estejam adicionados. **Para verificar se a sua função do Lambda@Edge adiciona cabeçalhos de segurança** 1. Em um navegador, insira o URL para um arquivo no seu bucket do S3. Por exemplo, você pode usar um URL semelhante a `https://d111111abcdef8.cloudfront.net/image.jpg`. Para obter mais informações sobre o nome de domínio do CloudFront a ser usado no arquivo URL, consulte [Personalizar o formato do URL para arquivos no CloudFront](LinkFormat.md). 1. Abra a barra de ferramentas do desenvolvedor da Web do navegador. Por exemplo, em sua janela do navegador Chrome, abra o menu de contexto (clique com o botão direito do mouse) e escolha **Inspect (Inspecionar)**. 1. Escolha a guia **Network**. 1. Recarregue a página para visualizar sua imagem e, em seguida, escolha uma solicitação HTTP no painel esquerdo. Você vê os cabeçalhos HTTP exibidos em um painel separado. 1. Verifique a lista de cabeçalhos HTTP para verificar se os cabeçalhos de segurança esperados são incluídos na lista. Por exemplo, você poderá ver cabeçalhos semelhantes aos mostrados na captura de tela a seguir: ![\[Os cabeçalhos de HTTP listam com os cabeçalhos de segurança em destaque esperados.\]](http://docs.aws.amazon.com/pt_br/AmazonCloudFront/latest/DeveloperGuide/images/lambda-at-edge-security-headers-list.png) Se os cabeçalhos de segurança forem incluídos na sua lista de cabeçalhos, excelente\$1 Você criou com êxito sua primeira função do Lambda@Edge. Se o CloudFront retornar erros ou se houver outros problemas, continue na próxima etapa para solucionar os problemas. ## Etapa 6: solução de problemas Se o CloudFront retornar erros ou não adicionar os cabeçalhos de segurança conforme esperado, você poderá investigar a execução da função verificando o CloudWatch Logs. Certifique-se de usar os logs armazenados no local da AWS que estão mais próximos do local em que a função é executada. Por exemplo, se você visualizar o arquivo de Londres, tente alterar a região no console do CloudWatch para EU (Londres). **Como examinar os CloudWatch Logs para sua função do Lambda@Edge** 1. Faça login no Console de gerenciamento da AWS e abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Altere a **Region (Região)** para o local que é mostrado quando você visualiza o arquivo no navegador. Aqui é onde a função está sendo executada. 1. No painel esquerdo, selecione **Logs** para visualizar os logs da sua distribuição. Para obter mais informações, consulte [Monitorar métricas do CloudFront com o Amazon CloudWatch](monitoring-using-cloudwatch.md). ## Etapa 7: apagar recursos de exemplo Se você criar um bucket do Amazon S3 e a distribuição do CloudFront apenas para este tutorial, exclua os recursos da AWS alocados para não acumular mais cobranças. Depois que você excluir os recursos da AWS, qualquer conteúdo que você adicionou não ficará mais disponível. **Tarefas** + [Exclua o bucket do S3](#lambda-edge-how-it-works-tutorial-delete-bucket) + [Excluir a função Lambda](#lambda-edge-how-it-works-tutorial-delete-function) + [Exclua a distribuição do CloudFront](#lambda-edge-how-it-works-tutorial-delete-distribution) ### Exclua o bucket do S3 Antes de excluir o bucket do Amazon S3, verifique se o log está desativado para o bucket. Caso contrário, a AWS continuará gravando logs para o bucket à medida que você o excluir. **Para desabilitar o registro em log para um bucket** 1. Abra o console do Amazon S3 em [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. Selecione o bucket e escolha **Properties (Propriedades)**. 1. Em **Properties (Propriedades)**, escolha **Logging (Registro)**. 1. Desmarque a caixa de seleção **Enabled (Habilitado)**. 1. Escolha **Save (Salvar)**. Agora, você pode excluir seu bucket. Para obter mais informações, consulte [Exclusão de um bucket ](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-bucket.html) no *Guia do usuário do console do Amazon Simple Storage Service*. ### Excluir a função Lambda Para ter instruções sobre como excluir a associação da função do Lambda e, opcionalmente, a própria função, consulte [Excluir funções e réplicas do Lambda@Edge](lambda-edge-delete-replicas.md). ### Exclua a distribuição do CloudFront Antes de excluir uma distribuição do CloudFront, você deve desabilitá-la. Uma distribuição desabilitada deixa de ser funcional e não acumula encargos. É possível habilitar uma distribuição desabilitada a qualquer momento. Depois que você excluir uma distribuição desabilitada, ela deixará de estar disponível. **Como desabilitar e excluir uma distribuição do CloudFront** 1. Abra o console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. Selecione a distribuição que você deseja desabilitar e escolha **Disable (Desabilitar)**. 1. Quando a confirmação for solicitada, escolha **Yes, Disable (Sim, desabilitar)**. 1. Selecione a distribuição desabilitada e escolha **Delete (Excluir)**. 1. Quando a confirmação for solicitada, escolha **Yes, Delete (Sim, excluir)**. ## Informações relacionadas Agora que você tem uma ideia básica de como as funções do Lambda@Edge funcionam, saiba mais lendo o seguinte: + [Funções de exemplo do Lambda@Edge](lambda-examples.md) + [Práticas recomendadas de design do Lambda@Edge](https://aws.amazon.com/blogs/networking-and-content-delivery/lambdaedge-design-best-practices/) + [Reducing Latency and Shifting Compute to the Edge with Lambda@Edge](https://aws.amazon.com/blogs/networking-and-content-delivery/reducing-latency-and-shifting-compute-to-the-edge-with-lambdaedge/) # Configurar permissões e perfis do IAM para o Lambda@Edge Para configurar o Lambda@Edge, é necessário ter as seguintes permissões e perfis do IAM para o AWS Lambda: + [Permissões do IAM](#lambda-edge-permissions-required): essas permissões autorizam você a criar a função do Lambda e a associá-la à distribuição do CloudFront. + [Perfil de execução da função do Lambda](#lambda-edge-permissions-function-execution) (perfil do IAM): as entidades principais do serviço do Lambda assumem esse perfil para executar a função. + [Perfis vinculados ao serviço para o Lambda@Edge](#using-service-linked-roles-lambda-edge): os perfis vinculados ao serviço permitem que Serviços da AWS específicos repliquem funções do Lambda para Regiões da AWS e habilitem o CloudWatch para usar arquivos de log do CloudFront. ## Permissões do IAM necessárias para associar funções do Lambda às distribuições do CloudFront Além das permissões do IAM necessárias para o Lambda, você precisa das seguintes permissões para associar as funções do Lambda às distribuições do CloudFront: + `lambda:GetFunction`: concede permissão para recebimento de informações de configuração para a função do Lambda e de um URL pré-assinado para baixar um arquivo `.zip` que contém a função. + `lambda:EnableReplication*`: concede permissão à política de recurso para que o serviço de replicação do Lambda possa obter o a configuração e o código da função. + `lambda:DisableReplication*`: concede permissão à política de recurso para que o serviço de replicação do Lambda possa excluir a função. **Importante** É necessário adicionar o asterisco (`*`) ao final das ações `lambda:EnableReplication*` e `lambda:DisableReplication*`. + Para o recurso, especifique o ARN da versão da função que você deseja executar quando ocorrer um evento do CloudFront, conforme mostrado no seguinte exemplo: `arn:aws:lambda:us-east-1:123456789012:function:TestFunction:2` + `iam:CreateServiceLinkedRole`: concede permissão para criar um perfil vinculado ao serviço que o Lambda@Edge usa para replicar funções do Lambda no CloudFront. Depois que você configurar o Lambda@Edge pela primeira vez, o perfil vinculado ao serviço será criado automaticamente para você. Não é necessário adicionar essa permissão a outras distribuições que usam o Lambda@Edge. + `cloudfront:UpdateDistribution` ou `cloudfront:CreateDistribution`: concede permissão para atualizar ou criar uma distribuição. Para saber mais, consulte os seguintes tópicos: + [Identity and Access Management para Amazon CloudFront](security-iam.md) + [Permissões de acesso a recursos do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#lambda-intro-execution-role) no *Guia do desenvolvedor do AWS Lambda* ## Função de execução de função para primários de serviço É necessário criar um perfil do IAM que as entidades principais do serviço `lambda.amazonaws.com` e `edgelambda.amazonaws.com` possam assumir ao executarem a função. **dica** Ao criar a função no console do Lambda, você pode optar por criar um perfil de execução usando um modelo de política da AWS. Essa etapa adiciona *automaticamente* as permissões necessárias do Lambda@Edge para executar a função. Consulte a [Etapa 5 do tutorial Criação de uma função do Lambda@Edge simples](lambda-edge-how-it-works-tutorial.md#lambda-edge-how-it-works-tutorial-create-function). Consulte mais informações sobre como criar um perfil do IAM manualmente em [Criar funções e anexar políticas (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions_create-policies.html) no *Guia do usuário do IAM*. **Example Exemplo: política de confiança do perfil** É possível adicionar esse perfil na guia **Relação de confiança** no console do IAM. Não adicione essa política na guia **Permissões**. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "lambda.amazonaws.com", "edgelambda.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` Consulte mais informações sobre as permissões que você precisa conceder ao perfil de execução em [Permissões de acesso a recursos do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#lambda-intro-execution-role) no *Guia do desenvolvedor do AWS Lambda*. **Observações** Por padrão, sempre que um evento do CloudFront aciona uma função do Lambda, os dados são gravados no CloudWatch Logs. Se você quiser usar esses logs, a função de execução precisará de permissão para registrar dados no CloudWatch Logs. É possível usar o AWSLambdaBasicExecutionRole predefinido para conceder permissão ao perfil de execução. Para obter mais informações sobre o CloudWatch Logs, consulte [Logs de funções de borda](edge-functions-logs.md). Se o código da função do Lambda acessar outros recursos da AWS, como a leitura de um objeto em um bucket do S3, o perfil de execução precisará de permissão para executar essa ação. ## Funções vinculadas ao serviço para o Lambda@Edge O Lambda@Edge usa [perfis vinculados ao serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role) do IAM. Uma função vinculada ao serviço é um tipo exclusivo de função do IAM vinculada diretamente a um serviço. As funções vinculadas a serviços são predefinidas pelo serviço e incluem todas as permissões de que ele precisa para chamar outros serviços da AWS em seu nome. O Lambda@Edge usa os seguintes perfis vinculados ao serviço do IAM: + **AWSServiceRoleForLambdaReplicator** – o Lambda@Edge usa essa função para permitir que ele mesmo replique funções para Regiões da AWS. Quando você adiciona um acionador do Lambda@Edge ao CloudFront pela primeira vez, um perfil chamado AWSServiceRoleForLambdaReplicator é criado automaticamente para permitir que o Lambda@Edge replique funções para Regiões da AWS. Esse perfil é necessário para usar as funções do Lambda@Edge. O ARN do perfil AWSServiceRoleForLambdaReplicator é semelhante a este exemplo: `arn:aws:iam::123456789012:role/aws-service-role/replicator.lambda.amazonaws.com/AWSServiceRoleForLambdaReplicator` + **AWSServiceRoleForCloudFrontLogger** – o CloudFront usa esse perfil para enviar arquivos de log ao CloudWatch. É possível usar arquivos de log para depurar erros de validação do Lambda@Edge. O perfil AWSServiceRoleForCloudFrontLogger é criado automaticamente quando você adiciona a associação da função do Lambda@Edge para permitir que o CloudFront envie arquivos de log de erros do Lambda@Edge ao CloudWatch. O ARN para a função AWSServiceRoleForCloudFrontLogger é semelhante a: `arn:aws:iam::account_number:role/aws-service-role/logger.cloudfront.amazonaws.com/AWSServiceRoleForCloudFrontLogger` Uma função vinculada a serviço facilita a configuração e o uso do Lambda@Edge, pois você não precisa adicionar manualmente as permissões necessárias. Lambda@Edge define as permissões de suas funções vinculadas ao serviço e apenas Lambda@Edge pode assumir as funções. As permissões definidas incluem a política de confiança e a política de permissões. Não é possível anexar a política de permissões a nenhuma outra entidade do IAM. Você deve remover todos os recursos do CloudFront ou do Lambda@Edge associados para poder excluir a função vinculada ao serviço. Isso ajuda a proteger seus recursos do Lambda@Edge de modo que você não remova um perfil vinculado ao serviço que ainda seja necessário para acessar os recursos ativos. Para obter mais informações sobre funções vinculadas ao serviço, consulte [Funções vinculadas ao serviço do CloudFront](security_iam_service-with-iam.md#security_iam_service-with-iam-roles-service-linked). ### Permissões de função vinculada ao serviço para o Lambda@Edge O Lambda@Edge usa duas funções vinculadas a serviços: **AWSServiceRoleForLambdaReplicator** e **AWSServiceRoleForCloudFrontLogger**. As seções a seguir descrevem as permissões para cada uma dessas funções. **Contents** + [ #### Permissões de função vinculada ao serviço para o replicador do Lambda ](#slr-permissions-lambda-replicator) + [ #### Permissões de função vinculada ao serviço para o CloudFront Logger ](#slr-permissions-cloudfront-logger) #### Permissões de função vinculada ao serviço para o replicador do Lambda Essa função vinculada ao serviço permite que o Lambda replique funções do Lambda@Edge para Regiões da AWS. O perfil vinculado ao serviço AWSServiceRoleForLambdaReplicator confia no serviço `replicator.lambda.amazonaws.com` para presumir o perfil. A política de permissões da função permite que o Lambda@Edge conclua as seguintes ações nos recursos especificados: + `lambda:CreateFunction` na `arn:aws:lambda:*:*:function:*` + `lambda:DeleteFunction` na `arn:aws:lambda:*:*:function:*` + `lambda:DisableReplication` na `arn:aws:lambda:*:*:function:*` + `iam:PassRole` na `all AWS resources` + `cloudfront:ListDistributionsByLambdaFunction` na `all AWS resources` #### Permissões de função vinculada ao serviço para o CloudFront Logger Esse perfil vinculado ao serviço permite que o CloudFront envie arquivos de log por push ao CloudWatch para que seja possível depurar erros de validação do Lambda@Edge. O perfil vinculado ao serviço AWSServiceRoleForCloudFrontLogger confia no serviço `logger.cloudfront.amazonaws.com` para presumir o perfil. A política de permissões do perfil permite que o Lambda@Edge conclua as seguintes ações no recurso `arn:aws:logs:*:*:log-group:/aws/cloudfront/*` especificado: + `logs:CreateLogGroup` `` + `logs:CreateLogStream` + `logs:PutLogEvents` Você deve configurar permissões para permitir que uma entidade do IAM (como um usuário, grupo ou função) exclua uma função vinculada ao serviço do Lambda@Edge. Para obter mais informações, consulte [Permissões do perfil vinculado a serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions) no *Guia do usuário do IAM*. ### Criação de funções vinculadas ao serviço para o Lambda@Edge Normalmente, não é necessário criar manualmente as funções vinculadas a serviços para o Lambda@Edge. O serviço cria as funções automaticamente nas seguintes situações: + Quando você cria um acionador pela primeira vez, o serviço cria o perfil AWSServiceRoleForLambdaReplicator (caso ele ainda não exista). Esse perfil permite que o Lambda replique funções do Lambda@Edge para Regiões da AWS. Se você excluir a função vinculada ao serviço, a função será criada novamente quando você adicionar um novo gatilho para o Lambda@Edge em uma distribuição. + Quando você atualiza ou cria uma distribuição do CloudFront que tem uma associação ao Lambda@Edge, o serviço cria o perfil AWSServiceRoleForCloudFrontLogger (caso o perfil ainda não exista). Esse perfil permite que o CloudFront envie arquivos de log ao CloudWatch. Se você excluir a função vinculada ao serviço, ela será criada novamente quando você atualizar ou criar uma distribuição do CloudFront que tenha uma associação ao Lambda@Edge. Para criar manualmente esses perfis vinculados ao serviço, execute os seguintes comandos da AWS Command Line Interface (AWS CLI): **Para criar a função AWSServiceRoleForLambdaReplicator** + Execute o comando a seguir. ``` aws iam create-service-linked-role --aws-service-name replicator.lambda.amazonaws.com ``` **Para criar a função AWSServiceRoleForCloudFrontLogger** + Execute o comando a seguir. ``` aws iam create-service-linked-role --aws-service-name logger.cloudfront.amazonaws.com ``` ### Edição de funções vinculadas ao serviço do Lambda@Edge O Lambda@Edge não permite que você edite os perfis vinculados ao serviço AWSServiceRoleForLambdaReplicator ou AWSServiceRoleForCloudFrontLogger. Depois que o serviço criar um perfil vinculado ao serviço, você não poderá alterar o nome dele, pois várias entidades podem fazer referência a ele. No entanto, é possível usar o IAM para editar a descrição da função. Para saber mais, consulte [Editar um perfil vinculado ao serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role) no *Guia do usuário do IAM*. ### Regiões da AWS compatíveis com perfis vinculados ao serviço do Lambda@Edge O CloudFront é compatível com as funções vinculadas ao serviço do Lambda@Edge nas seguintes Regiões da AWS: + Leste dos EUA (Norte da Virgínia) – `us-east-1` + Leste dos EUA (Ohio) – `us-east-2` + US West (N. California) – `us-west-1` + US West (Oregon) – `us-west-2` + Asia Pacific (Mumbai) – `ap-south-1` + Asia Pacific (Seoul) – `ap-northeast-2` + Asia Pacific (Singapore) – `ap-southeast-1` + Asia Pacific (Sydney) – `ap-southeast-2` + Asia Pacific (Tokyo) – `ap-northeast-1` + Europe (Frankfurt) – `eu-central-1` + Europe (Ireland) – `eu-west-1` + Europe (London) – `eu-west-2` + South America (São Paulo) – `sa-east-1` # Escrever e criar uma função do Lambda@Edge Para usar o Lambda@Edge, você *escreve* o código da função do AWS Lambda. Para ajudar você a escrever funções do Lambda@Edge, consulte os seguintes recursos: + [Estrutura de eventos do Lambda@Edge](lambda-event-structure.md): entenda a estrutura de eventos a ser usada com o Lambda@Edge. + [Funções de exemplo do Lambda@Edge](lambda-examples.md): funções de exemplo, como testes A/B e geração de um redirecionamento HTTP. O modelo de programação para usar o Node.js com o Lambda@Edge é o mesmo que para usar o Lambda em uma Região da AWS. Consulte mais informações em [Criar funções do Lambda com Node.js](https://docs.aws.amazon.com/lambda/latest/dg/lambda-nodejs.html) ou em [Criar funções do Lambda com Python](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html) no *Guia do desenvolvedor do AWS Lambda*. Na função do Lambda@Edge, inclua o parâmetro `callback` e retorne o objeto aplicável para eventos de solicitação ou resposta: + **Eventos de solicitação**: inclua o objeto `cf.request` na resposta. Se você estiver gerando uma resposta, inclua o objeto `cf.response` na resposta. Para obter mais informações, consulte [Gerar respostas de HTTP em acionadores da solicitação](lambda-generating-http-responses.md#lambda-generating-http-responses-in-requests). + **Eventos de resposta**: inclua o objeto `cf.response` na resposta. Depois de escrever seu próprio código ou usar um dos exemplos, você cria a função no Lambda. Para criar uma função ou editar uma existente, consulte os seguintes tópicos: **Topics** + [ # Criar uma função do Lambda@Edge ](lambda-edge-create-in-lambda-console.md) + [ # Editar uma função do Lambda ](lambda-edge-edit-function.md) Depois de criar a função no Lambda, você configura o Lambda para executar a função com base em eventos específicos do CloudFront, chamados *acionadores*. Para obter mais informações, consulte [Adicionar acionadores para uma função do Lambda@Edge](lambda-edge-add-triggers.md). # Criar uma função do Lambda@Edge Para configurar o AWS Lambda para executar funções do Lambda baseadas em eventos do CloudFront, siga este procedimento. **Para criar uma função Lambda@Edge** 1. Faça login no Console de gerenciamento da AWS e abra o console AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). 1. Se você já tiver uma ou mais funções do Lambda, escolha **Create function (Criar função)**. Se você não tiver nenhuma função, escolha **Get Started Now**. 1. Na lista Region (Região) na parte superior da página, escolha **US East (N. Virginia) (Leste dos EUA (Norte da Virgínia))**. 1. Crie uma função usando seu próprio código ou crie uma função começando com um esquema do CloudFront. + Para criar uma função usando seu próprio código, escolha **Author from scratch**. + Para exibir uma lista de esquemas do CloudFront, insira **cloudfront** no campo de filtro e selecione **Enter**. Se você encontrar um esquema que deseja usar, selecione o nome dele. 1. Na seção **Basic information**, especifique os seguintes valores: 1. **Nome**: insira um nome para a função. 1. **Função**: para começar rapidamente, escolha **Criar função com base em modelo(s)**. Também é possível selecionar **Escolher uma função existente** ou **Criar uma função personalizada** e siga as instruções para concluir as informações dessa seção. 1. **Nome da função**: insira um nome para a função. 1. **Modelos de política**: escolha **Permissões básicas do Edge Lambda**. 1. Se você escolheu **Author from scratch** na etapa 4, vá para a etapa 7. Se você escolheu um esquema na etapa 4, a seção **cloudfront** permitirá que você crie um trigger, que associa essa função a um cache em uma distribuição do CloudFront e a um evento do CloudFront. Recomendamos que você escolha **Remove (Remover)** nesse momento, para que não haja um trigger para a função quando ela for criada. Você poderá adicionar gatilhos mais tarde. **dica** Recomendamos que você teste e depure a função antes de adicionar acionadores. Se você adicionar um acionador agora, a função será executada assim que for criada e concluirá a replicação para locais da AWS em todo o mundo, e a distribuição correspondente será implantada. 1. Escolha **Create function**. O Lambda cria duas versões da sua função: \$1LATEST e Versão 1. Você pode editar apenas a versão \$1LATEST, mas o console inicialmente exibirá a Versão 1. 1. Para editar a função, escolha **Version 1** na parte superior da página, sob o ARN da função. Na guia **Versions**, escolha **\$1LATEST**. (Se você deixou a função e depois retornou a ela, o título do botão será **Qualifiers**.) 1. Na guia **Configuration**, escolha o **Code entry type** aplicável. Em seguida, siga as instruções para editar ou fazer upload do seu código. 1. Em **Runtime**, escolha o valor com base no código da função. 1. Na seção **Tags**, adicione todas as tags aplicáveis. 1. Escolha **Actions** e, em seguida, **Publish new version**. 1. Insira uma descrição para a nova versão da função. 1. Escolha **Publish**. 1. Teste e depure a função. Consulte mais informações sobre como testar no console do Lambda em [Invocar a função do Lambda usando o console](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html#get-started-invoke-manually) no *Guia do desenvolvedor do AWS Lambda*. 1. Quando você estiver pronto para que a função seja executada em eventos do CloudFront, publique outra versão e edite-a para adicionar triggers. Para obter mais informações, consulte [Adicionar acionadores para uma função do Lambda@Edge](lambda-edge-add-triggers.md). # Editar uma função do Lambda Depois de criar uma função do Lambda@Edge, você pode usar o console do Lambda para editá-la. **Observações** A versão original é identificada como \$1 LATEST. Você só pode editar a versão \$1LATEST. Cada vez que você editar a versão \$1LATEST, deverá publicar uma nova versão numerada. Você não pode criar triggers para \$1LATEST. Ao publicar uma nova versão de uma função, o Lambda não copiará automaticamente os triggers da versão anterior para a nova versão. Você deve reproduzir os triggers para a nova versão. Quando você adiciona um trigger de um evento do CloudFront a uma função, se já houver um trigger para a mesma distribuição, comportamento de cache e evento para uma versão anterior da mesma função, o Lambda excluirá o trigger da versão anterior. Depois de fazer atualizações em uma distribuição do CloudFront, como a adição de triggers, você precisará aguardar a propagação das alterações para os pontos de presença para que as funções especificadas nos triggers funcionem. **Para editar uma função do Lambda** 1. Faça login no Console de gerenciamento da AWS e abra o console AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). 1. Na lista Region (Região) na parte superior da página, escolha **US East (N. Virginia) (Leste dos EUA (Norte da Virgínia))**. 1. Na lista de funções, selecione o nome da função. Por padrão, o console exibirá a versão \$1LATEST. Você pode visualizar versões anteriores (escolha **Qualifiers**), mas só poderá editar \$1LATEST. 1. Na guia **Code (Código)**, em **Code entry type (Tipo de entrada de código)**, escolha editar o código no navegador, fazer upload de um arquivo .zip ou fazer upload de um arquivo do Amazon S3. 1. Selecione **Save** ou **Save and test**. 1. Escolha **Actions** e **Publish new version**. 1. Na caixa de diálogo **Publish new version from \$1LATEST**, insira uma descrição da nova versão. Essa descrição aparece na lista de versões, junto com um número de versão gerado automaticamente. 1. Escolha **Publish**. A nova versão se torna automaticamente a versão mais recente. O número da versão aparece em **Versão** no canto superior esquerdo da página. **nota** Se ainda não tiver adicionado acionadores para a função, consulte [Adicionar acionadores para uma função do Lambda@Edge](lambda-edge-add-triggers.md). 1. Selecione a guia **Triggers**. 1. Escolha **Add trigger**. 1. Na caixa de diálogo **Add trigger (Adicionar trigger)**, selecione a caixa pontilhada e escolha **CloudFront**. **nota** Se você já tiver criado um ou mais triggers para uma função, o CloudFront será o serviço padrão. 1. Especifique os seguintes valores para indicar quando você deseja que a função Lambda seja executada. 1. **ID da distribuição**: escolha o ID da distribuição à qual você deseja adicionar o acionador. 1. **Comportamento de cache**: escolha o comportamento de cache que especifica os objetos nos quais você deseja executar a função. 1. **Evento do CloudFront**: escolha o evento do CloudFront que faz com que a função seja executada. 1. **Ativar o trigger e replicar**: marque essa caixa de seleção para que o Lambda replique a função para Regiões da AWS globalmente. 1. Selecione **Enviar**. 1. Para adicionar mais triggers a essa função, repita as etapas de 10 a 13. Consulte mais informações sobre como testar e depurar a função no console do Lambda em [Invocar a função do Lambda usando o console](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html#get-started-invoke-manually) no *Guia do desenvolvedor do AWS Lambda*. Quando você estiver pronto para que a função seja executada em eventos do CloudFront, publique outra versão e edite-a para adicionar triggers. Para obter mais informações, consulte [Adicionar acionadores para uma função do Lambda@Edge](lambda-edge-add-triggers.md). # Adicionar acionadores para uma função do Lambda@Edge Gatilho do Lambda@Edge é uma combinação de distribuição do CloudFront, comportamento de cache e evento que faz com que a função seja executada. Por exemplo, você pode criar um trigger que faça com que a função seja executada quando o CloudFront receber uma solicitação de um visualizador para um determinado comportamento do cache de sua configuração da distribuição. Você pode especificar um ou mais acionadores do CloudFront. **dica** Ao criar uma distribuição do CloudFront, você especifica as configurações que informam ao CloudFront como responder ao receber diferentes solicitações. As configurações padrão são chamadas de *comportamento de cache padrão *para a distribuição. Você pode configurar comportamentos de cache adicionais que definem como o CloudFront responde em circunstâncias específicas, por exemplo, quando recebe uma solicitação para um tipo de arquivo específico. Para obter mais informações, consulte [Configurações de comportamento de cache](DownloadDistValuesCacheBehavior.md). Ao criar uma função do Lambda pela primeira vez, é possível especificar apenas *um* acionador. É possível adicionar mais acionadores à mesma função mais tarde usando o console do Lambda ou editando a distribuição no console do CloudFront. + O console do Lambda funciona bem para adicionar mais acionadores a uma função da mesma distribuição do CloudFront. + O console do CloudFront pode ser melhor para adicionar acionadores a várias distribuições, pois é mais fácil encontrar a distribuição que você deseja atualizar. Também é possível atualizar outras configurações do CloudFront ao mesmo tempo. **Topics** + [ # Eventos do CloudFront que podem acionar uma função do Lambda@Edge ](lambda-cloudfront-trigger-events.md) + [ # Escolher o evento para acionar a função ](lambda-how-to-choose-event.md) + [ # Adicionar acionadores a uma função do Lambda@Edge ](lambda-edge-add-triggers-console.md) # Eventos do CloudFront que podem acionar uma função do Lambda@Edge Para cada comportamento do cache em uma distribuição do Amazon CloudFront, é possível adicionar até quatro acionadores (associações) que fazem com que uma função do Lambda seja executada quando ocorrem eventos específicos do CloudFront. Os triggers de CloudFront podem ser baseados em um dos quatro eventos do CloudFront, conforme mostrado no diagrama a seguir. ![\[Gráfico conceitual que mostra como eventos acionadores do CloudFront para funções do Lambda integram-se ao CloudFront.\]](http://docs.aws.amazon.com/pt_br/AmazonCloudFront/latest/DeveloperGuide/images/cloudfront-events-that-trigger-lambda-functions.png) Os eventos do CloudFront que podem ser usados para acionar as funções do Lambda@Edge são os seguintes: **Solicitação do visualizador** A função é executada quando o CloudFront recebe uma solicitação de um visualizador antes de ele verificar se o objeto solicitado está no cache do CloudFront. A função não é executada nos seguintes casos: + Ao buscar uma página de erro personalizada. + Quando o CloudFront redireciona automaticamente uma solicitação HTTP para HTTPS (quando o valor de [Política de protocolo do visualizador](DownloadDistValuesCacheBehavior.md#DownloadDistValuesViewerProtocolPolicy) é **Redirecionar HTTP para HTTPS**). **Solicitação da origem** A função é executada *apenas* quando o CloudFront encaminha uma solicitação para a origem. Quando o objeto solicitado está no cache do CloudFront, a função não é executada. **Resposta da origem** A função é executada depois que o CloudFront recebe uma resposta da origem e antes de ele armazenar o objeto em cache na resposta. Observe que a função é executada mesmo se um erro for retornado da origem. A função não é executada nos seguintes casos: + Quando o arquivo solicitado está no cache do CloudFront e não expirou. + Quando a resposta é gerada de uma função acionada por um evento de solicitação de origem. **Resposta do visualizador** A função é executada antes de retornar o arquivo solicitado para o visualizador. Observe que a função é executada independentemente de o arquivo já estar no cache do CloudFront. A função não é executada nos seguintes casos: + Quando a origem retorna um código de status HTTP 400 ou posterior. + Quando uma página de erro personalizada é retornada. + Quando a resposta é gerada de uma função acionada por um evento de solicitação do visualizador. + Quando o CloudFront redireciona automaticamente uma solicitação HTTP para HTTPS (quando o valor de [Política de protocolo do visualizador](DownloadDistValuesCacheBehavior.md#DownloadDistValuesViewerProtocolPolicy) é **Redirecionar HTTP para HTTPS**). Ao adicionar vários triggers para o mesmo comportamento do cache, você pode usá-los para executar a mesma função ou executar funções diferentes para cada trigger. Você também pode associar a mesma função para mais de uma distribuição. **nota** Quando um evento do CloudFront aciona a execução de uma função do Lambda, a função deve ser concluída *antes* que o CloudFront possa continuar. Por exemplo, se uma função do Lambda for acionada por um evento de solicitação do visualizador do CloudFront, este não retornará uma resposta ao visualizador nem encaminhará a solicitação à origem enquanto a execução da função do Lambda não for concluída. Isso significa que cada solicitação que aciona uma função do Lambda aumenta a latência da solicitação. Portanto, é conveniente executar a função o mais rapidamente possível. # Escolher o evento para acionar a função Ao decidir qual evento do CloudFront você deseja usar para acionar uma função do Lambda, considere: **Quero que o CloudFront armazene em cache objetos que são alterados por uma função do Lambda** Para armazenar em cache um objeto que foi modificado por uma função do Lambda para que o CloudFront possa fornecer o objeto no local da borda na próxima vez que ele for solicitado, use os eventos de *solicitação da origem* ou de *resposta da origem*. Isso reduz a carga na origem, a latência de solicitações subsequentes e o custo de chamar o Lambda@Edge em solicitações subsequentes. Por exemplo, para adicionar, remover ou alterar os cabeçalhos dos objetos retornados pela origem e quiser que o CloudFront armazene o resultado em cache, use o evento de resposta da origem. **Quero que a função seja executada em todas as solicitações** Se quiser executar a função para todas as solicitações que o CloudFront recebe para a distribuição, use os eventos de *solicitação do visualizador* ou de *resposta do visualizador*. Os eventos de solicitação e de resposta da origem ocorrem somente quando um objeto solicitado não é armazenado em cache em um ponto de presença, e o CloudFront encaminha uma solicitação para a origem. **Quero que a função altere a chave de cache** Para alterar um valor que está sendo usado como base para o armazenamento em cache, use o evento de *solicitação do visualizador*. Por exemplo, se uma função altera o URL para incluir a abreviação de um idioma no caminho (por exemplo, porque o usuário escolheu o idioma em uma lista suspensa), use o evento de solicitação do visualizador: + **URL na solicitação do visualizador**: https://example.com/en/index.html + **URL quando a solicitação é proveniente de um endereço IP na Alemanha**: https://example.com/de/index.html O evento de solicitação do visualizador também pode ser usada se você estiver armazenando em cache com base em cookies ou cabeçalhos de solicitação. Se a função alterar cookies ou cabeçalhos, configure o CloudFront para encaminhar a parte aplicável da solicitação à origem. Para saber mais, consulte os seguintes tópicos: + [Conteúdo em cache com base em cookies](Cookies.md) + [Conteúdo em cache com base nos cabeçalhos de solicitação](header-caching.md) **A função afeta a resposta da origem** Para alterar a solicitação de maneira a afetar a resposta da origem, use o evento de *solicitação de origem*. Normalmente, a maioria dos eventos de solicitação do visualizador não é encaminhada para a origem. O CloudFront responde a uma solicitação com um objeto que já está no cache da borda. Se a função alterar a solicitação com base em um evento de solicitação de origem, o CloudFront armazenará em cache a resposta à solicitação de origem alterada. # Adicionar acionadores a uma função do Lambda@Edge É possível usar o console do AWS Lambda ou o console do Amazon CloudFront para adicionar um acionador à função do Lambda@Edge. **Importante** É possível criar acionadores somente para versões numeradas da função (não para **\$1LATEST**). ------ #### [ Lambda console ] **Como adicionar acionadores para eventos do CloudFront a uma função do Lambda@Edge** 1. Faça login no Console de gerenciamento da AWS e abra o console AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). 1. Na lista Region (Região) na parte superior da página, escolha **US East (N. Virginia) (Leste dos EUA (Norte da Virgínia))**. 1. Na página **Functions**, selecione o nome da função à qual você deseja adicionar triggers. 1. Na página de **Function overview** (Visão geral da função), escolha a guia **Versions** (Versões). 1. Escolha a versão à qual você deseja adicionar triggers. Depois de escolher uma versão, o nome do botão mudará para **Version: \$1LATEST** ou para **Version:** *número da versão*. 1. Selecione a guia **Triggers**. 1. Escolha **Add trigger**. 1. Em **Configuração do gatilho**, escolha **Selecione uma origem**, insira **cloudfront** e selecione **CloudFront**. **nota** Se você já tiver criado um ou mais triggers, o CloudFront será o serviço padrão. 1. Especifique os seguintes valores para indicar quando você deseja que a função Lambda seja executada. 1. **Distribuição**: escolha a distribuição à qual você deseja adicionar o acionador. 1. **Comportamento de cache**: escolha o comportamento de cache que especifica os objetos nos quais você deseja executar a função. **nota** Se você especificar `*` para o comportamento do cache, a função do Lambda será implantada no comportamento do cache padrão. 1. **Evento do CloudFront**: escolha o evento do CloudFront que faz com que a função seja executada. 1. **Incluir corpo**: marque essa caixa de seleção se quiser acessar o corpo da solicitação na função. 1. **Confirmar implantação no Lambda@Edge**: marque essa caixa de seleção para que o AWS Lambda replique a função para Regiões da AWS globalmente. 1. Escolha **Adicionar**. A função começará a processar solicitações para os eventos do CloudFront especificados quando a distribuição atualizada do CloudFront for implantada. Para determinar se uma distribuição foi implantada, escolha **Distributions** no painel de navegação. Quando uma distribuição estiver implantada, o valor da coluna **Status** da distribuição mudará de **Deploying** (Implantando) para a data e hora da implantação. ------ #### [ CloudFront console ] **Como adicionar acionadores para eventos do CloudFront a uma função do Lambda@Edge** 1. Obtenha o Nome de região da Amazon (ARN) da função do Lambda à qual você deseja adicionar triggers: 1. Faça login no Console de gerenciamento da AWS e abra o console AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). 1. Na lista de regiões na parte superior da página, escolha **US East (N. Virginia) (Leste dos EUA (Norte da Virgínia))**. 1. Na lista de funções, selecione o nome da função à qual você deseja adicionar triggers. 1. Na página **Function overview** (Visão geral da função), escolha a guia **Versions** (Versões) e escolha a versão numerada à qual você deseja adicionar acionadores. 1. Selecione **Copy ARN** (Copiar ARN) para copiar o código para a área de transferência. O ARN da função do Lambda tem a seguinte aparência: `arn:aws:lambda:us-east-1:123456789012:function:TestFunction:2` O número no final (**2**, no exemplo) é o número da versão da função. 1. Abra o console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. Na lista de distribuição, selecione o ID da distribuição à qual você deseja adicionar triggers. 1. Escolha a guia **Behaviors**. 1. Selecione o comportamento do cache ao qual você deseja adicionar acionadores e, em seguida, escolha **Edit** (Editar). 1. Em **Function associations** (Associações da função), na lista **Function type** (Tipo da função), escolha **Lambda@Edge** para quando a função deve ser executada: para solicitações do visualizador, respostas do visualizador, solicitações da origem ou respostas da origem. Para obter mais informações, consulte [Escolher o evento para acionar a função](lambda-how-to-choose-event.md). 1. Na caixa de texto **Function ARN / Name** (Função ARN/Nome), cole o ARN da função do Lambda que você deseja executar quando o evento escolhido ocorrer. Esse é o valor copiado do console do Lambda. 1. Selecione **Include body** (Incluir corpo) se quiser acessar o corpo da solicitação na sua função. Se deseja apenas substituir o corpo da solicitação, você não precisa selecionar essa opção. 1. Para executar a mesma função em outros tipos de evento, repita as etapas 6 e 7. 1. Escolha **Salvar alterações**. 1. Para adicionar acionadores em outros comportamentos de cache para essa distribuição, repita as etapas 5 a 10. A função começará a processar solicitações para os eventos do CloudFront especificados quando a distribuição atualizada do CloudFront for implantada. Para determinar se uma distribuição foi implantada, escolha **Distributions** no painel de navegação. Quando uma distribuição estiver implantada, o valor da coluna **Status** da distribuição mudará de **Deploying** (Implantando) para a data e hora da implantação. ------ # Testar e depurar as funções do Lambda@Edge É importante testar o código da sua função do Lambda@Edge independentemente para ter certeza de que ele conclui a tarefa pretendida e fazer testes de integração para garantir que a função funcione corretamente com o CloudFront. Durante o teste de integração ou depois que a função foi implantada, talvez seja necessário depurar erros do CloudFront, como erros HTTP 5xx. Os erros podem ser uma resposta inválida retornada da função do Lambda, erros de execução quando a função é acionada ou erros devido a uma limitação de execução do serviço do Lambda. As seções neste tópico compartilham estratégias para determinar qual tipo de falha é o problema e, em seguida, as etapas que você pode realizar para corrigir o problema. **nota** Ao revisar os arquivos de log ou as métricas do CloudWatch durante a solução de erros, esteja ciente de que eles são exibidos ou armazenados na Região da AWS mais próxima do local em que a função foi executada. Portanto, se você tiver um site ou aplicação web com usuários no Reino Unido e, por exemplo, tiver uma função do Lambda associada à distribuição, deverá alterar a região para visualizar as métricas ou os arquivos de log do CloudWatch para a Região da AWS Londres. Para obter mais informações, consulte [Determinar a região do Lambda@Edge](#lambda-edge-testing-debugging-determine-region). **Topics** + [ ## Testar as funções do Lambda@Edge ](#lambda-edge-testing-debugging-test-function) + [ ## Identificar erros de função do Lambda@Edge no CloudFront ](#lambda-edge-identifying-function-errors) + [ ## Solução de problemas de respostas inválidas de funções do Lambda@Edge (erros de validação) ](#lambda-edge-testing-debugging-troubleshooting-invalid-responses) + [ ## Solução de problemas de erros de execução de funções do Lambda@Edge ](#lambda-edge-testing-debugging-execution-errors) + [ ## Determinar a região do Lambda@Edge ](#lambda-edge-testing-debugging-determine-region) + [ ## Determinar se a sua conta envia logs ao CloudWatch ](#lambda-edge-testing-debugging-cloudwatch-logs-enabled) ## Testar as funções do Lambda@Edge Há duas etapas para testar a função do Lambda: teste autônomo e teste de integração. **Testar a funcionalidade autônoma** Antes de adicionar a função do Lambda ao CloudFront, teste a funcionalidade primeiro usando os recursos de teste no console do Lambda ou usando outros métodos. Consulte mais informações sobre como testar no console do Lambda em [Invocar a função do Lambda usando o console](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html#get-started-invoke-manually) no *Guia do desenvolvedor do AWS Lambda*. **Testar a operação da função no CloudFront** É importante concluir o teste de integração, quando a função está associada a uma distribuição e é executada com base em um evento do CloudFront. Certifique-se de que a função seja acionada para o evento correto e retorne uma resposta válida e correta para o CloudFront. Por exemplo, verifique se a estrutura do evento está correta, se apenas os cabeçalhos válidos estão incluídos e assim por diante. Ao iterar os testes de integração com a função no console do Lambda, consulte as etapas do tutorial do Lambda@Edge à medida que você modifica o código ou altera o trigger do CloudFront que chama a função. Por exemplo, verifique se você está trabalhando em uma versão numerada da função, conforme descrito nesta etapa do tutorial: [Etapa 4: adicionar um acionador do CloudFront para executar a função](lambda-edge-how-it-works-tutorial.md#lambda-edge-how-it-works-tutorial-add-trigger). Ao fazer alterações e implantá-las, lembre-se de que a função e os triggers atualizados do CloudFront levarão vários minutos para serem replicados em todas as regiões. Isso geralmente leva alguns minutos, mas pode demorar até 15 minutos. Você pode verificar se a replicação foi concluída acessando o console do CloudFront e visualizando a distribuição. **Como verificar se a implantação da replicação foi concluída** 1. Abra o console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. Escolha o nome da distribuição. 1. Verifique o status de distribuição para mudar de **In Progress** (Em progresso) para **Deployed** (Implantado), o que significa que sua função foi replicada. Em seguida, siga as etapas na próxima seção para verificar se a função funciona. Esteja ciente de que o teste no console valida apenas a lógica da sua função e não aplica cotas de serviço (anteriormente conhecidas como limites) específicas do Lambda@Edge. ## Identificar erros de função do Lambda@Edge no CloudFront Depois de verificar se a lógica da função funciona corretamente, você ainda poderá ver erros HTTP 5xx quando a função for executada no CloudFront. Os erros HTTP 5xx podem ser retornados por vários motivos, que incluem erros ou outros problemas da função do Lambda no CloudFront. + Ao usar as funções do Lambda@Edge, é possível usar gráficos no console do CloudFront para ajudar a identificar o que está causando o erro e corrigi-lo. Por exemplo, é possível ver se os erros HTTP 5xx são causados pelo CloudFront ou pelas funções do Lambda e, no caso de funções específicas, visualizar os arquivos de log relacionados para investigar o problema. + Para solucionar a maioria dos erros HTTP do CloudFront, consulte as etapas de solução de problemas no seguinte tópico: [Solucionar problemas de códigos de status de resposta de erros no CloudFront](troubleshooting-response-errors.md). ### O que causa erros na função do Lambda@Edge no CloudFront Existem vários motivos pelos quais uma função do Lambda pode causar um erro HTTP 5xx, e as etapas de solução de problemas que você deve seguir dependem do tipo de erro. Os erros podem ser categorizados assim: **Um erro de execução de função do Lambda** Ocorre um erro de execução quando o CloudFront não obtém uma resposta do Lambda porque existem exceções não tratadas na função ou há um erro no código. Por exemplo, se o código incluir um retorno de chamada (erro). **Uma resposta inválida da função do Lambda é retornada ao CloudFront** Após a execução da função, o CloudFront recebe uma resposta do Lambda. Um erro será retornado se a estrutura do objeto da resposta não estiver em conformidade com o [Estrutura de eventos do Lambda@Edge](lambda-event-structure.md) ou se a resposta contiver cabeçalhos inválidos ou outros campos inválidos. **A execução no CloudFront é limitada devido às cotas de serviço do Lambda (anteriormente conhecidas como limites)** O serviço do Lambda limita as execuções em cada região e retornará um erro se você exceder a cota. Para obter mais informações, consulte [Cotas do Lambda@Edge](cloudfront-limits.md#limits-lambda-at-edge). ### Como determinar o tipo de falha Para ajudar a decidir onde se concentrar na depuração de erros e solucionar os problemas retornados pelo CloudFront, é útil identificar por que o CloudFront está retornando um erro HTTP. Para iniciar a busca, você pode usar os gráficos fornecidos na seção **Monitoring** (Monitoramento) do console do CloudFront no Console de gerenciamento da AWS. Para obter mais informações sobre como visualizar gráficos na seção **Monitoring (Monitoramento)** no console do CloudFront, consulte [Monitorar métricas do CloudFront com o Amazon CloudWatch](monitoring-using-cloudwatch.md). Os seguintes gráficos podem ser especialmente úteis ao verificar se os erros estão sendo retornados por origens ou por uma função do Lambda, e para restringir o tipo de problema quando se trata de um erro de função do Lambda. **Gráfico de taxas de erro** Um dos gráficos que você pode visualizar na guia **Overview (Visão geral)** para cada uma das suas distribuições é um gráfico **Error rates (Taxas de erro)**. Esse gráfico exibe a taxa de erros como porcentagem do total de solicitações que chegam à sua distribuição. O gráfico mostra o total de taxa de erros, total de erros 4xx, total de erros 5xx e total de erros 5xx provenientes de funções Lambda. Com base no tipo de erro e volume, você pode executar etapas para investigar e solucionar o problema. ![\[Gráfico de taxas de erro na distribuição do CloudFront\]](http://docs.aws.amazon.com/pt_br/AmazonCloudFront/latest/DeveloperGuide/images/Distribution-error-rate-pct-full.png) + Se você encontrar erros do Lambda, você poderá investigar mais detalhadamente, observando os tipos específicos de erros retornados pela função. A guia **Lambda@Edge errors (Erros do Lambda@Edge)** inclui gráficos que categorizam os erros por tipo de função para ajudar a identificar o problema em uma função específica. + Se encontrar erros do CloudFront, você poderá solucionar e trabalhar para corrigir os erros de origem ou alterar a configuração do CloudFront. Para obter mais informações, consulte [Solucionar problemas de códigos de status de resposta de erros no CloudFront](troubleshooting-response-errors.md). **Gráficos de erros de execução e repostas de funções inválidas** A guia **Lambda@Edge errors (Erros do Lambda@Edge)** inclui gráficos que categorizam os erros do Lambda@Edge em uma distribuição específica, por tipo. Por exemplo, um grafo mostra todos os erros de execução por Região da AWS. Para facilitar a solução de problemas, você pode procurar problemas específicos ao abrir e examinar os arquivos de log para funções específicas por região. **Como visualizar os arquivos de log de uma função específica por região** 1. Na guia **Erros do Lambda@Edge**, em **Funções associadas do Lambda@Edge**, escolha o nome da função e selecione **Visualizar métricas**. 1. Em seguida, na página com o nome da função, no canto superior direito, selecione **Visualizar logs da função** e escolha uma região. Por exemplo, se você encontrar problemas no grafo **Erros** para a região Oeste dos EUA (Oregon), escolha essa região na lista suspensa. Isso abrirá o console do Amazon CloudWatch. 1. No console do CloudWatch dessa região, em **Fluxos de log**, escolha um fluxo de log para visualizar os eventos da função. Também leia as seguintes seções neste capítulo para obter mais recomendações sobre como solucionar problemas e corrigir erros. **Gráfico de limitações** A guia **Lambdga@Edge errors (Erros do Lambda@Edge)** também inclui um gráfico de **Throttles (Limitações)**. Ocasionalmente, o serviço Lambda limita as invocações de função por região quando a cota (anteriormente conhecida como limite) de simultaneidade regional é atingida. Se você encontrar um erro limit exceeded (limite excedido), isso significa que a função atingiu uma cota que o serviço Lambda impõe para execuções em uma região. Para obter mais informações, incluindo como solicitar um aumento na cota, consulte [Cotas do Lambda@Edge](cloudfront-limits.md#limits-lambda-at-edge). ![\[Grafo de controle de utilização para a execução da função do Lambda@Edge.\]](http://docs.aws.amazon.com/pt_br/AmazonCloudFront/latest/DeveloperGuide/images/Lambda-throttles-page.png) Para obter um exemplo de como usar essas informações para solucionar erros HTTP, consulte [Quatro etapas para depurar a entrega de conteúdo na AWS](https://aws.amazon.com/blogs/networking-and-content-delivery/four-steps-for-debugging-your-content-delivery-on-aws/). ## Solução de problemas de respostas inválidas de funções do Lambda@Edge (erros de validação) Se você identificar que o problema é um erro de validação do Lambda, a função do Lambda poderá estar retornando uma resposta inválida ao CloudFront. Siga as orientações nesta seção para tomar medidas para analisar a função e garantir que a resposta esteja de acordo com os requisitos do CloudFront. O CloudFront valida a resposta de uma função do Lambda de duas maneiras: + **A resposta do Lambda deve estar de acordo com a estrutura de objeto necessária.** Exemplos de estruturas de objeto inválidas incluem o seguinte: JSON não analisável, campos obrigatórios ausentes e um objeto inválido na resposta. Para mais informações, consulte o [Estrutura de eventos do Lambda@Edge](lambda-event-structure.md). + **A resposta deve incluir apenas valores de objeto válidos.** Um erro ocorrerá se a resposta incluir um objeto válido, mas tiver valores sem suporte. Os exemplos incluem o seguinte: adicionar ou atualizar cabeçalhos permitidos ou somente leitura (consulte [Restrições das funções de borda](edge-functions-restrictions.md)), exceder o tamanho máximo do corpo (consulte *Restrições sobre o tamanho da resposta gerada* no tópico [Erros](lambda-generating-http-responses.md#lambda-generating-http-responses-errors) do Lambda@Edge) e caracteres ou valores inválidos (consulte o [Estrutura de eventos do Lambda@Edge](lambda-event-structure.md)). Quando o Lambda retorna uma resposta inválida ao CloudFront, as mensagens de erro são gravados em arquivos de log que o CloudFront envia por push ao CloudWatch na região em que a função do Lambda foi executada. O comportamento padrão é enviar os arquivos de log ao CloudWatch quando há uma resposta inválida. No entanto, se você tiver associado uma função do Lambda ao CloudFront antes do lançamento dessa funcionalidade, talvez ela não esteja habilitada para a função. Para obter mais informações, consulte *Determinar se a conta envia logs por push ao CloudWatch*, mais adiante neste tópico. O CloudFront envia arquivos de log à região correspondente ao local onde a função foi executada, no grupo de logs associado à sua distribuição. Os grupos de log têm o seguinte formato: `/aws/cloudfront/LambdaEdge/DistributionId`, em que *DistributionId* é o ID da distribuição. Para determinar a região na qual você pode encontrar os arquivos de log do CloudWatch, consulte *Determinar a região do Lambda@Edge* mais adiante neste tópico. Se for possível reproduzir o erro, você poderá criar uma nova solicitação que resulte no erro e encontrar o id da solicitação em uma resposta do CloudFront com falha (cabeçalho `X-Amz-Cf-Id`) para localizar uma única falha nos arquivos de log. A entrada do arquivo de log inclui informações que podem ajudar a identificar porque o erro está sendo retornado, e também lista o id da solicitação do Lambda correspondente, para que você possa analisar a causa raiz no contexto de uma única solicitação. Se um erro for intermitente, você poderá usar os logs de acesso do CloudFront para encontrar o id de uma solicitação que falhou e depois pesquisar as mensagens de erro correspondentes nos CloudWatch Logs. Para mais informações, consulte a seção anterior, *Determinar o tipo de falha*. ## Solução de problemas de erros de execução de funções do Lambda@Edge Se o problema for um erro de execução do Lambda, poderá ser útil criar instruções de registro em log para funções do Lambda, gravar mensagens nos arquivos de log CloudWatch que monitoram a execução da função no CloudFront e determinar se ela está funcionando conforme o esperado. Depois, você pode pesquisar essas instruções nos arquivos de log do CloudWatch para verificar se a sua função está funcionando. **nota** Mesmo que você não tenha alterado a função do Lambda@Edge, as atualizações no ambiente de execução da função do Lambda podem afetá-la e um erro de execução poderá ser retornado. Para obter informações sobre como testar e migrar para uma versão mais recente, consulte [Próximas atualizações no AWS Lambda e no ambiente de execução do AWS Lambda@Edge](https://aws.amazon.com/blogs/compute/upcoming-updates-to-the-aws-lambda-execution-environment/). ## Determinar a região do Lambda@Edge Para ver as regiões em que a função do Lambda@Edge está recebendo tráfego, visualize os gráficos das métricas da função no console do CloudFron no Console de gerenciamento da AWS. As métricas são exibidas para cada região da AWS. Na mesma página, é possível escolher uma região e visualizar os arquivos de log para essa região a fim de investigar problemas. Revise os arquivos de log do CloudWatch na região correta da AWS para ver os arquivos de log criados quando o CloudFront executou a função do Lambda. Para obter mais informações sobre como visualizar gráficos na seção **Monitoring (Monitoramento)** no console do CloudFront, consulte [Monitorar métricas do CloudFront com o Amazon CloudWatch](monitoring-using-cloudwatch.md). ## Determinar se a sua conta envia logs ao CloudWatch Por padrão, o CloudFront habilita o registro em log de respostas de função inválidas do Lambda e envia por push os arquivos de log para o CloudWatch usando uma das [Funções vinculadas ao serviço para o Lambda@Edge](lambda-edge-permissions.md#using-service-linked-roles-lambda-edge). Se você tiver funções do Lambda@Edge adicionadas ao CloudFront antes do lançamento do recurso de log de respostas de função inválidas do Lambda, o registro em log será habilitado quando você atualizar a configuração do Lambda@Edge, por exemplo, adicionando um trigger do CloudFront. É possível verificar se o envio por push dos arquivos de log ao CloudWatch está habilitado para a conta, fazendo o seguinte: + **Verifique se os logs aparecem no CloudWatch**: examine na região em que a função do Lambda@Edge foi executada. Para obter mais informações, consulte [Determinar a região do Lambda@Edge](#lambda-edge-testing-debugging-determine-region). + **Determine se o perfil vinculado ao serviço relacionado existe na sua conta do IAM**: você deve ter o perfil do IAM `AWSServiceRoleForCloudFrontLogger` na sua conta. Para obter mais informações sobre esse perfil, consulte [Funções vinculadas ao serviço para o Lambda@Edge](lambda-edge-permissions.md#using-service-linked-roles-lambda-edge). # Excluir funções e réplicas do Lambda@Edge Só é possível excluir uma função do Lambda@Edge quando as réplicas da função tiverem sido excluídas pelo CloudFront. As réplicas de uma função do Lambda são excluídas automaticamente nas seguintes situações: + Depois de remover a última associação da função de todas as distribuições do CloudFront. Se mais de uma distribuição usar uma função, as réplicas serão excluídas somente depois que a associação da função for removida da última distribuição. + Depois que você excluir a última distribuição com a qual a função estava associada. Geralmente, as réplicas são excluídas dentro de algumas horas. Não é possível excluir manualmente réplicas de função do Lambda@Edge. Isso ajuda a evitar que uma réplica ainda em uso seja excluída, o que resultaria em um erro. **Atenção** Não crie aplicações que usem réplicas de função do Lambda@Edge fora do CloudFront. Essas réplicas são excluídas quando suas associações a distribuições são removidas ou quando as próprias distribuições são excluídas. A réplica da qual um aplicativo externo depende poderá ser removida sem aviso prévio, fazendo com que ele falhe. **Como excluir uma associação de função do Lambda@Edge de uma distribuição do CloudFront** 1. Faça login no Console de gerenciamento da AWS e abra o console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. Escolha o ID da distribuição com a associação da função do Lambda@Edge que deseja excluir. 1. Escolha a guia **Behaviors**. 1. Selecione o comportamento de cache que possui a associação de função do Lambda@Edge que deseja excluir e selecione **Edit** (Editar). 1. Em **Function associations** (Associações da função), **Function type** (Tipo da função), escolha **No association** (Nenhuma associação) para excluir a associação da função do Lambda@Edge. 1. Escolha **Salvar alterações**. Depois de excluir uma associação de função do Lambda@Edge de uma distribuição do CloudFront, você pode, opcionalmente, excluir a função Lambda ou a versão da função do AWS Lambda. Aguarde algumas horas após excluir a associação da função para que as réplicas da função do Lambda@Edge possam ser limpas. Depois disso, é possível excluir a função usando o console do Lambda, a AWS CLI, a API do Lambda ou um AWS SDK. Também é possível excluir uma *versão* específica de uma função do Lambda se ela não tiver nenhuma distribuição do CloudFront associada a ela. Depois de remover todas as associações de uma versão de função do Lambda, aguarde algumas horas. Depois, você pode excluir a versão da função. # Estrutura de eventos do Lambda@Edge Os tópicos a seguir descrevem os objetos de eventos de solicitação e resposta que o CloudFront passa para uma função do Lambda@Edge quando ela é acionada. **Topics** + [ ## Seleção de origem dinâmica ](#lambda-event-content-based-routing) + [ ## Eventos de solicitação ](#lambda-event-structure-request) + [ ## Eventos de resposta ](#lambda-event-structure-response) ## Seleção de origem dinâmica Você pode usar [o padrão do caminho em um comportamento de cache](DownloadDistValuesCacheBehavior.md#DownloadDistValuesPathPattern) para rotear as solicitações para uma origem, de acordo com o caminho e o nome do objeto solicitado, como `images/*.jpg`. Usando o Lambda@Edge, você também pode rotear as solicitações para uma origem com base em outras características, como os valores nos cabeçalhos de solicitação. Essa seleção de origem dinâmica pode ser útil de várias maneiras. Por exemplo, você pode distribuir solicitações em origens em diferentes áreas geográficas para ajudar com o balanceamento de carga global. Ou você pode seletivamente rotear solicitações para diferentes origens que cada servir uma determinada função: manuseio de bot, otimização de SEO, autenticação, e assim por diante. Para obter exemplos de código que demonstram como usar esse recurso, consulte [Seleção de origem dinâmica baseada em conteúdo: exemplos](lambda-examples.md#lambda-examples-content-based-routing-examples). No evento de solicitação de origem do CloudFront, o objeto `origin` na estrutura do evento contém informações sobre a origem para a qual a solicitação seria roteada, de acordo com o padrão de caminho. Você pode atualizar os valores no objeto `origin` para rotear uma solicitação para outra origem. Quando você atualiza o objeto `origin`, não precisa definir a origem na distribuição. Também é possível substituir um objeto de origem do Amazon S3 por um objeto de origem personalizado e vice-versa. No entanto, só é possível especificar uma única origem por solicitação; uma origem personalizada ou uma origem do Amazon S3, mas não ambas. ## Eventos de solicitação Os tópicos a seguir mostram a estrutura do objeto que o CloudFront passa para uma função do Lambda para [eventos de solicitação do visualizador e da origem](lambda-cloudfront-trigger-events.md). Estes exemplos mostram uma solicitação `GET` sem corpo. Após os exemplos, está uma lista de todos os campos possíveis em eventos de solicitação de visualizador e origem. **Topics** + [ ### Exemplo de solicitação de visualizador ](#example-viewer-request) + [ ### Exemplo de solicitação de origem ](#example-origin-request) + [ ### Campos de eventos de solicitação ](#request-event-fields) ### Exemplo de solicitação de visualizador O exemplo a seguir mostra um objeto de evento de solicitação de visualizador. ``` { "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-request", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.66.0" } ], "accept": [ { "key": "accept", "value": "*/*" } ] }, "method": "GET", "querystring": "", "uri": "/" } } } ] } ``` ### Exemplo de solicitação de origem O exemplo a seguir mostra um objeto de evento de solicitação de origem. ``` { "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "origin-request", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "x-forwarded-for": [ { "key": "X-Forwarded-For", "value": "203.0.113.178" } ], "user-agent": [ { "key": "User-Agent", "value": "Amazon CloudFront" } ], "via": [ { "key": "Via", "value": "2.0 2afae0d44e2540f472c0635ab62c232b.cloudfront.net (CloudFront)" } ], "host": [ { "key": "Host", "value": "example.org" } ], "cache-control": [ { "key": "Cache-Control", "value": "no-cache" } ] }, "method": "GET", "origin": { "custom": { "customHeaders": {}, "domainName": "example.org", "keepaliveTimeout": 5, "path": "", "port": 443, "protocol": "https", "readTimeout": 30, "responseCompletionTimeout": 30, "sslProtocols": [ "TLSv1", "TLSv1.1", "TLSv1.2" ] } }, "querystring": "", "uri": "/" } } } ] } ``` ### Campos de eventos de solicitação Os dados do objeto de evento de solicitação estão contidos em dois subobjetos: `config` (`Records.cf.config`) e `request` (`Records.cf.request`). As listas a seguir descrevem os campos de cada subobjeto. #### Campos no objeto de configuração A lista a seguir descreve os campos no objeto `config` (`Records.cf.config`). **`distributionDomainName` (somente leitura)** O nome de domínio da distribuição associada à solicitação. **`distributionID` (somente leitura)** O ID da distribuição associada à solicitação. **`eventType` (somente leitura)** O tipo de acionador associado à solicitação: `viewer-request` ou `origin-request`. **`requestId` (somente leitura)** Uma string criptografada que identifica exclusivamente uma solicitação do visualizador ao CloudFront. O valor de `requestId` também aparece nos logs de acesso do CloudFront como `x-edge-request-id`. Para obter mais informações, consulte [Logs de acesso (logs padrão)](AccessLogs.md) e [Campos de arquivo de log](standard-logs-reference.md#BasicDistributionFileFormat). #### Campos no objeto de solicitação A lista a seguir descreve os campos no objeto `request` (`Records.cf.request`). **`clientIp` (somente leitura)** O endereço IP do visualizador que fez a solicitação. Se o visualizador usar um proxy HTTP ou um load balancer para enviar a solicitação, o valor será o endereço IP do proxy ou do load balancer. **Cabeçalhos (leitura/gravação)** Os cabeçalhos na solicitação. Observe o seguinte: + As chaves no objeto `headers` são versões em letras minúsculas de nomes de cabeçalho HTTP padrão. Usar chaves em letras minúsculas dá acesso sem diferenciar letras maiúsculas e minúsculas dos valores de cabeçalho. + Cada objeto de cabeçalho (por exemplo, `headers["accept"]` ou `headers["host"]`) é uma matriz de pares de chave-valor. Para um determinado cabeçalho, a matriz contém um par de chave-valor para cada valor na solicitação. + `key` contém o nome do cabeçalho com distinção entre maiúsculas e minúsculas conforme ele apareceu na solicitação HTTP; por exemplo, `Host`, `User-Agent`, `X-Forwarded-For`, `Cookie` e assim por diante. + `value` contém o valor do cabeçalho conforme ele apareceu na solicitação HTTP. + Quando a função do Lambda adicionar ou modificar cabeçalhos de solicitação e você não incluir o campo `key` do cabeçalho, o Lambda@Edge inserirá automaticamente uma `key` de cabeçalho usando o nome de cabeçalho que você fornecer. Independentemente de como você tiver formatado o nome do cabeçalho, a chave de cabeçalho inserida automaticamente será formatada com inicial maiúscula para cada parte, separada por hifens (-). Por exemplo, você pode adicionar um cabeçalho como o seguinte, sem um de cabeçalh `key`: ``` "user-agent": [ { "value": "ExampleCustomUserAgent/1.X.0" } ] ``` Neste exemplo, o Lambda@Edge insere automaticamente `"key": "User-Agent"`. Para obter informações sobre as restrições de uso do cabeçalho, consulte [Restrições das funções de borda](edge-functions-restrictions.md). **`method` (somente leitura)** O método HTTP da solicitação. **`querystring` (leitura/gravação)** A string de consulta, se houver, na solicitação. Se a solicitação não incluir uma string de consulta, o objeto de evento ainda incluirá `querystring` com um valor vazio. Para obter mais informações sobre query strings, consulte [Conteúdo em cache com base em parâmetros de string de consulta](QueryStringParameters.md). **`uri` (leitura/gravação)** O caminho relativo do objeto solicitado. Se a função do Lambda modificar o valor `uri`, observe o seguinte: + O novo valor `uri` deve começar com uma barra (/). + Se uma função alterar o valor `uri`, isso alterará o objeto solicitado pelo visualizador. + Se uma função alterar o valor `uri`, isso *não* mudará o comportamento do cache da solicitação ou da origem para a qual a solicitação é enviada. **`body` (leitura/gravação)** O corpo da solicitação HTTP. A estrutura `body` pode conter os seguintes campos: **`inputTruncated` (somente leitura)** Um sinalizador booliano que indica se o corpo foi truncado pelo Lambda@Edge. Para obter mais informações, consulte [Restrições do corpo da solicitação com a opção de incluir corpo](lambda-at-edge-function-restrictions.md#lambda-at-edge-restrictions-request-body). **`action` (leitura/gravação)** A ação que você pretende realizar com o corpo. As opções para `action` são as seguintes: + `read-only:` esse é o padrão. Ao retornar a resposta da função do Lambda, se `action` for somente leitura, o Lambda@Edge ignorará todas as alterações em `encoding` ou em `data`. + `replace:` especifique isso quando quiser substituir o corpo enviado à origem. **`encoding` (leitura/gravação)** A codificação do corpo. Ao expor o corpo à função do Lambda, o Lambda@Edge primeiro converte o corpo em base64-encoding. Se você escolher `replace` para `action` substituir o corpo, poderá optar por usar a codificação `base64` (padrão) ou `text`. Se você especificar `encoding` como `base64`, mas o corpo não for um base64 válido, o CloudFront retornará um erro. **`data` (leitura/gravação)** O conteúdo do corpo da solicitação. **`origin` (leitura/gravação) (somente eventos de origem)** A origem para a qual enviar a solicitação. A estrutura `origin` deve conter *exatamente uma origem*, que pode ser personalizada ou do Amazon S3. Dependendo do tipo de origem que você especificar (origens personalizadas ou do Amazon S3), será necessário especificar os seguintes campos em sua solicitação: **`customHeaders` (leitura/gravação) (origens personalizadas e do Amazon S3)** (Opcional) É possível incluir os cabeçalhos personalizados com a solicitação ao especificar o par de nome e valor para cada cabeçalho personalizado. Não é possível adicionar cabeçalhos não permitidos, e não pode haver um cabeçalho com o mesmo nome em `Records.cf.request.headers`. As [notas sobre cabeçalhos de solicitação](#request-event-fields-request-headers) também se aplicam a cabeçalhos personalizados. Para obter mais informações, consulte [Cabeçalhos personalizados que o CloudFront não pode adicionar às solicitações da origem](add-origin-custom-headers.md#add-origin-custom-headers-denylist) e [Restrições das funções de borda](edge-functions-restrictions.md). **`domainName` (leitura/gravação) (origens personalizadas e do Amazon S3)** O nome de domínio da origem. O nome de domínio não pode estar vazio. + **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 Amazon 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. **`path` (leitura/gravação) (origens personalizadas e do Amazon S3)** 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/`). Apenas para origens personalizadas, o caminho deve ser codificado por URL e ter um comprimento máximo de 255 caracteres. **`keepaliveTimeout` (leitura/gravação) (somente origens personalizadas)** O tempo, em segundos, durante o qual o CloudFront deve tentar manter a conexão com a origem depois de receber o último pacote da resposta. O valor deve ser um número de 1 a 120, inclusive. **`port` (leitura/gravação) (somente origens personalizadas)** A porta à qual o CloudFront deve se conectar em sua origem personalizada. A porta deve ser 80, 443 ou um número no intervalo de 1024 a 65535, inclusive. **`protocol` (leitura/gravação) (somente origens personalizadas)** O protocolo de conexão que o CloudFront deve usar ao se conectar à sua origem. O valor pode ser `http` ou `https`. **`readTimeout` (leitura/gravação) (origens personalizadas e do Amazon S3)** O tempo, em segundos, que o CloudFront deve esperar por uma resposta depois de enviar uma solicitação à origem. Isso também especifica o tempo que o CloudFront deve aguardar depois de receber um pacote de resposta antes de receber o próximo pacote. O valor deve ser um número de 1 a 120, inclusive. Se você precisar de uma cota maior, consulte [Tempo limite de resposta por origem.](cloudfront-limits.md#limits-web-distributions) **`responseCompletionTimeout` (leitura/gravação) (origens personalizadas e do Amazon S3)** O tempo (em segundos) em que uma solicitação do CloudFront para a origem pode permanecer aberta e aguardar uma resposta. Se a resposta completa não for recebida da origem até esse momento, o CloudFront encerrará a conexão. O valor para `responseCompletionTimeout` deve ser igual a ou maior que o valor para `readTimeout`. Se você definir esse valor como 0, ele removerá qualquer valor anterior definido e retornará ao padrão. Você também pode fazer isso excluindo o campo `responseCompletionTimeout` da solicitação de evento. **`sslProtocols` (leitura/gravação) (somente origens personalizadas)** O protocolo SSL/TLS mínimo que o CloudFront pode usar ao estabelecer uma conexão HTTPS com a origem. Os valores podem ser qualquer um dos seguintes: `TLSv1.2`, `TLSv1.1`, `TLSv1` ou `SSLv3`. **`authMethod` (leitura/gravação) (somente origens do Amazon S3)** Se você estiver usando uma [identidade do acesso de origem (OAI)](private-content-restricting-access-to-s3.md#private-content-restricting-access-to-s3-oai), defina esse campo como `origin-access-identity`. Se você não estiver usando uma OAI, defina-o como `none`. Se você definir `authMethod` como `origin-access-identity`, haverá vários requisitos: + Você deve especificar `region` (consulte o campo a seguir). + Use o mesmo OAI ao alterar a solicitação de uma origem do Amazon S3 para outra. + Não é possível usar uma OAI ao alterar a solicitação de uma origem personalizada para uma origem do Amazon S3. Esse campo não aceita [controle de acesso à origem (OAC)](private-content-restricting-access-to-s3.md). **`region` (leitura/gravação) (somente origens do Amazon S3)** A região da AWS do bucket do Amazon S3. Isso é necessário apenas quando você define `authMethod` como `origin-access-identity`. ## Eventos de resposta Os tópicos a seguir mostram a estrutura do objeto que o CloudFront passa para uma função do Lambda para [eventos de resposta do visualizador e da origem](lambda-cloudfront-trigger-events.md). Após os exemplos, está uma lista de todos os campos possíveis em eventos de resposta do visualizador e da origem. **Topics** + [ ### Exemplo de resposta da origem ](#lambda-event-structure-response-origin) + [ ### Exemplo de resposta do visualizador ](#lambda-event-structure-response-viewer) + [ ### Campos de evento de resposta ](#response-event-fields) ### Exemplo de resposta da origem O exemplo a seguir mostra um objeto de evento de resposta da origem. ``` { "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "origin-response", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "x-forwarded-for": [ { "key": "X-Forwarded-For", "value": "203.0.113.178" } ], "user-agent": [ { "key": "User-Agent", "value": "Amazon CloudFront" } ], "via": [ { "key": "Via", "value": "2.0 8f22423015641505b8c857a37450d6c0.cloudfront.net (CloudFront)" } ], "host": [ { "key": "Host", "value": "example.org" } ], "cache-control": [ { "key": "Cache-Control", "value": "no-cache" } ] }, "method": "GET", "origin": { "custom": { "customHeaders": {}, "domainName": "example.org", "keepaliveTimeout": 5, "path": "", "port": 443, "protocol": "https", "readTimeout": 30, "responseCompletionTimeout": 30, "sslProtocols": [ "TLSv1", "TLSv1.1", "TLSv1.2" ] } }, "querystring": "", "uri": "/" }, "response": { "headers": { "access-control-allow-credentials": [ { "key": "Access-Control-Allow-Credentials", "value": "true" } ], "access-control-allow-origin": [ { "key": "Access-Control-Allow-Origin", "value": "*" } ], "date": [ { "key": "Date", "value": "Mon, 13 Jan 2020 20:12:38 GMT" } ], "referrer-policy": [ { "key": "Referrer-Policy", "value": "no-referrer-when-downgrade" } ], "server": [ { "key": "Server", "value": "ExampleCustomOriginServer" } ], "x-content-type-options": [ { "key": "X-Content-Type-Options", "value": "nosniff" } ], "x-frame-options": [ { "key": "X-Frame-Options", "value": "DENY" } ], "x-xss-protection": [ { "key": "X-XSS-Protection", "value": "1; mode=block" } ], "content-type": [ { "key": "Content-Type", "value": "text/html; charset=utf-8" } ], "content-length": [ { "key": "Content-Length", "value": "9593" } ] }, "status": "200", "statusDescription": "OK" } } } ] } ``` ### Exemplo de resposta do visualizador O exemplo a seguir mostra um objeto de evento de resposta do visualizador. ``` { "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-response", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.66.0" } ], "accept": [ { "key": "accept", "value": "*/*" } ] }, "method": "GET", "querystring": "", "uri": "/" }, "response": { "headers": { "access-control-allow-credentials": [ { "key": "Access-Control-Allow-Credentials", "value": "true" } ], "access-control-allow-origin": [ { "key": "Access-Control-Allow-Origin", "value": "*" } ], "date": [ { "key": "Date", "value": "Mon, 13 Jan 2020 20:14:56 GMT" } ], "referrer-policy": [ { "key": "Referrer-Policy", "value": "no-referrer-when-downgrade" } ], "server": [ { "key": "Server", "value": "ExampleCustomOriginServer" } ], "x-content-type-options": [ { "key": "X-Content-Type-Options", "value": "nosniff" } ], "x-frame-options": [ { "key": "X-Frame-Options", "value": "DENY" } ], "x-xss-protection": [ { "key": "X-XSS-Protection", "value": "1; mode=block" } ], "age": [ { "key": "Age", "value": "2402" } ], "content-type": [ { "key": "Content-Type", "value": "text/html; charset=utf-8" } ], "content-length": [ { "key": "Content-Length", "value": "9593" } ] }, "status": "200", "statusDescription": "OK" } } } ] } ``` ### Campos de evento de resposta Os dados do objeto de evento de resposta estão contidos em três subobjetos: `config` (`Records.cf.config`), `request` (`Records.cf.request`) e `response` (`Records.cf.response`). Para obter mais informações sobre os campos no objeto da solicitação, consulte [Campos no objeto de solicitação](#request-event-fields-request). As listas a seguir descrevem os campos nos subobjetos `config` e `response`. #### Campos no objeto de configuração A lista a seguir descreve os campos no objeto `config` (`Records.cf.config`). **`distributionDomainName` (somente leitura)** O nome de domínio da distribuição associada à resposta. **`distributionID` (somente leitura)** O ID da distribuição associada à resposta. **`eventType` (somente leitura)** O tipo de acionador associado à resposta: `origin-response` ou `viewer-response`. **`requestId` (somente leitura)** Uma string criptografada que identifica exclusivamente a solicitação do visualizador ao CloudFront à qual esta resposta está associada. O valor de `requestId` também aparece nos logs de acesso do CloudFront como `x-edge-request-id`. Para obter mais informações, consulte [Logs de acesso (logs padrão)](AccessLogs.md) e [Campos de arquivo de log](standard-logs-reference.md#BasicDistributionFileFormat). #### Campos no objeto de resposta A lista a seguir descreve os campos no objeto `response` (`Records.cf.response`). Para obter informações sobre como usar uma função do Lambda@Edge para gerar uma resposta HTTP, consulte [Gerar respostas de HTTP em acionadores da solicitação](lambda-generating-http-responses.md#lambda-generating-http-responses-in-requests). **`headers` (leitura/gravação)** Os cabeçalhos na resposta. Observe o seguinte: + As chaves no objeto `headers` são versões em letras minúsculas de nomes de cabeçalho HTTP padrão. Usar chaves em letras minúsculas dá acesso sem diferenciar letras maiúsculas e minúsculas dos valores de cabeçalho. + Cada objeto de cabeçalho (por exemplo, `headers["content-type"]` ou `headers["content-length"]`) é uma matriz de pares de chave-valor. Para determinado cabeçalho, a matriz contém um par de chave-valor para cada valor na resposta. + `key` contém o nome do cabeçalho com distinção entre maiúsculas e minúsculas conforme aparece na resposta HTTP; por exemplo, `Content-Type`, `Content-Length`, `Cookie`, e assim por diante. + `value` contém o valor do cabeçalho como ele aparece na resposta HTTP. + Quando a função do Lambda adicionar ou modificar cabeçalhos de resposta e você não incluir o campo `key` do cabeçalho, o Lambda@Edge inserirá automaticamente uma `key` de cabeçalho usando o nome de cabeçalho que você fornecer. Independentemente de como você tiver formatado o nome do cabeçalho, a chave de cabeçalho inserida automaticamente será formatada com inicial maiúscula para cada parte, separada por hifens (-). Por exemplo, você pode adicionar um cabeçalho como o seguinte, sem um de cabeçalh `key`: ``` "content-type": [ { "value": "text/html;charset=UTF-8" } ] ``` Neste exemplo, o Lambda@Edge insere automaticamente `"key": "Content-Type"`. Para obter informações sobre as restrições de uso do cabeçalho, consulte [Restrições das funções de borda](edge-functions-restrictions.md). **`status`** O código de status HTTP da resposta. **`statusDescription`** A descrição do status HTTP da resposta. # Trabalho com solicitações e respostas Para usar as solicitações e as respostas do Lambda@Edge, consulte os seguintes tópicos: **Topics** + [ ## Usar funções do Lambda@Edge com failover de origem ](#lambda-and-origin-failover) + [ ## Gerar respostas de HTTP em acionadores da solicitação ](#lambda-generating-http-responses-in-requests) + [ ## Atualizar respostas de HTTP em acionadores de resposta da origem ](#lambda-updating-http-responses) + [ ## Acessar o corpo da solicitação escolhendo a opção de incluir o corpo ](#lambda-include-body-access) ## Usar funções do Lambda@Edge com failover de origem É possível usar as funções do Lambda@Edge com distribuições do CloudFront que você configurou com grupos de origens, por exemplo, para um failover de origem que você configura para ajudar a garantir a alta disponibilidade. Para usar uma função do Lambda com um grupo de origem, especifique a função em um trigger de resposta ou de solicitação de origem para um grupo de origens ao criar o comportamento de cache. Para saber mais, consulte: + **Criar grupos de origens:** [Criar um grupo de origem](high_availability_origin_failover.md#concept_origin_groups.creating) + **Como um failover de origem funciona com o Lambda@Edge:** [Uso do failover de origem com funções do Lambda@Edge](high_availability_origin_failover.md#concept_origin_groups.lambda) ## Gerar respostas de HTTP em acionadores da solicitação Quando o CloudFront recebe uma solicitação, você pode usar uma função do Lambda para gerar uma resposta HTTP que o CloudFront retornará diretamente ao visualizador sem encaminhar a resposta para a origem. Gerar respostas HTTP reduz a carga na origem e geralmente também reduz a latência para o visualizador. Alguns cenários comuns para gerar respostas HTTP incluem o seguinte: + Retornar uma pequena página da web ao visualizador + Retornar um código de status HTTP 301 ou 302 para redirecionar o usuário para outra página da web + Retornar um código de status HTTP 401 para o visualizador quando o usuário ainda não tiver sido autenticado Uma função do Lambda@Edge pode gerar uma resposta HTTP quando ocorrerem os seguintes eventos do CloudFront: **Eventos de solicitação de visualizador** Quando uma função for acionada por um evento de solicitação do visualizador, o CloudFront retornará a resposta ao visualizador e não a armazenará em cache. **Eventos de solicitação de origem** Quando a função for acionada por um evento de solicitação de origem, o CloudFront verificará se há uma resposta gerada anteriormente pela função no cache de borda. + Se a resposta estiver no cache, a função não será executada e o CloudFront retornará a resposta em cache ao visualizador. + Se a resposta não estiver no cache, a função será executada, o CloudFront retornará a resposta ao visualizador e também a armazenará em cache. Para ver códigos de exemplo para gerar respostas HTTP, consulte [Funções de exemplo do Lambda@Edge](lambda-examples.md). Você também pode substituir as respostas HTTP em triggers de resposta. Para obter mais informações, consulte [Atualizar respostas de HTTP em acionadores de resposta da origem](#lambda-updating-http-responses). ### Modelo de programação Esta seção descreve o modelo de programação para usar o Lambda@Edge para gerar respostas HTTP. **Topics** + [ #### Objeto da resposta ](#lambda-generating-http-responses-object) + [ #### Erros ](#lambda-generating-http-responses-errors) + [ #### Campos obrigatórios ](#lambda-generating-http-responses-required-fields) #### Objeto da resposta A resposta que você retornar como o parâmetro `result` do método `callback` deverá ter a seguinte estrutura (observe que apenas o campo `status` é necessário). ``` const response = { body: 'content', bodyEncoding: 'text' | 'base64', headers: { 'header name in lowercase': [{ key: 'header name in standard case', value: 'header value' }], ... }, status: 'HTTP status code (string)', statusDescription: 'status description' }; ``` O objeto de resposta pode incluir os seguintes valores: **`body`** O corpo, se houver, que você deseja que o CloudFront retorne na resposta gerada. **`bodyEncoding`** A codificação para o valor que você especificou no `body`. As únicas codificações válidas são `text` e `base64`. Se você incluir `body` no objeto `response`, mas omitir `bodyEncoding`, o CloudFront tratará o corpo como texto. Se você especificar `bodyEncoding` como `base64`, mas o corpo não for um base64 válido, o CloudFront retornará um erro. **`headers`** Cabeçalhos que você deseja que o CloudFront retorne na resposta gerada. Observe o seguinte: + As chaves no objeto `headers` são versões em letras minúsculas de nomes de cabeçalho HTTP padrão. Usar chaves em letras minúsculas dá acesso sem diferenciar letras maiúsculas e minúsculas dos valores de cabeçalho. + Cada cabeçalho (por exemplo, `headers["accept"]` ou `headers["host"]`) é uma matriz de pares de chave-valor. Para determinado cabeçalho, a matriz contém um par de chave-valor para cada valor na resposta gerada. + `key` (opcional) é o nome com distinção entre letras maiúsculas e minúsculas do cabeçalho da forma como ele aparece em uma solicitação HTTP, por exemplo, `accept` ou `host`. + Especifique `value` como valor do cabeçalho. + Se você não incluir a parte da chave do par de chave-valor do cabeçalho, o Lambda@Edge inserirá automaticamente uma chave de cabeçalho usando o nome de cabeçalho fornecido. Independentemente de como você tiver formatado o nome do cabeçalho, a chave de cabeçalho inserida será automaticamente formatada com o uso de iniciais maiúsculas para cada parte, separada por hífen (-). Por exemplo, você pode adicionar um cabeçalho como o seguinte, sem uma chave de cabeçalho: `'content-type': [{ value: 'text/html;charset=UTF-8' }]` Neste exemplo, o Lambda@ Edge cria a seguinte chave de cabeçalho: `Content-Type`. Para obter informações sobre as restrições de uso do cabeçalho, consulte [Restrições das funções de borda](edge-functions-restrictions.md). **`status`** Código de status do HTTP. Forneça o código de status como uma string. O CloudFront usa o código de status fornecido para o seguinte: + Retornar na resposta + Armazenar no cache de borda do CloudFront, quando a resposta tiver sido gerada por uma função acionada por um evento de solicitação de origem + Fazer login no CloudFront [Logs de acesso (logs padrão)](AccessLogs.md) Se o valor de `status` não estiver entre 200 e 599, o CloudFront retornará um erro ao visualizador. **`statusDescription`** A descrição que você deseja que o CloudFront retorne na resposta para acompanhar o código de status HTTP. Você não precisa usar descrições padrão, como `OK`, para um código de status HTTP de 200. #### Erros Veja a seguir os erros possíveis das respostas HTTP geradas. **A resposta contém um corpo e especifica 204 (sem conteúdo) como status** Quando uma função for acionada por uma solicitação de visualizador, o CloudFront retornará um código de status HTTP 502 (gateway inválido) ao visualizador quando ocorrer o seguinte: + O valor de `status` for 204 (sem conteúdo) + A resposta incluir um valor para `body` Isso ocorre porque o Lambda@Edge impõe a restrição opcional encontrada na RFC 2616: uma resposta `HTTP 204` não precisa conter um corpo de mensagem. **Restrições ao tamanho da resposta gerada** O tamanho máximo de uma resposta gerada por uma função do Lambda depende do evento que acionou a função: + **Eventos de solicitação de visualizador**: 40 KB + **Eventos de solicitação de origem**: 1 MB Se a resposta for maior que o tamanho permitido, o CloudFront retornará um código de status HTTP 502 (gateway inválido) ao visualizador. #### Campos obrigatórios O campo `status` é obrigatório. Todos os demais campos são opcionais. ## Atualizar respostas de HTTP em acionadores de resposta da origem Quando o CloudFront recebe uma resposta HTTP do servidor de origem, se houver um trigger de resposta de origem associado ao comportamento de cache, você poderá modificar a resposta HTTP para substituir o que foi retornado pela origem. Alguns cenários comuns para atualizar respostas HTTP incluem o seguinte: + Alterar o status para definir um código de status HTTP 200 e a criação de conteúdo estático do corpo para retornar ao visualizador quando uma origem retornar um código de status de erro (4xx ou 5xx). Para obter o código de exemplo, consulte [Exemplo: usar um acionador de resposta de origem para atualizar o código do status de erro para 200](lambda-examples.md#lambda-examples-custom-error-static-body). + Alterar o status para definir um código de status HTTP 301 ou 302, de forma a redirecionar o usuário para outro site quando uma origem retornar um código de status de erro (4xx ou 5xx). Para obter o código de exemplo, consulte [Exemplo: usar um acionador de resposta de origem para atualizar o código do status de erro para 302](lambda-examples.md#lambda-examples-custom-error-new-site). **nota** A função deve retornar um valor de status entre `200` e `599` (inclusive); do contrário, o CloudFront retornará um erro ao visualizador. Você também pode substituir as respostas HTTP em eventos de solicitação do visualizador e da origem. Para obter mais informações, consulte [Gerar respostas de HTTP em acionadores da solicitação](#lambda-generating-http-responses-in-requests). Ao trabalhar com a resposta de HTTP, o Lambda@Edge não expõe o corpo retornado pelo servidor de origem ao acionador da resposta de origem. Você pode gerar um corpo de conteúdo estático definindo-o no valor desejado ou removendo o corpo de dentro da função ao definir o valor como vazio. Se você não atualizar o campo do corpo na função, o corpo original retornado pelo servidor de origem será reapresentado ao visualizador. ## Acessar o corpo da solicitação escolhendo a opção de incluir o corpo Você pode optar por fazer com que o Lambda@Edge exponha o corpo em uma solicitação para métodos HTTP graváveis (POST, PUT, DELETE e assim por diante), para que seja possível acessá-lo na função do Lambda. Você pode escolher acesso somente leitura ou especificar que substituirá o corpo. Para ativar essa opção, escolha **Include Body (Incluir corpo)** ao criar um trigger do CloudFront para sua função que seja para um evento de solicitação de visualizador ou de origem. Para obter mais informações, consulte [Adicionar acionadores para uma função do Lambda@Edge](lambda-edge-add-triggers.md) ou, para saber como usar a opção **Include Body (Incluir corpo)** com a função, consulte [Estrutura de eventos do Lambda@Edge](lambda-event-structure.md). Os cenários em que você pode querer usar esse recurso incluem: + Processamento de formulários da web, como formulários "entre em contato conosco", sem enviar dados de entrada do cliente de volta aos servidores de origem. + Reunir dados de web beacons enviados por navegadores dos visualizadores e processá-los no ponto. Para obter o código de exemplo, consulte [Funções de exemplo do Lambda@Edge](lambda-examples.md). **nota** Se o corpo da solicitação for grande, o Lambda@Edge o truncará. Para obter informações detalhadas sobre truncamento e tamanho máximo, consulte [Restrições do corpo da solicitação com a opção de incluir corpo](lambda-at-edge-function-restrictions.md#lambda-at-edge-restrictions-request-body). # Funções de exemplo do Lambda@Edge Veja os exemplos a seguir de como usar as funções do Lambda com o Amazon CloudFront. **nota** Se você escolher o runtime Node.js 18 ou posterior para a função Lambda@Edge, um arquivo `index.mjs` será criado automaticamente para você. Para usar os exemplos de código a seguir, renomeie o arquivo `index.mjs` para `index.js`. **Topics** + [ ## Exemplos gerais ](#lambda-examples-general-examples) + [ ## Gerar respostas: exemplos ](#lambda-examples-generated-response-examples) + [ ## Strings de consulta: exemplos ](#lambda-examples-query-string-examples) + [ ## Personalizar o conteúdo por cabeçalhos de país ou tipo de dispositivo: exemplos ](#lambda-examples-redirecting-examples) + [ ## Seleção de origem dinâmica baseada em conteúdo: exemplos ](#lambda-examples-content-based-routing-examples) + [ ## Atualização do status de erro: exemplos ](#lambda-examples-update-error-status-examples) + [ ## Acesso ao corpo da solicitação: exemplos ](#lambda-examples-access-request-body-examples) ## Exemplos gerais Os exemplos a seguir mostram as maneiras comuns de usar o Lambda@Edge no CloudFront. **Topics** + [ ### Exemplo: testes A/B ](#lambda-examples-a-b-testing) + [ ### Exemplo: substituir um cabeçalho de resposta ](#lambda-examples-overriding-response-header) ### Exemplo: testes A/B Você pode usar o exemplo a seguir para testar duas versões diferentes de uma imagem sem criar redirecionamentos nem alterar a URL. Este exemplo lê os cookies na solicitação do visualizador e modifica a URL da solicitação adequadamente. Se o visualizador não enviar um cookie com um dos valores esperados, o exemplo atribuirá aleatoriamente o visualizador a um dos URLs. ------ #### [ Node.js ] ``` 'use strict'; exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; const headers = request.headers; if (request.uri !== '/experiment-pixel.jpg') { // do not process if this is not an A-B test request callback(null, request); return; } const cookieExperimentA = 'X-Experiment-Name=A'; const cookieExperimentB = 'X-Experiment-Name=B'; const pathExperimentA = '/experiment-group/control-pixel.jpg'; const pathExperimentB = '/experiment-group/treatment-pixel.jpg'; /* * Lambda at the Edge headers are array objects. * * Client may send multiple Cookie headers, i.e.: * > GET /viewerRes/test HTTP/1.1 * > User-Agent: curl/7.18.1 (x86_64-unknown-linux-gnu) libcurl/7.18.1 OpenSSL/1.0.1u zlib/1.2.3 * > Cookie: First=1; Second=2 * > Cookie: ClientCode=abc * > Host: example.com * * You can access the first Cookie header at headers["cookie"][0].value * and the second at headers["cookie"][1].value. * * Header values are not parsed. In the example above, * headers["cookie"][0].value is equal to "First=1; Second=2" */ let experimentUri; if (headers.cookie) { for (let i = 0; i < headers.cookie.length; i++) { if (headers.cookie[i].value.indexOf(cookieExperimentA) >= 0) { console.log('Experiment A cookie found'); experimentUri = pathExperimentA; break; } else if (headers.cookie[i].value.indexOf(cookieExperimentB) >= 0) { console.log('Experiment B cookie found'); experimentUri = pathExperimentB; break; } } } if (!experimentUri) { console.log('Experiment cookie has not been found. Throwing dice...'); if (Math.random() < 0.75) { experimentUri = pathExperimentA; } else { experimentUri = pathExperimentB; } } request.uri = experimentUri; console.log(`Request uri set to "${request.uri}"`); callback(null, request); }; ``` ------ #### [ Python ] ``` import json import random def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] headers = request['headers'] if request['uri'] != '/experiment-pixel.jpg': # Not an A/B Test return request cookieExperimentA, cookieExperimentB = 'X-Experiment-Name=A', 'X-Experiment-Name=B' pathExperimentA, pathExperimentB = '/experiment-group/control-pixel.jpg', '/experiment-group/treatment-pixel.jpg' ''' Lambda at the Edge headers are array objects. Client may send multiple cookie headers. For example: > GET /viewerRes/test HTTP/1.1 > User-Agent: curl/7.18.1 (x86_64-unknown-linux-gnu) libcurl/7.18.1 OpenSSL/1.0.1u zlib/1.2.3 > Cookie: First=1; Second=2 > Cookie: ClientCode=abc > Host: example.com You can access the first Cookie header at headers["cookie"][0].value and the second at headers["cookie"][1].value. Header values are not parsed. In the example above, headers["cookie"][0].value is equal to "First=1; Second=2" ''' experimentUri = "" for cookie in headers.get('cookie', []): if cookieExperimentA in cookie['value']: print("Experiment A cookie found") experimentUri = pathExperimentA break elif cookieExperimentB in cookie['value']: print("Experiment B cookie found") experimentUri = pathExperimentB break if not experimentUri: print("Experiment cookie has not been found. Throwing dice...") if random.random() < 0.75: experimentUri = pathExperimentA else: experimentUri = pathExperimentB request['uri'] = experimentUri print(f"Request uri set to {experimentUri}") return request ``` ------ ### Exemplo: substituir um cabeçalho de resposta O exemplo abaixo mostra como alterar o valor de um cabeçalho de resposta com base no valor de outro cabeçalho. ------ #### [ Node.js ] ``` export const handler = async (event) => { const response = event.Records[0].cf.response; const headers = response.headers; const headerNameSrc = 'X-Amz-Meta-Last-Modified'; const headerNameDst = 'Last-Modified'; if (headers[headerNameSrc.toLowerCase()]) { headers[headerNameDst.toLowerCase()] = [{ key: headerNameDst, value: headers[headerNameSrc.toLowerCase()][0].value, }]; console.log(`Response header "${headerNameDst}" was set to ` + `"${headers[headerNameDst.toLowerCase()][0].value}"`); } return response; }; ``` ------ #### [ Python ] ``` import json def lambda_handler(event, context): response = event['Records'][0]['cf']['response'] headers = response['headers'] header_name_src = 'X-Amz-Meta-Last-Modified' header_name_dst = 'Last-Modified' if headers.get(header_name_src.lower()): headers[header_name_dst.lower()] = [{ 'key': header_name_dst, 'value': headers[header_name_src.lower()][0]['value'] }] print(f'Response header "{header_name_dst}" was set to ' f'"{headers[header_name_dst.lower()][0]["value"]}"') return response ``` ------ ## Gerar respostas: exemplos Os exemplos a seguir mostram como você pode usar o Lambda@Edge para gerar respostas. **Topics** + [ ### Exemplo: fornecer conteúdo estático (resposta gerada) ](#lambda-examples-static-web-server) + [ ### Exemplo: gerar um redirecionamento de HTTP (resposta gerada) ](#lambda-examples-http-redirect) ### Exemplo: fornecer conteúdo estático (resposta gerada) O exemplo a seguir mostra como usar uma função do Lambda para fornecer conteúdo estático de site. Isso reduz a carga no servidor de origem e a latência geral. **nota** Você pode gerar respostas HTTP para eventos de solicitação de visualizador e de solicitação de origem. Para obter mais informações, consulte [Gerar respostas de HTTP em acionadores da solicitação](lambda-generating-http-responses.md#lambda-generating-http-responses-in-requests). Você também pode substituir ou remover o corpo da resposta de HTTP em eventos de resposta de origem. Para obter mais informações, consulte [Atualizar respostas de HTTP em acionadores de resposta da origem](lambda-generating-http-responses.md#lambda-updating-http-responses). ------ #### [ Node.js ] ``` 'use strict'; const content = ` <\!DOCTYPE html>Hello from Lambda@Edge!
`; exports.handler = (event, context, callback) => { /* * Generate HTTP OK response using 200 status code with HTML body. */ const response = { status: '200', statusDescription: 'OK', headers: { 'cache-control': [{ key: 'Cache-Control', value: 'max-age=100' }], 'content-type': [{ key: 'Content-Type', value: 'text/html' }] }, body: content, }; callback(null, response); }; ``` ------ #### [ Python ] ``` import json CONTENT = """ <\!DOCTYPE html>Hello from Lambda@Edge!
""" def lambda_handler(event, context): # Generate HTTP OK response using 200 status code with HTML body. response = { 'status': '200', 'statusDescription': 'OK', 'headers': { 'cache-control': [ { 'key': 'Cache-Control', 'value': 'max-age=100' } ], "content-type": [ { 'key': 'Content-Type', 'value': 'text/html' } ] }, 'body': CONTENT } return response ``` ------ ### Exemplo: gerar um redirecionamento de HTTP (resposta gerada) O exemplo abaixo mostra como gerar um redirecionamento HTTP. **nota** Você pode gerar respostas HTTP para eventos de solicitação de visualizador e de solicitação de origem. Para obter mais informações, consulte [Gerar respostas de HTTP em acionadores da solicitação](lambda-generating-http-responses.md#lambda-generating-http-responses-in-requests). ------ #### [ Node.js ] ``` 'use strict'; exports.handler = (event, context, callback) => { /* * Generate HTTP redirect response with 302 status code and Location header. */ const response = { status: '302', statusDescription: 'Found', headers: { location: [{ key: 'Location', value: 'https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html', }], }, }; callback(null, response); }; ``` ------ #### [ Python ] ``` def lambda_handler(event, context): # Generate HTTP redirect response with 302 status code and Location header. response = { 'status': '302', 'statusDescription': 'Found', 'headers': { 'location': [{ 'key': 'Location', 'value': 'https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html' }] } } return response ``` ------ ## Strings de consulta: exemplos Os exemplos a seguir mostram maneiras de usar o Lambda@Edge com strings de consulta. **Topics** + [ ### Exemplo: adicionar um cabeçalho com base em um parâmetro de string de consulta ](#lambda-examples-header-based-on-query-string) + [ ### Exemplo: normalizar os parâmetros da string de consulta para melhorar a proporção de acertos no cache ](#lambda-examples-normalize-query-string-parameters) + [ ### Exemplo: redirecionar usuários não autenticados para uma página de login ](#lambda-examples-redirect-to-signin-page) ### Exemplo: adicionar um cabeçalho com base em um parâmetro de string de consulta O exemplo a seguir mostra como obter o par chave-valor de um parâmetro de string de consulta e adicionar um cabeçalho com base nesses valores. ------ #### [ Node.js ] ``` 'use strict'; const querystring = require('querystring'); exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; /* When a request contains a query string key-value pair but the origin server * expects the value in a header, you can use this Lambda function to * convert the key-value pair to a header. Here's what the function does: * 1. Parses the query string and gets the key-value pair. * 2. Adds a header to the request using the key-value pair that the function got in step 1. */ /* Parse request querystring to get javascript object */ const params = querystring.parse(request.querystring); /* Move auth param from querystring to headers */ const headerName = 'Auth-Header'; request.headers[headerName.toLowerCase()] = [{ key: headerName, value: params.auth }]; delete params.auth; /* Update request querystring */ request.querystring = querystring.stringify(params); callback(null, request); }; ``` ------ #### [ Python ] ``` from urllib.parse import parse_qs, urlencode def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] ''' When a request contains a query string key-value pair but the origin server expects the value in a header, you can use this Lambda function to convert the key-value pair to a header. Here's what the function does: 1. Parses the query string and gets the key-value pair. 2. Adds a header to the request using the key-value pair that the function got in step 1. ''' # Parse request querystring to get dictionary/json params = {k : v[0] for k, v in parse_qs(request['querystring']).items()} # Move auth param from querystring to headers headerName = 'Auth-Header' request['headers'][headerName.lower()] = [{'key': headerName, 'value': params['auth']}] del params['auth'] # Update request querystring request['querystring'] = urlencode(params) return request ``` ------ ### Exemplo: normalizar os parâmetros da string de consulta para melhorar a proporção de acertos no cache O exemplo a seguir mostra como melhorar o índice de ocorrência no cache fazendo as seguintes alterações nas strings de consulta antes que o CloudFront encaminhe as solicitações para a origem: + Colocar os pares de chave-valor em ordem alfabética pelo nome do parâmetro. + Alterar os pares de chave-valor para minúsculas. Para obter mais informações, consulte [Conteúdo em cache com base em parâmetros de string de consulta](QueryStringParameters.md). ------ #### [ Node.js ] ``` 'use strict'; const querystring = require('querystring'); exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; /* When you configure a distribution to forward query strings to the origin and * to cache based on an allowlist of query string parameters, we recommend * the following to improve the cache-hit ratio: * - Always list parameters in the same order. * - Use the same case for parameter names and values. * * This function normalizes query strings so that parameter names and values * are lowercase and parameter names are in alphabetical order. * * For more information, see: * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/QueryStringParameters.html */ console.log('Query String: ', request.querystring); /* Parse request query string to get javascript object */ const params = querystring.parse(request.querystring.toLowerCase()); const sortedParams = {}; /* Sort param keys */ Object.keys(params).sort().forEach(key => { sortedParams[key] = params[key]; }); /* Update request querystring with normalized */ request.querystring = querystring.stringify(sortedParams); callback(null, request); }; ``` ------ #### [ Python ] ``` from urllib.parse import parse_qs, urlencode def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] ''' When you configure a distribution to forward query strings to the origin and to cache based on an allowlist of query string parameters, we recommend the following to improve the cache-hit ratio: Always list parameters in the same order. - Use the same case for parameter names and values. This function normalizes query strings so that parameter names and values are lowercase and parameter names are in alphabetical order. For more information, see: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/QueryStringParameters.html ''' print("Query string: ", request["querystring"]) # Parse request query string to get js object params = {k : v[0] for k, v in parse_qs(request['querystring'].lower()).items()} # Sort param keys sortedParams = sorted(params.items(), key=lambda x: x[0]) # Update request querystring with normalized request['querystring'] = urlencode(sortedParams) return request ``` ------ ### Exemplo: redirecionar usuários não autenticados para uma página de login O exemplo a seguir mostra como redirecionar os usuários para uma página de login caso não tenham inserido as credenciais. ------ #### [ Node.js ] ``` 'use strict'; function parseCookies(headers) { const parsedCookie = {}; if (headers.cookie) { headers.cookie[0].value.split(';').forEach((cookie) => { if (cookie) { const parts = cookie.split('='); parsedCookie[parts[0].trim()] = parts[1].trim(); } }); } return parsedCookie; } exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; const headers = request.headers; /* Check for session-id in request cookie in viewer-request event, * if session-id is absent, redirect the user to sign in page with original * request sent as redirect_url in query params. */ /* Check for session-id in cookie, if present then proceed with request */ const parsedCookies = parseCookies(headers); if (parsedCookies && parsedCookies['session-id']) { callback(null, request); return; } /* URI encode the original request to be sent as redirect_url in query params */ const encodedRedirectUrl = encodeURIComponent(`https://${headers.host[0].value}${request.uri}?${request.querystring}`); const response = { status: '302', statusDescription: 'Found', headers: { location: [{ key: 'Location', value: `https://www.example.com/signin?redirect_url=${encodedRedirectUrl}`, }], }, }; callback(null, response); }; ``` ------ #### [ Python ] ``` import urllib def parseCookies(headers): parsedCookie = {} if headers.get('cookie'): for cookie in headers['cookie'][0]['value'].split(';'): if cookie: parts = cookie.split('=') parsedCookie[parts[0].strip()] = parts[1].strip() return parsedCookie def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] headers = request['headers'] ''' Check for session-id in request cookie in viewer-request event, if session-id is absent, redirect the user to sign in page with original request sent as redirect_url in query params. ''' # Check for session-id in cookie, if present, then proceed with request parsedCookies = parseCookies(headers) if parsedCookies and parsedCookies['session-id']: return request # URI encode the original request to be sent as redirect_url in query params redirectUrl = "https://%s%s?%s" % (headers['host'][0]['value'], request['uri'], request['querystring']) encodedRedirectUrl = urllib.parse.quote_plus(redirectUrl.encode('utf-8')) response = { 'status': '302', 'statusDescription': 'Found', 'headers': { 'location': [{ 'key': 'Location', 'value': 'https://www.example.com/signin?redirect_url=%s' % encodedRedirectUrl }] } } return response ``` ------ ## Personalizar o conteúdo por cabeçalhos de país ou tipo de dispositivo: exemplos Os exemplos a seguir mostram como você pode usar o Lambda@Edge para personalizar o comportamento com base no local ou no tipo de dispositivo usado pelo visualizador. **Topics** + [ ### Exemplo: redirecionar as solicitações do visualizador para um URL específico do país ](#lambda-examples-redirect-based-on-country) + [ ### Exemplo: fornecer diferentes versões de um objeto com base no dispositivo ](#lambda-examples-vary-on-device-type) ### Exemplo: redirecionar as solicitações do visualizador para um URL específico do país O exemplo a seguir mostra como gerar uma resposta de redirecionamento HTTP com um URL específico do país e retornar a resposta para o visualizador. Isso é útil quando você deseja fornecer respostas específicas do país. Por exemplo: + Se tiver subdomínios específicos do país, como us.example.com e tw.example.com, você pode gerar uma resposta de redirecionamento quando um visualizador solicitar example.com. + Se estiver transmitindo um vídeo, mas não tem direitos para transmitir o conteúdo em um país específico, você pode redirecionar os usuários desse país para uma página que explica por que eles não podem visualizar o vídeo. Observe o seguinte: + É necessário configurar a distribuição para armazenar em cache com base no cabeçalho `CloudFront-Viewer-Country`. Para obter mais informações, consulte [Cache baseado em Cabeçalhos de solicitação selecionados](DownloadDistValuesCacheBehavior.md#DownloadDistValuesForwardHeaders). + O CloudFront adiciona o cabeçalho `CloudFront-Viewer-Country` após o evento de solicitação do visualizador. Para usar este exemplo, é necessário criar um trigger para o evento de solicitação da origem. ------ #### [ Node.js ] ``` 'use strict'; /* This is an origin request function */ exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; const headers = request.headers; /* * Based on the value of the CloudFront-Viewer-Country header, generate an * HTTP status code 302 (Redirect) response, and return a country-specific * URL in the Location header. * NOTE: 1. You must configure your distribution to cache based on the * CloudFront-Viewer-Country header. For more information, see * https://docs.aws.amazon.com/console/cloudfront/cache-on-selected-headers * 2. CloudFront adds the CloudFront-Viewer-Country header after the viewer * request event. To use this example, you must create a trigger for the * origin request event. */ let url = 'https://example.com/'; if (headers['cloudfront-viewer-country']) { const countryCode = headers['cloudfront-viewer-country'][0].value; if (countryCode === 'TW') { url = 'https://tw.example.com/'; } else if (countryCode === 'US') { url = 'https://us.example.com/'; } } const response = { status: '302', statusDescription: 'Found', headers: { location: [{ key: 'Location', value: url, }], }, }; callback(null, response); }; ``` ------ #### [ Python ] ``` # This is an origin request function def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] headers = request['headers'] ''' Based on the value of the CloudFront-Viewer-Country header, generate an HTTP status code 302 (Redirect) response, and return a country-specific URL in the Location header. NOTE: 1. You must configure your distribution to cache based on the CloudFront-Viewer-Country header. For more information, see https://docs.aws.amazon.com/console/cloudfront/cache-on-selected-headers 2. CloudFront adds the CloudFront-Viewer-Country header after the viewer request event. To use this example, you must create a trigger for the origin request event. ''' url = 'https://example.com/' viewerCountry = headers.get('cloudfront-viewer-country') if viewerCountry: countryCode = viewerCountry[0]['value'] if countryCode == 'TW': url = 'https://tw.example.com/' elif countryCode == 'US': url = 'https://us.example.com/' response = { 'status': '302', 'statusDescription': 'Found', 'headers': { 'location': [{ 'key': 'Location', 'value': url }] } } return response ``` ------ ### Exemplo: fornecer diferentes versões de um objeto com base no dispositivo O exemplo a seguir mostra como servir diferentes versões de um objeto com base no tipo de dispositivo usado pelo usuário, por exemplo, um dispositivo móvel ou um tablet. Observe o seguinte: + É necessário configurar a distribuição para armazenar em cache com base nos cabeçalhos `CloudFront-Is-*-Viewer`. Para obter mais informações, consulte [Cache baseado em Cabeçalhos de solicitação selecionados](DownloadDistValuesCacheBehavior.md#DownloadDistValuesForwardHeaders). + O CloudFront adiciona os cabeçalhos `CloudFront-Is-*-Viewer` após o evento de solicitação do visualizador. Para usar este exemplo, é necessário criar um trigger para o evento de solicitação da origem. ------ #### [ Node.js ] ``` 'use strict'; /* This is an origin request function */ exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; const headers = request.headers; /* * Serve different versions of an object based on the device type. * NOTE: 1. You must configure your distribution to cache based on the * CloudFront-Is-*-Viewer headers. For more information, see * the following documentation: * https://docs.aws.amazon.com/console/cloudfront/cache-on-selected-headers * https://docs.aws.amazon.com/console/cloudfront/cache-on-device-type * 2. CloudFront adds the CloudFront-Is-*-Viewer headers after the viewer * request event. To use this example, you must create a trigger for the * origin request event. */ const desktopPath = '/desktop'; const mobilePath = '/mobile'; const tabletPath = '/tablet'; const smarttvPath = '/smarttv'; if (headers['cloudfront-is-desktop-viewer'] && headers['cloudfront-is-desktop-viewer'][0].value === 'true') { request.uri = desktopPath + request.uri; } else if (headers['cloudfront-is-mobile-viewer'] && headers['cloudfront-is-mobile-viewer'][0].value === 'true') { request.uri = mobilePath + request.uri; } else if (headers['cloudfront-is-tablet-viewer'] && headers['cloudfront-is-tablet-viewer'][0].value === 'true') { request.uri = tabletPath + request.uri; } else if (headers['cloudfront-is-smarttv-viewer'] && headers['cloudfront-is-smarttv-viewer'][0].value === 'true') { request.uri = smarttvPath + request.uri; } console.log(`Request uri set to "${request.uri}"`); callback(null, request); }; ``` ------ #### [ Python ] ``` # This is an origin request function def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] headers = request['headers'] ''' Serve different versions of an object based on the device type. NOTE: 1. You must configure your distribution to cache based on the CloudFront-Is-*-Viewer headers. For more information, see the following documentation: https://docs.aws.amazon.com/console/cloudfront/cache-on-selected-headers https://docs.aws.amazon.com/console/cloudfront/cache-on-device-type 2. CloudFront adds the CloudFront-Is-*-Viewer headers after the viewer request event. To use this example, you must create a trigger for the origin request event. ''' desktopPath = '/desktop'; mobilePath = '/mobile'; tabletPath = '/tablet'; smarttvPath = '/smarttv'; if 'cloudfront-is-desktop-viewer' in headers and headers['cloudfront-is-desktop-viewer'][0]['value'] == 'true': request['uri'] = desktopPath + request['uri'] elif 'cloudfront-is-mobile-viewer' in headers and headers['cloudfront-is-mobile-viewer'][0]['value'] == 'true': request['uri'] = mobilePath + request['uri'] elif 'cloudfront-is-tablet-viewer' in headers and headers['cloudfront-is-tablet-viewer'][0]['value'] == 'true': request['uri'] = tabletPath + request['uri'] elif 'cloudfront-is-smarttv-viewer' in headers and headers['cloudfront-is-smarttv-viewer'][0]['value'] == 'true': request['uri'] = smarttvPath + request['uri'] print("Request uri set to %s" % request['uri']) return request ``` ------ ## Seleção de origem dinâmica baseada em conteúdo: exemplos Os exemplos a seguir mostram como você pode usar o Lambda@Edge para rotear para diferentes origens com base em informações na solicitação. **Topics** + [ ### Exemplo: usar um acionador de solicitação de origem para alterar de uma origem personalizada para uma origem do Amazon S3 ](#lambda-examples-content-based-S3-origin-based-on-query) + [ ### Exemplo: usar um acionador de solicitação de origem para alterar a região de origem do Amazon S3 ](#lambda-examples-content-based-S3-origin-request-trigger) + [ ### Exemplo: usar um acionador de solicitação de origem para alterar de uma origem do Amazon S3 para uma origem personalizada ](#lambda-examples-content-based-custom-origin-request-trigger) + [ ### Exemplo: usar um acionador de solicitação de origem para transferir gradualmente o tráfego de um bucket do Amazon S3 para outro ](#lambda-examples-content-based-gradual-traffic-transfer) + [ ### Exemplo: usar um acionador de solicitação de origem para alterar o nome do domínio de origem com base no cabeçalho do país ](#lambda-examples-content-based-geo-header) ### Exemplo: usar um acionador de solicitação de origem para alterar de uma origem personalizada para uma origem do Amazon S3 Essa função demonstra como um trigger origin-request pode ser usado para alterar de uma origem personalizada para uma origem do Amazon S3 da qual o conteúdo é obtido, com base nas propriedades da solicitação. ------ #### [ Node.js ] ``` 'use strict'; const querystring = require('querystring'); exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; /** * Reads query string to check if S3 origin should be used, and * if true, sets S3 origin properties. */ const params = querystring.parse(request.querystring); if (params['useS3Origin']) { if (params['useS3Origin'] === 'true') { const s3DomainName = 'amzn-s3-demo-bucket.s3.amazonaws.com'; /* Set S3 origin fields */ request.origin = { s3: { domainName: s3DomainName, region: '', authMethod: 'origin-access-identity', path: '', customHeaders: {} } }; request.headers['host'] = [{ key: 'host', value: s3DomainName}]; } } callback(null, request); }; ``` ------ #### [ Python ] ``` from urllib.parse import parse_qs def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] ''' Reads query string to check if S3 origin should be used, and if true, sets S3 origin properties ''' params = {k: v[0] for k, v in parse_qs(request['querystring']).items()} if params.get('useS3Origin') == 'true': s3DomainName = 'amzn-s3-demo-bucket.s3.amazonaws.com' # Set S3 origin fields request['origin'] = { 's3': { 'domainName': s3DomainName, 'region': '', 'authMethod': 'origin-access-identity', 'path': '', 'customHeaders': {} } } request['headers']['host'] = [{'key': 'host', 'value': s3DomainName}] return request ``` ------ ### Exemplo: usar um acionador de solicitação de origem para alterar a região de origem do Amazon S3 Esta função demonstra como um trigger origin-request pode ser usado para alterar a origem do Amazon S3 da qual o conteúdo é obtido, com base nas propriedades da solicitação. Neste exemplo, usamos o valor do cabeçalho `CloudFront-Viewer-Country` para atualizar o nome do domínio de bucket do S3 para um bucket em uma região mais próxima do visualizador. Isso pode ser útil de várias maneiras: + Reduz as latências quando a região especificada estiver mais próxima do país do visualizador. + Fornece soberania de dados, garantindo que os dados sejam oferecidos de uma origem que esteja no mesmo país de onde veio a solicitação. Para usar esse exemplo, você precisa fazer o seguinte: + Configure sua distribuição para armazenar em cache com base no cabeçalho `CloudFront-Viewer-Country`. Para obter mais informações, consulte [Cache baseado em Cabeçalhos de solicitação selecionados](DownloadDistValuesCacheBehavior.md#DownloadDistValuesForwardHeaders). + Crie um gatilho para essa função no evento de solicitação de origem. O CloudFront adiciona o cabeçalho `CloudFront-Viewer-Country` após o evento de solicitação do visualizador. Portanto, para usar este exemplo, você precisa garantir que a função seja executada para uma solicitação de origem. **nota** O código de exemplo a seguir usa a mesma identidade do acesso de origem (OAI) para todos os buckets do S3 que você está usando para sua origem. Para ter mais informações, consulte [Visão geral da identidade do acesso de origem](private-content-restricting-access-to-s3.md#private-content-restricting-access-to-s3-oai). ------ #### [ Node.js ] ``` 'use strict'; exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; /** * This blueprint demonstrates how an origin-request trigger can be used to * change the origin from which the content is fetched, based on request properties. * In this example, we use the value of the CloudFront-Viewer-Country header * to update the S3 bucket domain name to a bucket in a Region that is closer to * the viewer. * * This can be useful in several ways: * 1) Reduces latencies when the Region specified is nearer to the viewer's * country. * 2) Provides data sovereignty by making sure that data is served from an * origin that's in the same country that the request came from. * * NOTE: 1. You must configure your distribution to cache based on the * CloudFront-Viewer-Country header. For more information, see * https://docs.aws.amazon.com/console/cloudfront/cache-on-selected-headers * 2. CloudFront adds the CloudFront-Viewer-Country header after the viewer * request event. To use this example, you must create a trigger for the * origin request event. */ const countryToRegion = { 'DE': 'eu-central-1', 'IE': 'eu-west-1', 'GB': 'eu-west-2', 'FR': 'eu-west-3', 'JP': 'ap-northeast-1', 'IN': 'ap-south-1' }; if (request.headers['cloudfront-viewer-country']) { const countryCode = request.headers['cloudfront-viewer-country'][0].value; const region = countryToRegion[countryCode]; /** * If the viewer's country is not in the list you specify, the request * goes to the default S3 bucket you've configured. */ if (region) { /** * If you've set up OAI, the bucket policy in the destination bucket * should allow the OAI GetObject operation, as configured by default * for an S3 origin with OAI. Another requirement with OAI is to provide * the Region so it can be used for the SIGV4 signature. Otherwise, the * Region is not required. */ request.origin.s3.region = region; const domainName = `amzn-s3-demo-bucket-in-${region}.s3.${region}.amazonaws.com`; request.origin.s3.domainName = domainName; request.headers['host'] = [{ key: 'host', value: domainName }]; } } callback(null, request); }; ``` ------ #### [ Python ] ``` def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] ''' This blueprint demonstrates how an origin-request trigger can be used to change the origin from which the content is fetched, based on request properties. In this example, we use the value of the CloudFront-Viewer-Country header to update the S3 bucket domain name to a bucket in a Region that is closer to the viewer. This can be useful in several ways: 1) Reduces latencies when the Region specified is nearer to the viewer's country. 2) Provides data sovereignty by making sure that data is served from an origin that's in the same country that the request came from. NOTE: 1. You must configure your distribution to cache based on the CloudFront-Viewer-Country header. For more information, see https://docs.aws.amazon.com/console/cloudfront/cache-on-selected-headers 2. CloudFront adds the CloudFront-Viewer-Country header after the viewer request event. To use this example, you must create a trigger for the origin request event. ''' countryToRegion = { 'DE': 'eu-central-1', 'IE': 'eu-west-1', 'GB': 'eu-west-2', 'FR': 'eu-west-3', 'JP': 'ap-northeast-1', 'IN': 'ap-south-1' } viewerCountry = request['headers'].get('cloudfront-viewer-country') if viewerCountry: countryCode = viewerCountry[0]['value'] region = countryToRegion.get(countryCode) # If the viewer's country in not in the list you specify, the request # goes to the default S3 bucket you've configured if region: ''' If you've set up OAI, the bucket policy in the destination bucket should allow the OAI GetObject operation, as configured by default for an S3 origin with OAI. Another requirement with OAI is to provide the Region so it can be used for the SIGV4 signature. Otherwise, the Region is not required. ''' request['origin']['s3']['region'] = region domainName = 'amzn-s3-demo-bucket-in-{0}.s3.{0}.amazonaws.com'.format(region) request['origin']['s3']['domainName'] = domainName request['headers']['host'] = [{'key': 'host', 'value': domainName}] return request ``` ------ ### Exemplo: usar um acionador de solicitação de origem para alterar de uma origem do Amazon S3 para uma origem personalizada Esta função demonstra como um trigger de origem-solicitação pode ser usado para alterar a origem personalizada de onde o conteúdo é obtido, com base nas propriedades da solicitação. ------ #### [ Node.js ] ``` 'use strict'; const querystring = require('querystring'); exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; /** * Reads query string to check if custom origin should be used, and * if true, sets custom origin properties. */ const params = querystring.parse(request.querystring); if (params['useCustomOrigin']) { if (params['useCustomOrigin'] === 'true') { /* Set custom origin fields*/ request.origin = { custom: { domainName: 'www.example.com', port: 443, protocol: 'https', path: '', sslProtocols: ['TLSv1', 'TLSv1.1'], readTimeout: 5, keepaliveTimeout: 5, customHeaders: {} } }; request.headers['host'] = [{ key: 'host', value: 'www.example.com'}]; } } callback(null, request); }; ``` ------ #### [ Python ] ``` from urllib.parse import parse_qs def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] # Reads query string to check if custom origin should be used, and # if true, sets custom origin properties params = {k: v[0] for k, v in parse_qs(request['querystring']).items()} if params.get('useCustomOrigin') == 'true': # Set custom origin fields request['origin'] = { 'custom': { 'domainName': 'www.example.com', 'port': 443, 'protocol': 'https', 'path': '', 'sslProtocols': ['TLSv1', 'TLSv1.1'], 'readTimeout': 5, 'keepaliveTimeout': 5, 'customHeaders': {} } } request['headers']['host'] = [{'key': 'host', 'value': 'www.example.com'}] return request ``` ------ ### Exemplo: usar um acionador de solicitação de origem para transferir gradualmente o tráfego de um bucket do Amazon S3 para outro Essa função demonstra como transferir o tráfego de um bucket do Amazon S3 para outro de forma gradual e controlada. ------ #### [ Node.js ] ``` 'use strict'; function getRandomInt(min, max) { /* Random number is inclusive of min and max*/ return Math.floor(Math.random() * (max - min + 1)) + min; } exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; const BLUE_TRAFFIC_PERCENTAGE = 80; /** * This Lambda function demonstrates how to gradually transfer traffic from * one S3 bucket to another in a controlled way. * We define a variable BLUE_TRAFFIC_PERCENTAGE which can take values from * 1 to 100. If the generated randomNumber less than or equal to BLUE_TRAFFIC_PERCENTAGE, traffic * is re-directed to blue-bucket. If not, the default bucket that we've configured * is used. */ const randomNumber = getRandomInt(1, 100); if (randomNumber <= BLUE_TRAFFIC_PERCENTAGE) { const domainName = 'blue-bucket.s3.amazonaws.com'; request.origin.s3.domainName = domainName; request.headers['host'] = [{ key: 'host', value: domainName}]; } callback(null, request); }; ``` ------ #### [ Python ] ``` import math import random def getRandomInt(min, max): # Random number is inclusive of min and max return math.floor(random.random() * (max - min + 1)) + min def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] BLUE_TRAFFIC_PERCENTAGE = 80 ''' This Lambda function demonstrates how to gradually transfer traffic from one S3 bucket to another in a controlled way. We define a variable BLUE_TRAFFIC_PERCENTAGE which can take values from 1 to 100. If the generated randomNumber less than or equal to BLUE_TRAFFIC_PERCENTAGE, traffic is re-directed to blue-bucket. If not, the default bucket that we've configured is used. ''' randomNumber = getRandomInt(1, 100) if randomNumber <= BLUE_TRAFFIC_PERCENTAGE: domainName = 'blue-bucket.s3.amazonaws.com' request['origin']['s3']['domainName'] = domainName request['headers']['host'] = [{'key': 'host', 'value': domainName}] return request ``` ------ ### Exemplo: usar um acionador de solicitação de origem para alterar o nome do domínio de origem com base no cabeçalho do país Esta função demonstra como você pode alterar o nome de domínio de origem com base no cabeçalho `CloudFront-Viewer-Country`, de forma que o conteúdo seja fornecido de origem mais próxima do país do visualizador. A implementação dessa funcionalidade para sua distribuição pode ter vantagens, como as seguintes: + Redução das latências quando a região especificada estiver mais próxima do país do visualizador + Fornecimento da soberania de dados garantindo que os dados sejam fornecidos de uma origem que esteja no mesmo país de onde veio a solicitação Observe que, para habilitar essa funcionalidade, você deve configurar sua distribuição para o cache com base no cabeçalho `CloudFront-Viewer-Country`. Para obter mais informações, consulte [Cache baseado em Cabeçalhos de solicitação selecionados](DownloadDistValuesCacheBehavior.md#DownloadDistValuesForwardHeaders). ------ #### [ Node.js ] ``` 'use strict'; exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; if (request.headers['cloudfront-viewer-country']) { const countryCode = request.headers['cloudfront-viewer-country'][0].value; if (countryCode === 'GB' || countryCode === 'DE' || countryCode === 'IE' ) { const domainName = 'eu.example.com'; request.origin.custom.domainName = domainName; request.headers['host'] = [{key: 'host', value: domainName}]; } } callback(null, request); }; ``` ------ #### [ Python ] ``` def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] viewerCountry = request['headers'].get('cloudfront-viewer-country') if viewerCountry: countryCode = viewerCountry[0]['value'] if countryCode == 'GB' or countryCode == 'DE' or countryCode == 'IE': domainName = 'eu.example.com' request['origin']['custom']['domainName'] = domainName request['headers']['host'] = [{'key': 'host', 'value': domainName}] return request ``` ------ ## Atualização do status de erro: exemplos Os exemplos a seguir fornecem orientações sobre como você pode usar o Lambda@Edge para alterar o status de erro retornado para os usuários. **Topics** + [ ### Exemplo: usar um acionador de resposta de origem para atualizar o código do status de erro para 200 ](#lambda-examples-custom-error-static-body) + [ ### Exemplo: usar um acionador de resposta de origem para atualizar o código do status de erro para 302 ](#lambda-examples-custom-error-new-site) ### Exemplo: usar um acionador de resposta de origem para atualizar o código do status de erro para 200 Esta função demonstra como você pode atualizar o status da resposta para 200 e gerar conteúdo do corpo estático para retornar ao visualizador no cenário a seguir: + A função é acionada em uma resposta da origem. + O status da resposta do servidor de origem é um código de status de erro (4xx ou 5xx). ------ #### [ Node.js ] ``` 'use strict'; exports.handler = (event, context, callback) => { const response = event.Records[0].cf.response; /** * This function updates the response status to 200 and generates static * body content to return to the viewer in the following scenario: * 1. The function is triggered in an origin response * 2. The response status from the origin server is an error status code (4xx or 5xx) */ if (response.status >= 400 && response.status <= 599) { response.status = 200; response.statusDescription = 'OK'; response.body = 'Body generation example'; } callback(null, response); }; ``` ------ #### [ Python ] ``` def lambda_handler(event, context): response = event['Records'][0]['cf']['response'] ''' This function updates the response status to 200 and generates static body content to return to the viewer in the following scenario: 1. The function is triggered in an origin response 2. The response status from the origin server is an error status code (4xx or 5xx) ''' if int(response['status']) >= 400 and int(response['status']) <= 599: response['status'] = 200 response['statusDescription'] = 'OK' response['body'] = 'Body generation example' return response ``` ------ ### Exemplo: usar um acionador de resposta de origem para atualizar o código do status de erro para 302 Essa função demonstra como você pode atualizar o código de status HTTP para 302, de forma a redirecionar a outro caminho (comportamento de cache) que tem uma origem diferente configurada. Observe o seguinte: + A função é acionada em uma resposta da origem. + O status da resposta do servidor de origem é um código de status de erro (4xx ou 5xx). ------ #### [ Node.js ] ``` 'use strict'; exports.handler = (event, context, callback) => { const response = event.Records[0].cf.response; const request = event.Records[0].cf.request; /** * This function updates the HTTP status code in the response to 302, to redirect to another * path (cache behavior) that has a different origin configured. Note the following: * 1. The function is triggered in an origin response * 2. The response status from the origin server is an error status code (4xx or 5xx) */ if (response.status >= 400 && response.status <= 599) { const redirect_path = `/plan-b/path?${request.querystring}`; response.status = 302; response.statusDescription = 'Found'; /* Drop the body, as it is not required for redirects */ response.body = ''; response.headers['location'] = [{ key: 'Location', value: redirect_path }]; } callback(null, response); }; ``` ------ #### [ Python ] ``` def lambda_handler(event, context): response = event['Records'][0]['cf']['response'] request = event['Records'][0]['cf']['request'] ''' This function updates the HTTP status code in the response to 302, to redirect to another path (cache behavior) that has a different origin configured. Note the following: 1. The function is triggered in an origin response 2. The response status from the origin server is an error status code (4xx or 5xx) ''' if int(response['status']) >= 400 and int(response['status']) <= 599: redirect_path = '/plan-b/path?%s' % request['querystring'] response['status'] = 302 response['statusDescription'] = 'Found' # Drop the body as it is not required for redirects response['body'] = '' response['headers']['location'] = [{'key': 'Location', 'value': redirect_path}] return response ``` ------ ## Acesso ao corpo da solicitação: exemplos Os exemplos a seguir mostram como você pode usar o Lambda@Edge para trabalhar com solicitações POST. **nota** Para usar esses exemplos, você deve habilitar a opção *include body* (incluir corpo) na associação da função do Lambda da distribuição. Ele não é habilitado por padrão. Para habilitar essa configuração no console do CloudFront, marque a caixa de seleção **Include Body (Incluir corpo)** na **Lambda Function Association (Associação de função do Lambda)**. Para habilitar essa configuração na API do CloudFront ou com o CloudFormation, defina o campo `IncludeBody` como `true` em `LambdaFunctionAssociation`. **Topics** + [ ### Exemplo: usar um acionador de solicitação para ler um formulário HTML ](#lambda-examples-access-request-body-examples-read) + [ ### Exemplo: usar um acionador de solicitação para modificar um formulário HTML ](#lambda-examples-access-request-body-examples-replace) ### Exemplo: usar um acionador de solicitação para ler um formulário HTML Essa função demonstra como você pode processar o corpo de uma solicitação POST gerada por um formulário HTML (formulário da web), como um formulário "entre em contato conosco". Por exemplo, você pode ter um formulário em HTML como o seguinte: ``` ``` No exemplo a seguir, a função deve ser acionada em uma solicitação de origem ou de um visualizador do CloudFront. ------ #### [ Node.js ] ``` 'use strict'; const querystring = require('querystring'); /** * This function demonstrates how you can read the body of a POST request * generated by an HTML form (web form). The function is triggered in a * CloudFront viewer request or origin request event type. */ exports.handler = (event, context, callback) => { const request = event.Records[0].cf.request; if (request.method === 'POST') { /* HTTP body is always passed as base64-encoded string. Decode it. */ const body = Buffer.from(request.body.data, 'base64').toString(); /* HTML forms send the data in query string format. Parse it. */ const params = querystring.parse(body); /* For demonstration purposes, we only log the form fields here. * You can put your custom logic here. For example, you can store the * fields in a database, such as Amazon DynamoDB, and generate a response * right from your Lambda@Edge function. */ for (let param in params) { console.log(`For "${param}" user submitted "${params[param]}".\n`); } } return callback(null, request); }; ``` ------ #### [ Python ] ``` import base64 from urllib.parse import parse_qs ''' Say there is a POST request body generated by an HTML such as: ''' ''' This function demonstrates how you can read the body of a POST request generated by an HTML form (web form). The function is triggered in a CloudFront viewer request or origin request event type. ''' def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] if request['method'] == 'POST': # HTTP body is always passed as base64-encoded string. Decode it body = base64.b64decode(request['body']['data']) # HTML forms send the data in query string format. Parse it params = {k: v[0] for k, v in parse_qs(body).items()} ''' For demonstration purposes, we only log the form fields here. You can put your custom logic here. For example, you can store the fields in a database, such as Amazon DynamoDB, and generate a response right from your Lambda@Edge function. ''' for key, value in params.items(): print("For %s use submitted %s" % (key, value)) return request ``` ------ ### Exemplo: usar um acionador de solicitação para modificar um formulário HTML Essa função demonstra como você pode modificar o corpo de uma solicitação POST gerada por um formulário HTML (formulário da web). A função é acionada em uma solicitação de origem ou de visualizador do CloudFront. ------ #### [ Node.js ] ``` 'use strict'; const querystring = require('querystring'); exports.handler = (event, context, callback) => { var request = event.Records[0].cf.request; if (request.method === 'POST') { /* Request body is being replaced. To do this, update the following /* three fields: * 1) body.action to 'replace' * 2) body.encoding to the encoding of the new data. * * Set to one of the following values: * * text - denotes that the generated body is in text format. * Lambda@Edge will propagate this as is. * base64 - denotes that the generated body is base64 encoded. * Lambda@Edge will base64 decode the data before sending * it to the origin. * 3) body.data to the new body. */ request.body.action = 'replace'; request.body.encoding = 'text'; request.body.data = getUpdatedBody(request); } callback(null, request); }; function getUpdatedBody(request) { /* HTTP body is always passed as base64-encoded string. Decode it. */ const body = Buffer.from(request.body.data, 'base64').toString(); /* HTML forms send data in query string format. Parse it. */ const params = querystring.parse(body); /* For demonstration purposes, we're adding one more param. * * You can put your custom logic here. For example, you can truncate long * bodies from malicious requests. */ params['new-param-name'] = 'new-param-value'; return querystring.stringify(params); } ``` ------ #### [ Python ] ``` import base64 from urllib.parse import parse_qs, urlencode def lambda_handler(event, context): request = event['Records'][0]['cf']['request'] if request['method'] == 'POST': ''' Request body is being replaced. To do this, update the following three fields: 1) body.action to 'replace' 2) body.encoding to the encoding of the new data. Set to one of the following values: text - denotes that the generated body is in text format. Lambda@Edge will propagate this as is. base64 - denotes that the generated body is base64 encoded. Lambda@Edge will base64 decode the data before sending it to the origin. 3) body.data to the new body. ''' request['body']['action'] = 'replace' request['body']['encoding'] = 'text' request['body']['data'] = getUpdatedBody(request) return request def getUpdatedBody(request): # HTTP body is always passed as base64-encoded string. Decode it body = base64.b64decode(request['body']['data']) # HTML forms send data in query string format. Parse it params = {k: v[0] for k, v in parse_qs(body).items()} # For demonstration purposes, we're adding one more param # You can put your custom logic here. For example, you can truncate long # bodies from malicious requests params['new-param-name'] = 'new-param-value' return urlencode(params) ``` ------ # Restrições das funções de borda Os tópicos a seguir descrevem as restrições aplicáveis ao CloudFront Functions e ao Lambda@Edge. Algumas restrições aplicam-se a todas as funções de borda, enquanto outras são válidas apenas para o CloudFront Functions ou o Lambda@Edge. Cada tópico fornece informações detalhadas sobre as limitações e as restrições a serem levadas em conta no desenvolvimento e na implantação de funções de borda com o CloudFront. Compreender essas restrições ajuda a garantir que as funções de borda se comportem conforme o esperado e estejam em conformidade com os recursos compatíveis. **Topics** + [ # Restrições de todas as funções de borda ](edge-function-restrictions-all.md) + [ # Restrições do CloudFront Functions ](cloudfront-function-restrictions.md) + [ # Restrições ao Lambda@Edge ](lambda-at-edge-function-restrictions.md) Para obter mais informações sobre cotas (anteriormente chamadas de limites), consulte [Cotas no CloudFront Functions](cloudfront-limits.md#limits-functions) e [Cotas do Lambda@Edge](cloudfront-limits.md#limits-lambda-at-edge). # Restrições de todas as funções de borda As restrições a seguir aplicam-se a todas as funções de borda, tanto ao CloudFront Functions quanto ao Lambda@Edge. **Topics** + [ ## Conta da AWSPropriedade da ](#function-restrictions-account-ownership) + [ ## Combinação do CloudFront Functions ao Lambda@Edge ](#function-restrictions-combining-functions) + [ ## Códigos de status de HTTP ](#function-restrictions-status-codes) + [ ## Cabeçalhos HTTP ](#function-restrictions-headers) + [ ## Strings de consulta ](#function-restrictions-query-strings) + [ ## URI ](#function-restrictions-uri) + [ ## Codificação de URI, string de consulta e cabeçalhos ](#function-restrictions-encoding) + [ ## Microsoft Smooth Streaming ](#function-restrictions-microsoft-smooth-streaming) + [ ## Tags ](#function-restrictions-tagging) ## Conta da AWSPropriedade da Para associar uma função de borda a uma distribuição do CloudFront, a função e a distribuição devem pertencer à mesma Conta da AWS. ## Combinação do CloudFront Functions ao Lambda@Edge Para um determinado comportamento de cache, as seguintes restrições são aplicáveis: + Cada tipo de evento (solicitação do visualizador, solicitação de origem, resposta de origem e resposta do visualizador) pode ter apenas uma associação de função de borda. + Não é possível combinar o CloudFront Functions e o Lambda@Edge em eventos do visualizador (solicitação do visualizador e resposta do visualizador). Todas as demais combinações de funções de borda são permitidas. A tabela a seguir explica as combinações permitidas. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonCloudFront/latest/DeveloperGuide/edge-function-restrictions-all.html) ## Códigos de status de HTTP O CloudFront não invocará funções de borda para eventos de resposta do visualizador se a origem retornar um código de status HTTP 400 ou superior. As funções do Lambda@Edge para eventos de resposta de origem são chamadas para *todas* as respostas de origem, incluindo quando a origem retorna um código de status HTTP 400 ou superior. Para obter mais informações, consulte [Atualizar respostas de HTTP em acionadores de resposta da origem](lambda-generating-http-responses.md#lambda-updating-http-responses). ## Cabeçalhos HTTP Determinados cabeçalhos HTTP não são permitidos, o que significa que eles não estão expostos a funções de borda e as funções não podem adicioná-los. Outros cabeçalhos são somente leitura, o que significa que as funções podem lê-los, mas não podem adicioná-los, modificá-los nem excluí-los. **Topics** + [ ### Cabeçalhos não permitidos ](#function-restrictions-disallowed-headers) + [ ### Cabeçalhos somente leitura ](#function-restrictions-read-only-headers) ### Cabeçalhos não permitidos Os cabeçalhos HTTP a seguir não são expostos a funções de borda e as funções não podem adicioná-los. Se sua função adicionar um desses cabeçalhos, o CloudFront não a validará e retornará o código de status HTTP 502 (gateway inválido) para o visualizador. + `Connection` + `Expect` + `Keep-Alive` + `Proxy-Authenticate` + `Proxy-Authorization` + `Proxy-Connection` + `Trailer` + `Upgrade` + `X-Accel-Buffering` + `X-Accel-Charset` + `X-Accel-Limit-Rate` + `X-Accel-Redirect` + `X-Amz-Cf-*` + `X-Amzn-Auth` + `X-Amzn-Cf-Billing` + `X-Amzn-Cf-Id` + `X-Amzn-Cf-Xff` + `X-Amzn-Errortype` + `X-Amzn-Fle-Profile` + `X-Amzn-Header-Count` + `X-Amzn-Header-Order` + `X-Amzn-Lambda-Integration-Tag` + `X-Amzn-RequestId` + `X-Cache` + `X-Edge-*` + `X-Forwarded-Proto` + `X-Real-IP` ### Cabeçalhos somente leitura Os cabeçalhos a seguir são somente leitura. Sua função pode lê-los ou usá-los como entrada para a lógica da função, mas não podem alterar os valores. Se sua função adicionar ou editar um cabeçalho somente leitura, a solicitação falhará na validação do CloudFront, o qual retornará o código de status HTTP 502 (gateway inválido) para o visualizador. #### Cabeçalhos somente leitura em eventos de solicitação do visualizador Os cabeçalhos a seguir são somente leitura em eventos de solicitação do visualizador. + `Content-Length` + `Host` + `Transfer-Encoding` + `Via` #### Cabeçalhos somente leitura em eventos de solicitação de origem (somente Lambda@Edge) Os seguintes cabeçalhos são somente leitura em eventos de solicitação de origem, os quais existem apenas no Lambda@Edge. + `Accept-Encoding` + `Content-Length` + `If-Modified-Since` + `If-None-Match` + `If-Range` + `If-Unmodified-Since` + `Transfer-Encoding` + `Via` #### Cabeçalhos somente leitura em eventos de resposta de origem (somente Lambda@Edge) Os seguintes cabeçalhos são somente leitura em eventos de resposta de origem, os quais existem apenas no Lambda@Edge. + `Transfer-Encoding` + `Via` #### Cabeçalhos somente leitura em eventos de resposta do visualizador Os cabeçalhos a seguir são somente leitura em eventos de resposta do visualizador para o CloudFront Functions e para o Lambda@Edge. + `Warning` + `Via` Os cabeçalhos a seguir são somente leitura em eventos de resposta do visualizador para o Lambda@Edge. + `Content-Length` + `Content-Encoding` + `Transfer-Encoding` ## Strings de consulta As restrições a seguir aplicam-se a funções que leem, atualizam ou criam uma string de consulta em um URI de solicitação. + (Somente Lambda@Edge) Para acessar a string de consulta em uma solicitação de origem ou função de resposta de origem, sua política de cache ou política de solicitação de origem deve ser definida como **All** (Todas) para **Query strings** (Strings de consulta). + Uma função pode criar ou atualizar uma string de consulta para eventos de solicitação do visualizador e solicitação da origem (eventos de solicitação da origem existem apenas no Lambda@Edge). + Uma função pode ler uma string de consulta, mas não pode criar ou atualizar uma, para eventos de resposta da origem e resposta do visualizador (eventos de resposta da origem existem apenas no Lambda@Edge). + Se uma função criar ou atualizar uma string de consulta, as seguintes restrições se aplicarão: + A string de consulta não pode incluir espaços, caracteres de controle nem o identificador de fragmento (`#`). + O tamanho total do URI, incluindo a string de consulta, deve ser menor que 8.192 caracteres. + Recomendamos o uso de codificação percentual para o URI e a string de consulta. Para obter mais informações, consulte [Codificação de URI, string de consulta e cabeçalhos](#function-restrictions-encoding). ## URI Se uma função alterar o URI para uma solicitação, o comportamento do cache da solicitação ou a origem para a qual a solicitação é encaminhada não será alterada. O tamanho total do URI, incluindo a string de consulta, deve ser menor que 8.192 caracteres. ## Codificação de URI, string de consulta e cabeçalhos Os valores de string de consulta e de URI e os cabeçalhos transmitidos para as funções de borda são codificados em UTF-8. A função deve usar codificação UTF-8 para os valores de URI, de string de consulta e de cabeçalhos exibidos. A codificação percentual é compatível com a codificação UTF-8. A seguinte lista explica como o CloudFront lida com a codificação de URI, string de consulta e cabeçalhos: + Quando os valores na solicitação são codificados em UTF-8, o CloudFront encaminha os valores para a função sem alterá-los. + Quando os valores na solicitação são [codificados em ISO-8859-1](https://en.wikipedia.org/wiki/ISO/IEC_8859-1), o CloudFront os converte para a codificação UTF-8 antes de encaminhá-los para sua função. + Quando os valores na solicitação são codificados usando qualquer outra codificação de caracteres, o CloudFront assume que eles estão codificados em ISO 8859-1 e tenta convertê-los de ISO-8859-1 em UTF-8. **Importante** A versão convertida pode ser uma interpretação imprecisa dos valores da solicitação original. Isso pode fazer com que sua função ou origem produzam um resultado indesejado. Os valores de URI, de string de consulta e de cabeçalhos que o CloudFront encaminhará à sua origem dependerão de uma função alterá-los ou não: + Se uma função não alterar o URI, a string de consulta ou o cabeçalho, o CloudFront encaminhará à origem os valores recebidos na solicitação. + Se uma função alterar o URI, a string de consulta ou o cabeçalho, o CloudFront encaminhará os valores codificados em UTF-8. ## Microsoft Smooth Streaming Não é possível usar funções de borda com uma distribuição do CloudFront utilizada em streaming de arquivos de mídia transcodificados no formato Microsoft Smooth Streaming. ## Tags Não é possível adicionar tags a funções de borda. Consulte mais informações sobre marcação no CloudFront em [Marcar uma distribuição](tagging.md). # Restrições do CloudFront Functions As restrições a seguir aplicam-se somente ao CloudFront Functions. **Contents** + [ ## Logs ](#cloudfront-function-restrictions-logs) + [ ## Corpo da solicitação ](#cloudfront-function-restrictions-request-body) + [ ## Usar credenciais temporárias com a API KeyValueStore do CloudFront ](#regional-endpoint-for-key-value-store) + [ ## Runtime ](#cloudfront-function-runtime-restrictions) + [ ## Utilização de recursos de computação ](#cloudfront-function-restrictions-compute-utilization) Para ter mais informações sobre cotas (anteriormente chamadas de limites), consulte [Cotas no CloudFront Functions](cloudfront-limits.md#limits-functions). ## Logs Os logs de função no CloudFront Functions são truncados em 10 KB. ## Corpo da solicitação O CloudFront Functions não pode acessar o corpo da solicitação HTTP. ## Usar credenciais temporárias com a API KeyValueStore do CloudFront É possível usar o AWS Security Token Service (AWS STS) para gerar credenciais de segurança temporárias (também conhecidas como *tokens de sessão*). Os tokens de sessão permitem assumir temporariamente um perfil do AWS Identity and Access Management (IAM) para que você possa acessar Serviços da AWS. Para chamar a [API KeyValueStore do CloudFront](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_Operations_Amazon_CloudFront_KeyValueStore.html), use um endpoint *Regional* no AWS STS para exibir um token de sessão da *versão 2*. Se você usar o endpoint *global* para o AWS STS (`sts.amazonaws.com`), o AWS STS vai gerar um token de sessão da *versão 1*, que não é compatível com o Signature Version 4A (SigV4A). Como consequência, você receberá um erro de autenticação. Para chamar a API KeyValueStore do CloudFront, é possível usar as seguintes opções: **AWS CLI e AWS SDKs** É possível configurar a AWS CLI ou um SDK da AWS para usar endpoints regionais do AWS STS. Para ter mais informações, consulte [AWS STS Regionalized endpoints](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sts-regionalized-endpoints.html) no *Guia de referência de ferramentas e SDKs da AWS*. Para ter mais informações sobre endpoints do AWS STS, consulte [Regiões e endpoints](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#id_credentials_region-endpoints) no *Guia do usuário do IAM*. **SAML** É possível configurar o SAML para usar endpoints regionais do AWS STS. Para ter mais informações, consulte a publicação de blog [How to use regional SAML endpoints for failover](https://aws.amazon.com/blogs/security/how-to-use-regional-saml-endpoints-for-failover/). **`SetSecurityTokenServicePreferences`API ** Em vez de usar um endpoint regional do AWS STS, é possível configurar o endpoint global para o AWS STS para exibir tokens de sessão da versão 2. Use a operação de API [SetSecurityTokenServicePreferences](https://docs.aws.amazon.com/IAM/latest/APIReference/API_SetSecurityTokenServicePreferences.html) para fazer isso e configurar a Conta da AWS. **Example Exemplo: comando da CLI do IAM** ``` aws iam set-security-token-service-preferences --global-endpoint-token-version v2Token ``` Recomendamos usar endpoints regionais do AWS STS em vez dessa opção. Os endpoints regionais oferecem maior disponibilidade e casos de failover. **Provedor de identidades personalizado** Se você estiver usando um provedor de identidades personalizado que faça a federação e assuma o perfil, use uma das opções anteriores para o sistema de provedor de identidades principal responsável por gerar o token de sessão. ## Runtime O ambiente de runtime do CloudFront Functions não permite a avaliação dinâmica de código e restringe o acesso à rede, ao sistema de arquivos, às variáveis do ambiente e aos temporizadores. Para obter mais informações, consulte [Recursos restritos](functions-javascript-runtime-10.md#writing-functions-javascript-features-restricted-features). **nota** Para usar o CloudFront KeyValueStore, a função do CloudFront deve usar o [runtime 2.0 do JavaScript.](functions-javascript-runtime-20.md) ## Utilização de recursos de computação O CloudFront Functions tem um limite de tempo para executar, o qual é medido como *Utilização de recursos de computação*. A utilização de recursos de computação é um número entre 0 e 100 que indica a quantidade de tempo que a função levou para ser executada como um percentual do tempo máximo permitido. Por exemplo, uma utilização de computação de 35 significa que a função foi concluída em 35% do tempo máximo permitido. Quando você [testa uma função](test-function.md), é possível ver o valor de utilização de recursos de computação na saída do evento de teste. Para funções de produção, você pode visualizar a [compute utilization metric](viewing-cloudfront-metrics.md#monitoring-console.cloudfront-functions) (métrica de utilização de recursos de computação) na [Página de monitoramento no console do CloudFront](https://console.aws.amazon.com/cloudfront/v4/home?#/monitoring) ou no CloudWatch. # Restrições ao Lambda@Edge As restrições a seguir aplicam-se somente ao Lambda@Edge. **Contents** + [ ## Resolução do DNS ](#lambda-at-edge-restrictions-dns) + [ ## Códigos de status de HTTP ](#lambda-at-edge-restrictions-status-codes) + [ ## Versionamento da função do Lambda ](#lambda-at-edge-restrictions-version) + [ ## Região do Lambda ](#lambda-at-edge-restrictions-region) + [ ## Permissões de função do Lambda ](#lambda-at-edge-restrictions-role-permissions) + [ ## Recursos do Lambda ](#lambda-at-edge-restrictions-features) + [ ## Tempos de execução compatíveis ](#lambda-at-edge-restrictions-runtime) + [ ## Cabeçalhos do CloudFront ](#lambda-at-edge-restrictions-cloudfront-headers) + [ ## Restrições do corpo da solicitação com a opção de incluir corpo ](#lambda-at-edge-restrictions-request-body) + [ ## Tempo limite de resposta e de manutenção (somente origens personalizadas) ](#timeout-for-lambda-edge-functions) Para obter informações sobre cotas do , consulte [Cotas do Lambda@Edge](cloudfront-limits.md#limits-lambda-at-edge). ## Resolução do DNS O CloudFront executa uma resolução de DNS no nome de domínio da origem *antes* de executar a solicitação de origem da função do Lambda@Edge. Se o serviço DNS do domínio estiver com problemas e o CloudFront não puder resolver o nome de domínio para obter o endereço IP, a função do Lambda@Edge não será invocada. O CloudFront retornará um [código de status HTTP 502 (gateway inativo)](http-502-bad-gateway.md) ao cliente. Para obter mais informações, consulte [Erro de DNS (`NonS3OriginDnsError`)](http-502-bad-gateway.md#http-502-dns-error). Se a lógica da função modificar o nome de domínio de origem, o CloudFront executará outra resolução de DNS no nome de domínio atualizado após a conclusão da execução da função. Para ter mais informações sobre como gerenciar failover de DNS, consulte [Configurar failover de DNS](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-failover-configuring.html) no *Guia do desenvolvedor do Amazon Route 53*. ## Códigos de status de HTTP As funções do Lambda@Edge para eventos de resposta do visualizador não podem modificar o código de status HTTP da resposta, independentemente de a resposta ter vindo da origem ou do cache do CloudFront. ## Versionamento da função do Lambda Você deve usar uma versão numerada da função do Lambda, e não `$LATEST` nem aliases. ## Região do Lambda A função do Lambda deve estar na região Leste dos EUA (Norte da Virgínia). ## Permissões de função do Lambda A função de execução do IAM associada à função do Lambda deve permitir que os principais de serviço `lambda.amazonaws.com` e `edgelambda.amazonaws.com` assumam a função. Para obter mais informações, consulte [Configurar permissões e perfis do IAM para o Lambda@Edge](lambda-edge-permissions.md). ## Recursos do Lambda Os seguintes recursos do Lambda não são compatíveis com o Lambda@Edge: + [Configurações de gerenciamento de runtime do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-update.html#runtime-management-controls) diferentes de **Auto** (padrão) + Configuração de sua função do Lambda para acessar recursos na VPC + [Filas de mensagens não entregues da função do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/invocation-async.html#dlq) + [Variáveis de ambiente do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html) (exceto variáveis de ambiente reservadas, que são automaticamente compatíveis) + Funções do Lambda com [Gerenciar dependências do AWS Lambda com camadas](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html) + [Usar o AWS X-Ray](https://docs.aws.amazon.com/lambda/latest/dg/lambda-x-ray.html) + Simultaneidade provisionada do Lambda **nota** As funções do Lambda@Edge têm os mesmos recursos de [Simultaneidade regional](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html) que as funções do Lambda. Para obter mais informações, consulte [Cotas do Lambda@Edge](cloudfront-limits.md#limits-lambda-at-edge). + [Criar uma função do Lambda usando uma imagem de contêiner](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html) + [Funções do Lambda que usam a arquitetura arm](https://docs.aws.amazon.com/lambda/latest/dg/foundation-arch.html) + Funções do Lambda com mais de 512 MB de armazenamento temporário + Usar uma [chave gerenciada pelo cliente para criptografar pacotes de implantação .zip](https://docs.aws.amazon.com/lambda/latest/dg/encrypt-zip-package.html) ## Tempos de execução compatíveis O Lambda@Edge é compatível com as versões mais recentes dos runtimes Node.js e Python. Para ver uma lista das versões compatíveis e suas futuras datas de descontinuação, consulte [Tempos de execução compatíveis](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html#runtimes-supported) no *Guia do desenvolvedor do AWS Lambda*. **dica** Como prática recomendada, use as versões mais recentes dos runtimes fornecidos para melhorias de desempenho e novos atributos. Não é possível criar nem atualizar funções com versões descontinuadas do Node.js. Só é possível associar funções existentes a essas versões com distribuições do CloudFront. Funções com essas versões que estão associadas a distribuições continuam a ser executadas. No entanto, recomendamos mover sua função para versões mais recentes do Node.js. Para ter mais informações, consulte [Política de descontinuação de runtime](https://docs.aws.amazon.com/lambda/latest/dg/runtime-support-policy.html) no *Guia do desenvolvedor do AWS Lambda* e o [cronograma de lançamentos do Node.js](https://github.com/nodejs/Release#release-schedule) no GitHub. ## Cabeçalhos do CloudFront As funções do Lambda@Edge podem ler, editar, remover ou adicionar qualquer um dos cabeçalhos do CloudFront listados em [Adicionar cabeçalhos de solicitação do CloudFront](adding-cloudfront-headers.md). **Observações** Para que o CloudFront adicione esses cabeçalhos, configure-o para adicioná-los usando uma [política de cache](controlling-the-cache-key.md) ou [política de solicitação de origem](controlling-origin-requests.md). O CloudFront adiciona os cabeçalhos *após* o evento de solicitação do visualizador, o que significa que eles não estão disponíveis para as funções do Lambda@Edge em uma solicitação do visualizador. Os cabeçalhos só estão disponíveis para funções do Lambda@Edge em uma solicitação e resposta de origem. Se a solicitação do visualizador incluir cabeçalhos que têm esses nomes e você configurou o CloudFront para adicionar esses cabeçalhos usando uma [política de cache](controlling-the-cache-key.md) ou [política de solicitação de origem](controlling-origin-requests.md), o CloudFront substituirá os valores de cabeçalho que estavam na solicitação do visualizador. As funções voltadas para o visualizador veem o valor do cabeçalho da solicitação do visualizador, enquanto as funções voltadas para a origem veem o valor do cabeçalho adicionado pelo o CloudFront. Se uma função de solicitação do visualizador adicionar o cabeçalho `CloudFront-Viewer-Country`, a validação falhará e o CloudFront retornará o código de status HTTP 502 (gateway inválido) para o visualizador. ## Restrições do corpo da solicitação com a opção de incluir corpo Ao escolher a opção **Incluir corpo** para expor o corpo da solicitação à função do Lambda@Edge, as informações e limites de tamanho a seguir se aplicam às partes do corpo que são expostas ou substituídas. + O CloudFront sempre codifica em base64 o corpo da solicitação antes de expô-lo ao Lambda@Edge. + Se o corpo da solicitação for grande, o CloudFront o truncará antes de expô-lo ao Lambda@Edge da seguinte forma: + Para eventos de solicitação do visualizador, o corpo é truncado em 40 KB. + Para eventos de solicitação da origem, o corpo é truncado em 1 MB. + Se você acessar o corpo da solicitação como somente leitura, o CloudFront enviará o corpo da solicitação original completo à origem. + Se a função do Lambda@Edge substituir o corpo da solicitação, os limites de tamanho a seguir se aplicarão ao corpo retornado pela função: + Se a função do Lambda@Edge retornar o corpo como texto simples: + Para eventos de solicitação do visualizador, o limite do corpo é de 40 KB. + Para eventos de solicitação da origem, o limite do corpo é de 1 MB. + Se a função do Lambda@Edge retornar o corpo como texto codificado em base64: + Para eventos de solicitação do visualizador, o limite do corpo é de 53,2 KB. + Para eventos de solicitação da origem, o limite do corpo é de 1,33 MB. **nota** Se a função do Lambda@Edge retornar um corpo que exceda esses limites, a solicitação falhará com um código de status HTTP 502 ([Erro de validação do Lambda](http-502-bad-gateway.md#http-502-lambda-validation-error)). Recomendamos que você atualize a função do Lambda@Edge para que o corpo não exceda esses limites. ## Tempo limite de resposta e de manutenção (somente origens personalizadas) Se estiver usando as funções do Lambda@Edge para definir o tempo limite de resposta ou de manutenção para as origens da distribuição, verifique se você está especificando um valor compatível com a origem. Para obter mais informações, consulte [Cotas de tempo limite de resposta e manutenção](DownloadDistValuesOrigin.md#response-keep-alive-timeout-quota).