Module cfn-response

Lorsque vous utilisez la ZipFile propriété pour spécifier le code source de votre fonction et que cette fonction interagit avec une ressource AWS CloudFormation personnalisée, vous pouvez charger le cfn-response module pour envoyer des réponses à ces ressources. Le module contient une méthode send qui envoie un objet de réponse à une ressource personnalisée au moyen d'une URL Amazon S3 présignée (ResponseURL).

Après l'exécution de la méthode send, la fonction Lambda s'arrête. Dès lors, tout ce que vous écrivez après cette méthode est ignoré.

Note

Le module cfn-response est disponible uniquement lorsque vous utilisez la propriété ZipFile pour écrire votre code source. Il n'est pas disponible pour le code source stocké dans des compartiments Amazon S3. Pour le code stocké dans des compartiments , vous devez écrire vos propres fonctions pour envoyer des réponses.

Chargement du module cfn-response

Pour les fonctions Node.js, utilisez la fonction require() pour charger le module cfn-response. Par exemple, l'exemple de code suivant crée un objet cfn-response avec le nom response :

var response = require('cfn-response');

Pour Python, utilisez l'instruction import pour charger le module cfnresponse, comme illustré dans l'exemple suivant :

Note

Utilisez cette instruction import exacte. Si vous utilisez d'autres variantes de l'instruction d'importation, le module de réponse AWS CloudFormation n'est pas inclus.

import cfnresponse

Paramètres de la méthode send

Vous pouvez utiliser les paramètres suivants avec la méthode send.

event

Champs d'une demande de ressource personnalisée.

context

Objet propre aux fonctions Lambda qui vous permet de spécifier à quel moment l'exécution de la fonction et des rappels se termine ou pour accéder aux informations à partir de l'environnement d'exécution Lambda. Pour plus d'informations, veuillez consulter la rubrique Modèle de programmation (Node.js) dans le Guide du développeurAWS Lambda .

responseStatus

Indique si la fonction a été exécutée avec succès. Utilisez les constantes du cfnresponse pour spécifier le statut SUCCESS pour les exécutions réussies et FAILED pour celles qui ont échoué.

responseData

Champ Data de l'objet de réponse d'une ressource personnalisée. Les données sont une liste de paires nom-valeur.

physicalResourceId

Facultatif. Identifiant unique de la ressource personnalisée qui appelé la fonction. Par défaut, le module utilise le nom du flux de journal Amazon CloudWatch Logs associé à la fonction Lambda.

La valeur renvoyée pour un PhysicalResourceId peut modifier les opérations de mise à jour des ressources personnalisées. Si la valeur renvoyée est la même, on considère qu'il s'agit d'une mise à jour normale. Si la valeur renvoyée est différente, AWS CloudFormation reconnaît la mise à jour comme un remplacement et envoie une requête de suppression à l'ancienne ressource. Pour de plus amples informations, veuillez consulter AWS::CloudFormation::CustomResource.

noEcho

Facultatif. Indique s'il faut masquer la sortie de la ressource personnalisée lorsque celle-ci est récupérée à l'aide de la fonction Fn::GetAtt. Si cette valeur est définie sur true, toutes les valeurs renvoyées sont masquées par des astérisques (*****), à l'exception des informations stockées dans les emplacements spécifiés ci-dessous. Cette valeur est false par défaut.

Important

L'utilisation de l'attribut NoEcho ne masque aucune information stockée dans les lieux suivants :

• La section des Metadata modèles. CloudFormation ne transforme, ne modifie ni n'expédie aucune information que vous incluez dans Metadata cette section. Pour de plus amples informations, veuillez consulter Metadonnées.

• La section de modèle Outputs Pour de plus amples informations, veuillez consulter Outputs.

• L’attribut Metadata d'une définition de ressource. Pour de plus amples informations, veuillez consulter Attribut Metadata.

Nous vous recommandons vivement de ne pas utiliser ces mécanismes pour inclure des informations sensibles, telles que des mots de passe ou des secrets.

Pour plus d’informations sur l’utilisation de NoEcho pour masquer des informations sensibles, consultez la documentation sur la bonne pratique consistant à ne pas intégrer les informations d’identification dans vos modèles.

Exemples

Node.js

Dans l'exemple Node.js suivant, la fonction Lambda en ligne multiplie une valeur d'entrée par 5. Les fonctions en ligne sont particulièrement utiles pour les fonctions de petite ampleur, car elles vous permettent de spécifier le code source directement dans le modèle au lieu de créer un package et de l'importer dans un compartiment Amazon S3. Cette fonction utilise la méthode cfn-response send pour renvoyer le résultat à la ressource personnalisée qui l'a appelée.

