Création d’une fonction externe personnalisable sur AWS

Ce document montre une façon de créer une fonction externe sur la plate-forme Cloud Amazon Web Services (AWS), notamment :

  • Création d’un service distant (fonction Lambda sur AWS).

  • Création d’un service proxy (sur Amazon API Gateway).

  • Création d’une intégration API dans Snowflake.

  • Création d’une fonction externe dans Snowflake.

  • Appel de la fonction externe.

Ces instructions supposent que vous connaissez déjà l’administration d’AWS. Ces instructions spécifient les étapes générales que vous devez exécuter, mais ne vous guident pas dans les détails de la console d’administration AWS car les détails pourraient changer.

Dans ce chapitre :

Conditions préalables

Vous avez besoin des éléments suivants :

  • Un compte avec AWS, y compris des privilèges pour :

    • Créer des rôles AWS via IAM (gestion des identités et des accès).

    • Créer des fonctions Lambda AWS.

    • Créer un point de terminaison API Gateway.

  • Un compte Snowflake dans lequel vous disposez des privilèges ACCOUNTADMIN ou un rôle avec le privilège CREATE INTEGRATION.

Ce document suppose que vous êtes un administrateur AWS expérimenté.

Astuce

Lors de la création de la fonction externe, vous devez copier les informations liées à l’authentification de Snowflake vers AWS et de AWS vers Snowflake.

Lorsque vous suivez les instructions ci-dessous, Snowflake vous recommande d’enregistrer les informations dans la feuille de calcul ci-dessous pour les utiliser dans les étapes suivantes :

AWS Account ID.............: _____________________________________________
Lambda Function Name.......: _____________________________________________
New IAM Role Name..........: _____________________________________________
New IAM Role ARN...........: _____________________________________________
Snowflake VPC ID (optional): _____________________________________________
New API Name...............: _____________________________________________
API Gateway Resource Name..: _____________________________________________
Resource Invocation URL....: _____________________________________________
Method Request ARN.........: _____________________________________________
API_AWS_IAM_USER_ARN.......: _____________________________________________
API_AWS_EXTERNAL_ID........: _____________________________________________

Étape 1 : Créer le service distant (fonction Lambda sur AWS)

Il existe plusieurs façons de créer un service distant. Cette section montre comment créer un service distant implémenté en tant que fonction Python s’exécutant dans AWS Lambda.

Cet exemple de fonction en langage Python renvoie simplement ses entrées.

Cette fonction accepte et renvoie les données au même format (JSON) que celui envoyé et lu par Snowflake.

Cette fonction Python reçoit deux paramètres, event et context. Le paramètre event comprend de nombreux sous-champs, dont l’un est body. Le corps est un dictionnaire qui comprend une clé nommée data ; la valeur correspondante pour data est une chaîne contenant les données envoyées par Snowflake au format JSON. Etant donné que AWS Lambda traite commodément la requête HTTP POST envoyée par Snowflake, extrait le corps et transmet le corps à l’intérieur du paramètre d’événement, cet exemple de fonction n’a pas besoin d’analyser l’intégralité de la requête HTTP POST.

Après que cette fonction Python a extrait le corps sous forme de chaîne, la fonction appelle une fonction de bibliothèque JSON pour convertir la chaîne en une structure de données Python. La fonction extrait ensuite des lignes individuelles de cette structure de données, les traite et renvoie une valeur pour chacune d’entre elles.

Le JSON pour une valeur de retour typique d’une fonction AWS Lambda ressemble à ceci :

{
"statusCode": <http_status_code>,
"body":
        {
            "data":
                  [
                      [ 0, <value> ],
                      [ 1, <value> ]
                      ...
                  ]
        }
}

Les données de la valeur de retour correspondent au format décrit précédemment pour les données d’entrée. Sur AWS, la convention pour un service compatible HTTP est de renvoyer le corps à l’intérieur d’un objet JSON qui inclut également le code de statut HTTP.

