Configurer une intégration de catalogue pour Amazon API Gateway¶

Création d’une API REST dans Amazon API Gateway¶

Pour connecter Snowflake à votre catalogue REST Iceberg, vous avez besoin d’une ressource API REST dans Amazon API Gateway.

Si vous ne disposez pas encore d’une ressource API REST dans Amazon API Gateway pour votre catalogue Iceberg, vous pouvez en créer une simple API REST en modifiant et en important un fichier de définition du catalogue Iceberg OpenAPI ou en ajoutant manuellement des points de terminaison.

1. Dans la console de gestion AWS, recherchez et sélectionnez API Gateway.

2. Sélectionnez Create API.

3. Sélectionnez Build sous REST API. Pour créer une API REST privée, sélectionnez Build sous REST API Private.

4. Sélectionnez l’une des options suivantes :

   • Pour créer une API en ajoutant manuellement des points de terminaison, sélectionnez New API.

   • Pour créer une API en utilisant un fichier de définition OpenAPI, sélectionnez Import API, puis téléchargez le fichier ou collez la définition dans l’éditeur de code.

5. Saisissez un API name et, si vous le souhaitez, une Description.

   Note

   Vous n’avez pas besoin de saisir un ID de point de terminaison VPC lorsque vous créez une API REST privée.

6. Sélectionnez Create API.

Pour plus d’informations sur la création et le développement d’une API REST dans API Gateway, consultez le Guide du développeur d’Amazon API Gateway.

Créer une politique IAM et la joindre à un rôle¶

Dans cette étape, vous créez un rôle AWS IAM que Snowflake peut utiliser pour se connecter à API Gateway. Vous joignez une politique au rôle qui accorde l’autorisation d’appeler votre API.

1. Dans la console de gestion AWS, recherchez et sélectionnez IAM.

2. Dans le volet de navigation de gauche, sélectionnez Policies.

3. Sélectionnez Create policy, puis JSON pour l”Policy editor.

4. Remplacez la politique vide par une politique ayant l’autorisation d’appeler vos méthodes API. Par exemple, la politique générale suivante autorise l’action d’appel pour toutes les ressources d’API Gateway dans un compte AWS.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "execute-api:Invoke"
           ],
           "Resource": "arn:aws:execute-api:*:<aws_account_id>:*"
       }
     ]
   }
   

   Copy

   Important

   En tant que bonne pratique, utilisez une politique qui accorde les privilèges minimaux requis pour votre cas d’utilisation. Pour des conseils supplémentaires et des exemples de politiques, voir Contrôle de l’accès à une API avec les autorisations IAM.

5. Sélectionnez Next.

6. Saisissez un Policy name (par exemple, snowflake_access) et une Description facultative.

7. Sélectionnez Create policy.

8. Dans le volet de navigation gauche du tableau de bord IAM, sélectionnez Roles.

9. Sélectionnez un rôle auquel joindre la politique. Lorsque vous créez une intégration de catalogue, vous spécifiez ce rôle. Si vous n’avez pas de rôle, créez un nouveau rôle.

10. Sur la page Summary du rôle, dans l’onglet Permissions, sélectionnez Add permissions » Attach policies.

11. Recherchez et cochez la case à côté de la politique que vous avez créée pour API Gateway, puis sélectionnez Add permissions.

12. Sur la page Summary du rôle, copiez le rôle ARN. Vous spécifiez l’ARN lorsque vous créez une intégration de catalogue.

Joindre une politique des ressources API Gateway (APIs privées uniquement)¶

Si votre API REST est privée, vous devez joindre une ressource Amazon API Gateway à votre API. La politique de ressources permet à Snowflake d’appeler votre API depuis le Cloud privé virtuel d’Amazon (VPC) dans lequel votre compte Snowflake se trouve.

1. Dans Snowflake, appelez la fonction SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO pour récupérer l’IDs du VPC dans lequel votre compte Snowflake se trouve. Depuis la sortie de la fonction, pour chaque propriété identifiée par « purpose »: « generic », enregistrer le(s) identifiants VPC (ID) correspondant(s).

   SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
   

   Copy

   Sortie :

   {
     "snowflake-vpc-id": ["vpc-c1c234a5"],
     "snowflake-egress-vpc-ids": [
       ...
       {
         "id": "vpc-c1c234a5",
         "expires": "2025-03-01T00:00:00",
         "purpose": "generic"
       },
       ...
     ]
   }
   

2. Suivez les instructions indiquées dans Joindre des politiques de ressources API Gateway pour joindre une politique de ressources à votre API REST.

   Collez et modifiez l’exemple de politique suivant.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Deny",
         "Principal": "*",
         "Action": "execute-api:Invoke",
         "Resource": "<api_gateway_arn>",
         "Condition": {
           "StringNotEquals": {
             "aws:sourceVpc": "<snowflake_vpc_id>"
           }
         }
       },
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:sts::123456789XXX:assumed-role/<my_api_permissions_role_name>/snowflake"
         },
         "Action": "execute-api:Invoke",
         "Resource": "<api_gateway_arn>/*/*/*",
         "Condition": {
           "StringEquals": {
             "aws:sourceVpc": "<snowflake_vpc_id>"
           }
         }
       }
     ]
   }
   

   Copy