JSON

"ZipFile": { "Fn::Join": ["", [
  "var response = require('cfn-response');",
  "exports.handler = function(event, context) {",
  "  var input = parseInt(event.ResourceProperties.Input);",
  "  var responseData = {Value: input * 5};",
  "  response.send(event, context, response.SUCCESS, responseData);",
  "};"
]]}

YAML

ZipFile: >
  var response = require('cfn-response');
  exports.handler = function(event, context) {
    var input = parseInt(event.ResourceProperties.Input);
    var responseData = {Value: input * 5};
    response.send(event, context, response.SUCCESS, responseData);
  };

Python

Dans l'exemple Python suivant, la fonction Lambda en ligne multiplie un entier par 5.

JSON

"ZipFile" : { "Fn::Join" : ["\n", [
  "import json",
  "import cfnresponse",
  "def handler(event, context):",
  "   responseValue = int(event['ResourceProperties']['Input']) * 5",
  "   responseData = {}",
  "   responseData['Data'] = responseValue",
  "   cfnresponse.send(event, context, cfnresponse.SUCCESS, responseData, \"CustomResourcePhysicalID\")"
]]}

YAML

ZipFile: |
  import json
  import cfnresponse
  def handler(event, context):
    responseValue = int(event['ResourceProperties']['Input']) * 5
    responseData = {}
    responseData['Data'] = responseValue
    cfnresponse.send(event, context, cfnresponse.SUCCESS, responseData, "CustomResourcePhysicalID")

Code source du module

Voici le code source du module de réponse pour les fonctions Node.js. Examinez-le pour comprendre ce que fait le module et pour vous aider à mettre en œuvre vos propres fonctions de réponse.

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: MIT-0
 
exports.SUCCESS = "SUCCESS";
exports.FAILED = "FAILED";
 
exports.send = function(event, context, responseStatus, responseData, physicalResourceId, noEcho) {
 
    var responseBody = JSON.stringify({
        Status: responseStatus,
        Reason: "See the details in CloudWatch Log Stream: " + context.logStreamName,
        PhysicalResourceId: physicalResourceId || context.logStreamName,
        StackId: event.StackId,
        RequestId: event.RequestId,
        LogicalResourceId: event.LogicalResourceId,
        NoEcho: noEcho || false,
        Data: responseData
    });
 
    console.log("Response body:\n", responseBody);
 
    var https = require("https");
    var url = require("url");
 
    var parsedUrl = url.parse(event.ResponseURL);
    var options = {
        hostname: parsedUrl.hostname,
        port: 443,
        path: parsedUrl.path,
        method: "PUT",
        headers: {
            "content-type": "",
            "content-length": responseBody.length
        }
    };
 
    var request = https.request(options, function(response) {
        console.log("Status code: " + parseInt(response.statusCode));
        context.done();
    });
 
    request.on("error", function(error) {
        console.log("send(..) failed executing https.request(..): " + error);
        context.done();
    });
 
    request.write(responseBody);
    request.end();
}

Voici le code source du module de réponse pour les fonctions Python 2 et 3 :

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
 
from __future__ import print_function
import urllib3
import json

SUCCESS = "SUCCESS"
FAILED = "FAILED"

http = urllib3.PoolManager()


def send(event, context, responseStatus, responseData, physicalResourceId=None, noEcho=False, reason=None):
    responseUrl = event['ResponseURL']

    print(responseUrl)

    responseBody = {
        'Status' : responseStatus,
        'Reason' : reason or "See the details in CloudWatch Log Stream: {}".format(context.log_stream_name),
        'PhysicalResourceId' : physicalResourceId or context.log_stream_name,
        'StackId' : event['StackId'],
        'RequestId' : event['RequestId'],
        'LogicalResourceId' : event['LogicalResourceId'],
        'NoEcho' : noEcho,
        'Data' : responseData
    }

    json_responseBody = json.dumps(responseBody)

    print("Response body:")
    print(json_responseBody)

    headers = {
        'content-type' : '',
        'content-length' : str(len(json_responseBody))
    }

    try:
        response = http.request('PUT', responseUrl, headers=headers, body=json_responseBody)
        print("Status code:", response.status)


    except Exception as e:

        print("send(..) failed executing http.request(..):", e)