Pour créer cette fonction Lambda AWS, procédez comme suit :

  1. Connectez-vous à la console de gestion AWS, si ce n’est pas déjà fait.

  2. Enregistrez l’ID de votre compte AWS dans la feuille de calcul ci-dessus.

    Si vous devez consulter votre ID de compte AWS, suivez les instructions AWS.

  3. Sélectionnez « Lambda ».

  4. Sélectionnez « Créer une fonction ».

  5. Saisissez un nom de fonction.

    Enregistrez ce nom dans la feuille de calcul ci-dessus sur la ligne intitulée « Nom de la fonction Lambda ».

  6. Sélectionnez le langage à utiliser. Pour cet exemple, choisissez Python 3.7.

  7. Choisissez ou créez un rôle d’exécution pour cette fonction.

    Sélectionnez la ou les options appropriées, généralement « Créer un nouveau rôle avec des autorisations Lambda de base ».

    (Ce rôle est distinct de votre rôle de compte Cloud et distinct de vos rôles Snowflake.)

  8. Cliquez sur le bouton Create Function.

  9. Dans l’onglet lambda_function , entrez le code de la fonction. Si vous n’avez pas encore écrit votre propre fonction, vous pouvez remplacer le code de fonction par défaut par le code ci-dessous, qui fera écho à son entrée. Vous pouvez remplacer ou mettre à jour ce code ultérieurement lorsque vous serez prêt à créer une fonction personnalisée.

    Cet exemple de code suppose que vous utilisez l’intégration du proxy Lambda, comme le recommande Snowflake dans les instructions de création du point de terminaison API Gateway.

    Si vous ne pouvez pas coller dans la fenêtre d’édition, essayez de double-cliquer sur le nom du fichier de la fonction pour activer l’édition.

    import json
    
    def lambda_handler(event, context):
    
        # 200 is the HTTP status code for "ok".
        status_code = 200
    
        # The return value will contain an array of arrays (one inner array per input row).
        array_of_rows_to_return = [ ]
    
        try:
            # From the input parameter named "event", get the body, which contains
            # the input rows.
            event_body = event["body"]
    
            # Convert the input from a JSON string into a JSON object.
            payload = json.loads(event_body)
            # This is basically an array of arrays. The inner array contains the
            # row number, and a value for each parameter passed to the function.
            rows = payload["data"]
    
            # For each input row in the JSON object...
            for row in rows:
                # Read the input row number (the output row number will be the same).
                row_number = row[0]
    
                # Read the first input parameter's value. For example, this can be a
                # numeric value or a string, or it can be a compound value such as
                # a JSON structure.
                input_value_1 = row[1]
    
                # Read the second input parameter's value.
                input_value_2 = row[2]
    
                # Compose the output based on the input. This simple example
                # merely echoes the input by collecting the values into an array that
                # will be treated as a single VARIANT value.
                output_value = ["Echoing inputs:", input_value_1, input_value_2]
    
                # Put the returned row number and the returned value into an array.
                row_to_return = [row_number, output_value]
    
                # ... and add that array to the main array.
                array_of_rows_to_return.append(row_to_return)
    
            json_compatible_string_to_return = json.dumps({"data" : array_of_rows_to_return})
    
        except Exception as err:
            # 400 implies some type of error.
            status_code = 400
            # Tell caller what this function could not handle.
            json_compatible_string_to_return = event_body
    
        # Return the return value and HTTP status code.
        return {
            'statusCode': status_code,
            'body': json_compatible_string_to_return
        }
    
  10. Cliquez sur le bouton Deploy pour déployer la fonction.

  11. Facultatif, mais fortement recommandé : testez votre fonction.

    Pour l’exemple de fonction Python fournie par Snowflake, utilisez les données de test suivantes (remplacez toutes les données par défaut par les données ci-dessous) :

    {
      "body":
        "{ \"data\": [ [ 0, 43, \"page\" ], [ 1, 42, \"life, the universe, and everything\" ] ] }"
    }
    

    Les résultats d’exécution doivent être similaires à ceci :

    Response:
    {
      "statusCode": 200,
      "body": "{\"data\": [[0, [\"Echoing inputs:\", 43, \"page\"]], [1, [\"Echoing inputs:\", 42, \"life, the universe, and everything\"]]]}"
    }
    ...
    

Si le précédent a fonctionné correctement, vous disposez maintenant d’une fonction AWS Lambda que vous pouvez utiliser comme service distant pour votre fonction externe.

Étape 2 : Configurer le service proxy (Amazon API Gateway) et créer l’intégration API (dans Snowflake)