La première instruction de la politique refuse toutes les requêtes qui ne proviennent pas du VPC Snowflake. La deuxième instruction autorise l’action d’appel (pour toutes les méthodes) des requêtes provenant du VPC Snowflake qui utilisent le principal de séance.

Pour en savoir plus sur les politiques de ressources d’APIGateway, voir :

• Contrôle de l’accès à une API avec les politiques de ressources d’API Gateway

• Exemples de politiques de ressources d’API Gateway

Sélection d’une autorisation IAM pour votre API¶

Sélectionnez une autorisation IAM pour chaque méthode à laquelle vous souhaitez donner accès dans votre API REST. Avec l’autorisation IAM, Snowflake peut utiliser le rôle IAM que vous avez configuré pour effectuer des appels vers l’API.

1. Dans la console Amazon API Gateway, sélectionnez votre API REST.

2. Pour chaque méthode :

   1. Sous Resources, sélectionnez une méthode dans la liste.

   2. Sous Method request settings, sélectionnez Edit.

   3. Pour Authorization, sélectionnez AWS IAM.

   4. Sélectionnez Save.

3. Pour appliquer les modifications d’autorisation, sélectionnez Deploy API. Pour plus d’informations, voir Déploiement d’une API REST dans la console API Gateway.

Récupération de l’URL du point de terminaison¶

Récupérez le point de terminaison de votre API REST URL (ou appelez l’URL). Votre API doit être déployée vers une zone de préparation avant de pouvoir récupérer l’URL du point de terminaison.

1. Dans la console Amazon API Gateway, sélectionnez votre API REST.

2. Dans le volet de navigation de gauche, sélectionnez Stages.

3. Sous Stage details, copiez l”Invoke URL.

Vous spécifiez l’URL du point de terminaison lorsque vous créez une intégration de catalogue.

Création d’une intégration de catalogue pour SigV4¶

Après avoir obtenu une API REST dans Amazon API Gateway et exécuté les étapes initiales pour contrôler l’accès à votre API à l’aide des autorisations IAM, vous pouvez créer une intégration de catalogue dans Snowflake.

Pour afficher la syntaxe de la commande et les descriptions des paramètres, voir CREATE CATALOG INTEGRATION (Apache Iceberg™ REST).

API REST publique

Pour créer une intégration de catalogue pour une API REST publique, spécifiez ICEBERG_REST comme CATALOG_SOURCE et utilisez l’authentification SIGV4.

Incluez des détails comme l’URL du point de terminaison de l’API l’ARN du rôle IAM.

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    CATALOG_API_TYPE = AWS_API_GATEWAY
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789XXX:role/my_api_permissions_role'
    SIGV4_EXTERNAL_ID = 'my_iceberg_external_id'
  )
  ENABLED = TRUE;

API REST privée

Pour créer une intégration de catalogue pour une API REST privée, vous devez définir le paramètre CATALOG_API_TYPE sur AWS_PRIVATE_API_GATEWAY.

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    CATALOG_API_TYPE = AWS_PRIVATE_API_GATEWAY
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789XXX:role/my_api_permissions_role'
    SIGV4_EXTERNAL_ID = 'my_iceberg_external_id'
  )
  ENABLED = TRUE;

Configuration de la relation de confiance dans IAM¶

Récupérez les informations sur l’utilisateur AWS IAM qui a été créé pour votre compte Snowflake lorsque vous avez créé l’intégration du catalogue, et configurez la relation de confiance pour votre rôle IAM.

1. Dans Snowflake, appelez la commande DESCRIBE CATALOG INTEGRATION :

   DESCRIBE CATALOG INTEGRATION my_rest_catalog_integration;
   

   Copy

   Notez les valeurs suivantes :

   Valeur	Description
   API_AWS_IAM_USER_ARN	Utilisateur IAM AWS créé pour votre compte Snowflake, par exemple, arn:aws:iam::123456789001:user/abc1-b-self1234. Snowflake provisionne un seul utilisateur IAM pour l’intégralité de votre compte Snowflake.
   API_AWS_EXTERNAL_ID	L’ID externe nécessaire pour établir une relation de confiance. Si vous n’avez pas spécifié d’ID (SIGV4_EXTERNAL_ID) externe lors de la création de l’intégration du catalogue, Snowflake génère un ID que vous pouvez utiliser. Enregistrez la valeur afin de pouvoir mettre à jour votre politique de confiance du rôle IAM avec l’ID de rôle externe généré.

2. Dans la console de gestion AWS, recherchez et sélectionnez IAM.

3. Dans le volet de navigation de gauche, sélectionnez Roles.

4. Sélectionnez le rôle IAM que vous avez créé pour votre intégration de catalogue.

5. Sélectionnez l’onglet Trust relationships.

6. Sélectionnez Edit trust policy.

7. Modifiez le document de politique en y ajoutant les valeurs que vous avez enregistrées.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<api_aws_iam_user_arn>"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "<api_aws_external_id>"
           }
         }
       }
     ]
   }
   

   Copy

8. Sélectionnez Update policy pour enregistrer vos modifications.