Configurer Amazon API Gateway en tant que service proxy nécessite plusieurs étapes, notamment :

  • Création d’un nouveau rôle IAM dans votre compte AWS.

  • Création et configuration d’un point de terminaison Amazon API Gateway.

  • Sécurisation de votre point de terminaison Amazon API Gateway.

  • Création d’un objet d’intégration API dans Snowflake.

  • Configuration d’une relation de confiance entre Snowflake et le nouveau rôle IAM.

Les étapes pour les créer sont entrelacées, car l’intégration API a besoin d’informations de l’API Gateway (l’ARN (Amazon Resource Name) du rôle), et l’API Gateway a besoin d’informations de l’intégration API (le API_AWS_EXTERNAL_ID et le API_AWS_IAM_USER_ARN).

Créer un nouveau rôle IAM dans votre compte AWS

Pour que Snowflake s’authentifie auprès de votre compte AWS, un utilisateur IAM appartenant à Snowflake (gestion des identités et des accès) doit être autorisé à assumer un rôle IAM dans votre compte AWS. Pour ce faire, une relation de confiance doit être établie. Pour établir la relation de confiance, vous devez créer un rôle IAM sur votre compte AWS et le configurer avec l’ARN de l’utilisateur IAM appartenant à Snowflake, et vous devez créer un objet d’intégration API dans Snowflake et configurer l’objet d’intégration API avec les informations sur le rôle IAM à assumer.

  1. Créez un nouveau rôle IAM.

  2. Lorsque vous devez sélectionner le type d’entité de confiance, choisissez « Un autre compte AWS ».

  3. Lorsque vous êtes invité à « spécifier les comptes pouvant utiliser ce rôle », collez l’ID de compte AWS précédemment enregistré provenant de la feuille de calcul ci-dessus.

  4. Cliquez sur « Suivant : Autorisations ».

  5. Définissez les autorisations (« Attacher les stratégies d’autorisations ») si nécessaire.

  6. Entrez un nom de rôle.

    • Enregistrez le nom du rôle en tant que « Nouveau nom de rôle IAM ».

  7. Cliquez sur le bouton Create role. Après avoir créé le rôle :

    • Enregistrez l”« ARN de rôle » comme le « Nouvel ARN de rôle IAM » dans la feuille de calcul ci-dessus.

Créer et configurer une API dans Amazon API Gateway

Choisissez votre type de point de terminaison : point de terminaison régional vs. point de terminaison privé

Vous accédez à un service proxy (tel que Amazon API Gateway) via une URI, parfois appelé « point de terminaison ». Pour votre Amazon API Gateway, vous pouvez créer, au choix :

  • Un point de terminaison régional.

  • Un point de terminaison privé.

Un point de terminaison régional peut être accessible à travers les régions ou même les Clouds. Votre instance Snowflake, votre service proxy et votre service à distance peuvent tous se trouver dans des régions différentes ou même sur des plateformes Cloud différentes. Par exemple, une instance de Snowflake fonctionnant sur Azure pourrait envoyer des requêtes à un point de terminaison régional Amazon API Gateway, qui à son tour pourrait transmettre des données à un service distant fonctionnant sur GCP.

Un point de terminaison privé peut être configuré pour permettre l’accès uniquement à partir d’un VPC (Cloud privé virtuel) Snowflake dans la même région AWS via PrivateLink.

Pour plus de détails sur les différents types de points de terminaison sur AWS, voir :

Si vous souhaitez utiliser un point de terminaison privé et que vous n’êtes pas sûr de la région que vous utilisez, vous pouvez rechercher votre région en procédant de l’une des manières suivantes :

  • Appelez la fonction SQL CURRENT_REGION() (par exemple SELECT CURRENT_REGION()).

  • Vérifiez le nom d’hôte de votre compte Snowflake, qui indique normalement le fournisseur de services Cloud et la région. Pour plus d’informations sur les noms d’hôtes, les régions et les fournisseurs de services Cloud relatifs aux comptes, voir Régions prises en charge.

Pour utiliser un point de terminaison privé, votre compte doit remplir les conditions suivantes :

  • Édition Business Critical (ou supérieure) de Snowflake.

Sur AWS, Snowflake prend en charge la connexion des comptes Snowflake aux VPCs AWS. Les points de terminaison privés permettent la communication entre VPCs (Clouds privés virtuels) via PrivateLink. Pour plus d’informations sur Snowflake et AWS PrivateLink, voir :

Créer le point de terminaison API Gateway

Avant de créer et de configurer votre API Gateway, choisissez si vous voulez utiliser un point de terminaison régional ou privé. Pour plus d’informations, voir Choisissez votre type de point de terminaison : point de terminaison régional vs. point de terminaison privé.

Note

Vous pouvez créer une fonction externe sur des instances de Snowflake non hébergées par AWS. Si votre entrepôt virtuel se trouve sur Azure ou GCP (Google Cloud Platform), vous pouvez créer une fonction externe qui accède à un service distant via une Amazon API Gateway.

Les étapes pour créer un point de terminaison API Gateway sont les suivantes :

  1. Si vous prévoyez d’utiliser un point de terminaison privé, obtenez l’ID du VPC (Cloud privé virtuel) en exécutant la commande suivante dans l’interface Web Snowflake :

    select system$get_snowflake_platform_info();
    

    La sortie devrait ressembler à ce qui suit :

    {"snowflake-vpc-id":["vpc-12345699"]}
    

    Enregistrez l’ID du VPC (par exemple « vpc-12345699 ») dans le champ « ID du VPC Snowflake » de la feuille de calcul ci-dessus.

    (Remarque : vous devez utiliser un ID de VPC et non un ID de point de terminaison VPC. Les IDs de points de terminaison VPC peuvent changer au fil du temps).

  2. Dans la console de gestion AWS, sélectionnez API Gateway.

  3. Sélectionnez Create API.

  4. Sélectionnez le type de point de terminaison (régional ou privé).

    • Si vous voulez un point de terminaison régional , alors :

      • Trouvez REST API et cliquez sur son bouton Build .

    • Si vous voulez un point de terminaison privé, alors :

      • Trouvez REST API private et cliquez sur son bouton Build .

    Important

    Veillez à choisir REST API ou REST API private . Ne sélectionnez pas HTTP API ou une autre option.

  5. Sélectionnez l’option New API .

  6. Saisissez un nom pour la nouvelle API.

    Enregistrez ce nom sous le nom de « Nom de la nouvelle API » dans la feuille de calcul.

  7. Si on vous demande de sélectionner un Endpoint Type , sélectionnez soit Regional , soit Private.

  8. Si vous créez un point de terminaison privé, entrez l’ID du VPC Snowflake enregistré dans le champ « ID du VPC Snowflake » dans la feuille de calcul.

    (Si vous ne créez pas de point de terminaison privé, vous n’avez pas besoin d’entrer un ID de VPC.)

  9. Cliquez sur le bouton Create API.

    Cela devrait vous amener à un nouvel écran qui vous permet de créer des ressources.

  10. Créez une ressource.

    (Vous devrez peut-être cliquer sur le bouton Actions pour voir l’option Create Resource.)

    Enregistrez le nom de la ressource dans la feuille de calcul en tant que « Nom de ressource API Gateway » ; vous en aurez besoin plus tard.

    Après avoir cliqué sur le bouton Create Resource , l’écran devrait afficher No methods defined for the resource.

  11. Créez une nouvelle méthode. Cliquez sur Actions et sélectionnez Create Method pour cette ressource.

    Spécifiez l’option POST . (Si vous ne voyez pas l’option POST , cliquez sur la petite boîte de menu déroulant sous le nom de la ressource).

    Une nouvelle fenêtre devrait alors s’ouvrir et afficher Integration type ainsi que d’autres options.

  12. Integration type devrait être Lambda Function. Si ce n’est pas déjà sélectionné, sélectionnez-le.

  13. Cliquez sur la case Use Lambda Proxy integration.

    Il est important de sélectionner une intégration de proxy lambda, car le JSON sans intégration du proxy Lambda serait différent du JSON avec intégration du proxy Lambda. Pour plus d’informations sur l’intégration du proxy Lambda, voir la documentation AWS pour :

  14. Dans le champ Lambda Function , collez le nom de la fonction Lambda que vous avez enregistré dans la feuille de calcul.

  15. Enregistrez.

  16. Cliquez sur le bouton Actions , et sélectionnez l’action Deploy API .

  17. Sélectionnez ou créez une zone de préparation pour cette fonction.

  18. Sous le nom de la ressource, vous devriez voir POST.

    Si ce n’est pas le cas, vous devrez peut-être développer l’arbre des ressources en cliquant sur le triangle qui se trouve à gauche du nom de la ressource.

  19. Cliquez sur POST, puis enregistrez Invoke URL de la demande POST dans le champ « Resource Invocation URL » de la feuille de calcul.

    Assurez-vous que l’URL d’appel inclut le nom de la ressource que vous avez créée ; si ce n’est pas le cas, vous avez peut-être cliqué sur l’URL d’appel pour la zone de préparation plutôt que pour la ressource.

  20. Cliquez sur Save Changes.

Protégez votre point de terminaison Amazon API Gateway

Pour un aperçu de la sécurisation des points de terminaison du service proxy, comme les point de terminaison Amazon API Gateway, voir Sécurisez votre point de terminaison de service proxy.

Pour sécuriser un point de terminaison Amazon API Gateway :

  1. À ce stade, vous devriez être sur l’écran qui affiche vos informations sur API Gateway, et vous devriez voir votre ressource et la méthode POST.

    Si vous n’y êtes pas déjà, faites ce qui suit :

    1. Dans l’interface Web AWS , allez à la page API Gateway.

    2. Sélectionnez votre API Gateway si vous ne l’avez pas encore fait.

    3. Dans le volet de gauche, cliquez sur Resources .

    4. Cliquez sur la méthode POST . (Si vous ne voyez pas cela, développez l’arbre des ressources en cliquant sur le triangle à gauche de la ressource dans le panneau Resources , qui est généralement le deuxième panneau à partir de la gauche).

  2. Copiez l’ARN de la requête de méthode de la case Method Request vers le champ « ARN de la requête de méthode » de la feuille de calcul ci-dessus.

  3. Cliquez sur le titre Method Request.

  4. Précisez que le Method Request nécessite l’autorisation du AWS_IAM .

    Notez qu’après avoir sélectionné l’autorisation AWS_IAM dans le menu déroulant, vous devez cliquer sur la petite coche à côté du menu pour confirmer votre choix.

  5. Définissez la politique de ressource pour API Gateway afin de spécifier qui est autorisé à appeler le point de terminaison de la passerelle.

    Pour accéder à la fenêtre d’édition qui vous permet de saisir une politique de ressources, vous devrez peut-être cliquer sur Resource Policy dans la colonne de gauche de la fenêtre pour l” API.

    • Point de terminaison régional :

      Collez le modèle de politique de ressources ci-dessous dans l’éditeur de politique de ressources, puis remplacez les caractères de remplissage par les valeurs appropriées de la feuille de calcul, comme décrit ci-dessous.

      {
          "Version": "2012-10-17",
          "Statement":
          [
              {
              "Effect": "Allow",
              "Principal":
                  {
                  "AWS": "arn:aws:sts::<12-digit-number>:assumed-role/<external_function_role>/snowflake"
                  },
              "Action": "execute-api:Invoke",
              "Resource": "<method_request_ARN>"
              }
          ]
      }
      

      Remplacez les parties suivantes de la politique de ressource :

      • Remplacez le <numéro à 12chiffres> par l’ID de compte AWS , que vous avez enregistré dans la feuille de calcul.

      • Remplacez <rôle_fonction_externe> par le nom de rôle du nouveau nom de rôle IAM.

        Par exemple, si votre nom de rôle AWS est :

        arn:aws:iam::987654321098:role/MyNewIAMRole
        

        alors le résultat devrait être :

        "AWS": "arn:aws:sts::987654321098:assumed-role/MyNewIAMRole/snowflake"
        
      • La « ressource » doit être définie sur l’ARN de la demande de méthode pour la méthode POST de la ressource.

        Note

        La définition de la ressource sur l’ARN de la demande de méthode spécifie que l’API Gateway doit autoriser les appels uniquement vers la ressource spécifiée. Il est possible de spécifier un sous-ensemble de l’ARN de la demande de méthode comme préfixe, ce qui permet d’appeler plusieurs ressources à partir de la même API Gateway.

        Par exemple, si l’ARN de la demande de méthode est :

        arn:aws:execute-api:us-west-1:123456789012:a1b2c3d4e5/*/POST/MyResource
        

        alors vous pouvez spécifier simplement le préfixe suivant :

        arn:aws:execute-api:us-west-1:123456789012:a1b2c3d4e5/*/
        
    • Point de terminaison privé :

      Collez le modèle de politique de ressources ci-dessous dans l’éditeur de politique de ressources, puis remplacez les caractères de remplissage par les valeurs appropriées de la feuille de calcul, comme décrit ci-dessous.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Principal": {
                      "AWS": "arn:aws:sts::<12-digit-number>:assumed-role/<external_function_role>/snowflake"
                  },
                  "Action": "execute-api:Invoke",
                  "Resource": "<method_request_ARN>",
                  "Condition": {
                      "StringEquals": {
                          "aws:sourceVpc": "<VPC_ID>"
                      }
                  }
              }
          ]
      }
      

      Remplacez les parties suivantes de la politique de ressource :

      • Remplacez le <numéro à 12chiffres>, <rôle_de_fonction_externe> et <ARN_méthode_de_requête> comme décrit ci-dessus pour un point de terminaison régional.

      • Remplacez la valeur de <VPD_ID> par l’ID du VPC Snowflake de votre région, qui doit être enregistré dans le champ « ID du VPC Snowflake » de la feuille de calcul.

  6. Si vous n’avez pas encore cliqué sur Save pour sauvegarder la politique des ressources, faites-le maintenant.

  7. Déployez l’API mise à jour.

Dans les étapes suivantes, vous créez un objet d’intégration API Snowflake. Ne fermez pas votre fenêtre d’administration AWS maintenant ; vous devrez y revenir plus tard.

Créer un objet d’intégration API dans Snowflake

  1. Ouvrez (si vous ne l’avez pas déjà fait) une session Snowflake, généralement une session d’interface Web Snowflake.

  2. Utilisez un rôle Snowflake avec des privilèges ACCOUNTADMIN ou le privilège CREATE INTEGRATION, par exemple :

    use role has_accountadmin_privileges;
    
  3. Tapez la commande CREATE API INTEGRATION pour créer une intégration API. La commande doit ressembler à ce qui suit :

    CREATE OR REPLACE API INTEGRATION my_api_integration_01
      api_provider = aws_api_gateway
      api_aws_role_arn = '<new_IAM_role_ARN>'
      api_allowed_prefixes = ('https://')
      enabled = true
    ;
    

    Personnalisez la commande :

    • Si vous utilisez un point de terminaison privé, le fournisseur d’api doit être « aws_private_api_gateway ». Sinon, le fournisseur d’api doit être « aws_api_gateway ».

    • Le <nouveau_ARNde_rôle_IAM> devrait être le nouveau ARN de rôle IAM que vous avez enregistré précédemment dans la feuille de travail ci-dessus.

    • Le champ préfixes_autorisés_api doit contenir l’URL de l’appel de ressource que vous avez enregistrée précédemment.

    • Vous pouvez également souhaiter personnaliser le nom de l’intégration API, plutôt que d’utiliser la valeur dans l’exemple.

    Voici un exemple d’une instruction CREATE API INTEGRATION complète :

    create or replace api integration demonstration_external_api_integration_01
        api_provider=aws_api_gateway
        api_aws_role_arn='arn:aws:iam::123456789012:role/my_cloud_account_role'
        api_allowed_prefixes=('https://xyz.execute-api.us-west-2.amazonaws.com/production/')
        enabled=true;
    
  4. Exécutez la commande CREATE API INTEGRATION que vous avez tapée ci-dessus.

  5. Exécutez la commande DESCRIBE INTEGRATION.

    DESCRIBE INTEGRATION <my_integration_name>;
    

    Par exemple :

    DESCRIBE INTEGRATION my_api_integration_01;
    
  6. Recherchez la propriété nommée « API_AWS_IAM_USER_ARN », puis enregistrez la valeur_propriété de cette propriété dans la feuille de calcul.

  7. Trouvez la propriété nommée « API_AWS_EXTERNAL_ID », puis enregistrez la valeur_propriété de cette propriété dans la feuille de calcul.

    Notez que la valeur_propriété de API_AWS_EXTERNAL_ID se termine souvent par un signe égal (« = »). Ce signe égal fait partie de la valeur ; assurez-vous de le couper et de le coller avec le reste de la valeur_propriété.

Au cours des prochaines étapes, vous reviendrez à la fenêtre d’administration AWS. Ne fermez pas votre fenêtre d’administration Snowflake maintenant ; vous devez y revenir plus tard.

Configurer la relation de confiance entre Snowflake et le nouveau rôle IAM

Dans la console de gestion AWS :

  1. Sélectionnez IAM.

  2. Sélectionnez les rôles.

  3. Recherchez le nouveau nom de rôle IAM que vous avez créé et enregistré précédemment, puis sélectionnez-le.

  4. Cliquez sur l’onglet « Relations de confiance », puis cliquez sur le bouton Edit trust relationship.

    Cela devrait ouvrir le document de politique dans lequel vous pouvez ajouter des informations d’authentification.

  5. Dans le document de stratégie, recherchez le champ Statement.Principal.AWS et remplacez la valeur (pas la clé) par l’API_AWS_IAM_USER_ARN que vous avez enregistré précédemment.

  6. Recherchez le champ Statement.Condition. Initialement, cela ne devrait contenir que des accolades (« {} »).

  7. Collez ce qui suit entre les accolades : "StringEquals": { "sts:ExternalId": "xxx" }.

  8. Remplacez le « xxx » par la valeur de API_AWS_EXTERNAL_ID que vous avez enregistré précédemment.

  9. Une fois que vous avez terminé de modifier le document de stratégie pour la relation de confiance, cela devrait ressembler à ce qui suit :

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::1234567898012:user/development/development_user"
          },
          "Action": "sts:AssumeRole",
          "Condition": {"StringEquals": { "sts:ExternalId": "EXTERNAL_FUNCTIONS_SFCRole=3_8Hcmbi9halFOkt+MdilPi7rdgOv=" }}
        }
      ]
    }
    
  10. Cliquez sur Update Trust Policy.

Etape 3 : Créer la fonction externe

Revenez maintenant à votre fenêtre d’administration Snowflake (où vous avez précédemment tapé la commande CREATE API INTEGRATION).

  1. Tapez la commande CREATE EXTERNAL FUNCTION. Cela devrait ressembler à ce qui suit :

    CREATE EXTERNAL FUNCTION my_external_function(n INTEGER, v VARCHAR)
        RETURNS VARIANT
        API_INTEGRATION = <api_integration_name>
        AS '<resource_invocation_url>'
        ;
    

    Personnalisez la commande :

    • La valeur <api_integration_name> doit contenir le nom de l’intégration API que vous avez créée précédemment.

    • La valeur <resource_invocation_url> doit être l’URL d’appel de ressource que vous avez enregistrée dans la feuille de calcul. Assurez-vous que cette URL inclut le nom de la ressource API Gateway, pas seulement le nom de la zone de préparation.

    • Vous pouvez également personnaliser le nom de la fonction.

    Cet exemple transmet deux arguments (un INTEGER et un VARCHAR), car ce sont les arguments que la fonction Lambda attend. Lorsque vous créerez votre propre fonction Lambda, vous devez transmettre les arguments appropriés pour votre fonction Lambda.

  2. Si vous n’avez pas encore exécuté la commande CREATE EXTERNAL FUNCTION que vous avez tapée ci-dessus, exécutez-la maintenant.

Etape 4 : Appeler la fonction externe

  1. Le cas échéant, accordez le privilège USAGE sur la fonction externe à un ou plusieurs rôles Snowflake afin que ces rôles puissent appeler la fonction externe. (Un rôle doit avoir des privilèges USAGE ou OWNERSHIP sur cette fonction externe.)

  2. Exécutez votre fonction en appelant :

    SELECT my_external_function(99, 'Luftballoons');
    

    Si vous avez personnalisé le nom de la fonction dans la commande CREATE EXTERNAL FUNCTION , alors remplacez « ma_fonction_externe » par le nom personnalisé.

Ressources supplémentaires pour la mise en place de fonctions externes sur AWS

D’autres exemples de services à distance basés sur les fonctions Lambda sont disponibles à l’adresse suivante :

Dépannage

Voir également le document de dépannage général des fonctions externes.

Unable to read the requests body inside the Amazon AWS Lambda Function

Symptôme :

La fonction est incapable de lire le corps de la requête dans la méthode HTTP POST .

Cause(s) possible(s) :

Vous n’avez peut-être pas activé l’intégration du proxy Lambda.

Solution(s) possible(s) :

Activation de l’intégration des proxy Lambda.

Pour plus de détails, voir les étapes correspondantes dans Créer et configurer une API dans Amazon API Gateway.

SQL execution error: Error assuming AWS_ROLE. Please verify the role and externalId are configured correctly in your AWS policy.

Symptôme :

Lorsque vous essayez d’appeler la fonction externe, vous obtenez le message d’erreur suivant :

SQL execution error: Error assuming AWS_ROLE. Please verify the role and externalId are configured correctly in your AWS policy.

Causes possibles :

  • Dans la stratégie de relation de confiance AWS pour votre rôle, l’ARN AWS est incorrect. Les causes possibles de cela comprennent :

    • Vous ne l’avez pas défini.

    • Vous l’avez défini, mais vous avez utilisé l’ARN du rôle AWS (incorrect) au lieu de l’ARN utilisateur, que vous pouvez voir à partir de la commande « DESCRIBE INTEGRATION » dans Snowflake. Assurez-vous que vous utilisez API_AWS_IAM_USER_ARN plutôt que API_AWS_ROLE_ARN.

  • Dans votre stratégie de relation de confiance AWS, le std:ExternalId est incorrect. Les causes possibles de cela comprennent :

    • Vous ne l’avez pas défini.

    • Vous avez recréé l’objet d’intégration API. La recréation de l’objet API modifie son ID externe.

Error: 403 '{"Message":"User: <ARN> is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

Symptôme :

Lorsque vous essayez d’appeler la fonction externe, vous obtenez le message d’erreur suivant :

Request failed for external function <nom_fonction>. Error: 403 '{"Message":"User: <ARN> is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

Cause(s) possible(s) :

  • La politique des ressources API Gateway a :

    • Le mauvais ARN de rôle IAM.

    • Le mauvais rôle assumé.

    • Le mauvais ARN de requête de méthode.

  • Le rôle IAM n’est pas assorti de la bonne politique.

Solution(s) possible(s) :

  • Assurez-vous que vous avez bien suivi le modèle de politique des ressources figurant dans Protégez votre point de terminaison Amazon API Gateway. Plus précisément, assurez-vous que votre politique en matière de ressources :

    • A remplacé le <numéro à 12chiffres> par l’ID de compte AWS de la feuille de calcul.

    • A remplacé le <rôle_fonction_externe> par le nom du nouveau rôle IAM de la feuille de calcul.

    • A remplacé le method_request_ARN dans le champ Resource par l’ARN de la requête de méthode.

  • Si vous devez vous assurer que le rôle IAM a la bonne politique de permissions attachée, vous pouvez trouver la liste de la politique de permissions du rôle en suivant les étapes ci-dessous :

    1. Dans AWS, sélectionnez le rôle.

    2. Affichez le Summary pour le rôle.

    3. Cliquez sur l’onglet Permissions .

    4. Vérifiez que la politique requise figure dans la liste Permissions policies .

Error: 403 '{"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

Symptôme :

Lorsque vous essayez d’appeler la fonction externe, vous obtenez le message d’erreur suivant :

Request failed for external function <nom_fonction>. Error: 403 '{"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

Cause(s) possible(s) :

Une cause possible est que lorsque vous configuriez l’autorisation pour l’API Gateway, vous n’avez peut-être pas précisé que Method Request nécessite l’autorisation AWS_IAM pour la ressource.

Solution(s) possible(s) :

Si vous n’avez pas suivi les instructions de sécurité Amazon API Gateway, alors veuillez les suivre dès à présent pour spécifier l’autorisation AWS_IAM.

"Error parsing JSON response for external function ... Error: top-level JSON object must contain "data" JSON array element"

Cause(s) possible(s) :

  • Vous n’avez peut-être pas spécifié l’intégration par proxy lambda pour la ressource API Gateway.

Solution(s) possible(s) :