Configuration d’une intégration de catalogue pour les catalogues Apache Iceberg™ REST

Une intégration de catalogue Apache Iceberg™ REST <label-tables_iceberg_catalog_integration_def> permet à Snowflake d’accéder aux Tables Apache Iceberg™ gérées dans un catalogue distant conforme à la spécification Apache Iceberg REST OpenAPI open source.

Connexion aux catalogues REST

Vous pouvez vous connecter à une API REST Iceberg qui utilise un point de terminaison public ou un réseau privé.

Point de terminaison public

Pour se connecter à une API REST Iceberg à l’aide d’un point de terminaison public, vous pouvez créer une intégration de catalogue qui utilise les méthodes d’authentification suivantes :

  • OAuth

  • Jeton porteur ou jeton d’accès personnel (PAT)

  • SigV4

Réseau privé

Pour se connecter à une API REST Iceberg qui est hébergée sur un réseau privé, vous pouvez créer une intégration de catalogue qui utilise l’authentification Signature Version 4 (SigV4).

Créer une intégration de catalogue

Créez une intégration de catalogue pour la méthode d’authentification choisie à l’aide de la commande CREATE CATALOG INTEGRATION (Apache Iceberg™ REST). Les valeurs que vous spécifiez pour les arguments REST_CONFIG et REST_AUTHENTICATION diffèrent selon la méthode d’authentification que vous choisissez.

OAuth

L’exemple suivant crée une intégration REST de catalogue qui utilise OAuth pour se connecter à Tabular.

CREATE OR REPLACE CATALOG INTEGRATION tabular_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://api.tabular.io/ws'
    WAREHOUSE = '<tabular_warehouse_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://api.tabular.io/ws/v1/oauth/tokens'
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('catalog')
  )
  ENABLED = TRUE;
Copy

L’exemple suivant crée une intégration de catalogue REST qui utilise OAuth pour se connecter au catalogue Databricks Unity.

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_oauth
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://my-api/api/2.1/unity-catalog/iceberg'
    WAREHOUSE = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://my-api/oidc/v1/token'
    OAUTH_CLIENT_ID = '123AbC ...'
    OAUTH_CLIENT_SECRET = '1365910ab ...'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;
Copy

Jeton porteur ou PAT

L’exemple suivant crée une intégration de catalogue REST qui utilise un jeton PAT pour se connecter au catalogue Databricks Unity.

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_pat
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://my-api/api/2.1/unity-catalog/iceberg'
    WAREHOUSE = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = 'eyAbCD...eyDeF...'
  )
  ENABLED = TRUE;
Copy

SigV4 (API Gateway)

Le diagramme suivant montre comment Snowflake interagit avec votre serveur de catalogue REST à l’aide d’API Gateway et de l’authentification SigV4.

Diagramme montrant comment un catalogue REST Iceberg fonctionne avec Amazon API Gateway, IAM et S3.

Suivez les étapes de cette section pour utiliser une API REST dans Amazon API Gateway et l’authentification Signature Version 4 (SigV4) pour connecter Snowflake en toute sécurité à un catalogue REST Iceberg qui n’est pas accessible au public.

  1. Création d’une API REST dans Amazon API Gateway

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

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

  4. Sélection d’une autorisation IAM pour votre API

  5. Récupération de l’URL du point de terminaison

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

  7. Configuration de la relation de confiance dans IAM

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.

Note

Pour importer la définition OpenAPI du catalogue Iceberg, vous devez modifier le fichier YAML. Amazon API Gateway ne prend pas en charge tous les composants des spécifications OpenAPI 2.0 ou 3.0. Pour plus d’informations, voir Notes importantes sur Amazon API Gateway pour les APIs REST.

  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’ID du VPC dans lequel votre compte Snowflake se trouve. Copiez l’ID du VPC à partir de la sortie de fonction.

    SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
    
    Copy

    Sortie :

    {"snowflake-vpc-id":["vpc-c1c234a5"]}
    
  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 :

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;
Copy

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;
Copy

Note

Les deux exemples spécifient un ID externe (SIGV4_EXTERNAL_ID = 'my_iceberg_external_id') que vous pouvez utiliser dans la relation de confiance pour votre rôle IAM (dans l’étape suivante).

La spécification d’un ID externe vous permet d’utiliser le même rôle IAM dans plusieurs intégrations de catalogues sans mettre à jour la politique de confiance du rôle IAM. Cette procédure est particulièrement utile dans les scénarios de test si vous devez créer ou remplacer plusieurs fois une intégration de catalogue.

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.

SigV4 (Glue)

Suivez les étapes de cette section pour créer une intégration de catalogue pour le point de terminaison AWS Glue Iceberg REST avec authentification Signature Version 4 (SigV4).

Étape 1 : Configurer des autorisations d’accès pour le catalogue de données AWS Glue

Créez une politique IAM pour que Snowflake puisse accéder au catalogue de données AWS Glue. Attachez la politique à un rôle IAM, que vous spécifiez lors de la création d’une intégration au catalogue. Pour des instructions, voir Création de politiques IAM et Modification d’une politique d’autorisations de rôle dans le Guide de l’utilisateur IAM (Identity and Access Management - Gestion de l’identité et de l’accès) AWS.

Au minimum, Snowflake requiert les autorisations suivantes sur le catalogue de données Glue AWS pour accéder aux informations utilisant le catalogue Glue Iceberg REST.

  • glue:GetConfig

  • glue:GetDatabase

  • glue:GetDatabases

  • glue:GetTable

  • glue:GetTables

L’exemple de politique suivant (au format JSON) fournit les autorisations nécessaires pour pouvoir accéder à toutes les tables d’une base de données spécifique.

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Sid": "AllowGlueCatalogTableAccess",
         "Effect": "Allow",
         "Action": [
           "glue:GetConfig",
           "glue:GetDatabase",
           "glue:GetDatabases",
           "glue:GetTable",
           "glue:GetTables"
         ],
         "Resource": [
            "arn:aws:glue:*:<accountid>:table/*/*",
            "arn:aws:glue:*:<accountid>:catalog",
            "arn:aws:glue:*:<accountid>:database/<database-name>"
         ]
      }
   ]
}
Copy

Note

  • Vous pouvez modifier l’élément Resource de cette politique pour restreindre davantage les ressources autorisées (par exemple, le catalogue, les bases de données ou les tables). Pour plus d’informations, voir Types de ressource définis par AWS Glue

  • Si vous utilisez le chiffrement pour AWS Glue, vous devez modifier la politique pour ajouter des autorisations Key Management Service AWS (AWSKMS). Pour plus d’informations, voir Configuration du chiffrement dans AWS Glue.

Étape 2 : Créer une intégration de catalogue dans Snowflake

Créez une intégration au catalogue pour le point de terminaison AWS Glue Iceberg REST à l’aide de la commande CREATE CATALOG INTEGRATION (Apache Iceberg™ REST). Indiquez le rôle IAM que vous avez configuré. Pour WAREHOUSE, utilisez l’ID de votre compte AWS.

CREATE CATALOG INTEGRATION glue_rest_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'rest_catalog_integration'
  REST_CONFIG = (
    CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'
    CATALOG_API_TYPE = AWS_GLUE
    WAREHOUSE = '123456789012'
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my-role'
    SIGV4_SIGNING_REGION = 'us-west-2'
  )
  ENABLED = TRUE;
Copy

Vérifier la configuration de votre catalogue REST

Vous pouvez utiliser les scénarios suivants pour vérifier si vous avez correctement configuré l’autorisation et le contrôle d’accès avec votre catalogue Iceberg REST afin que Snowflake puisse interagir avec votre serveur de catalogue.

Utiliser SYSTEM$VERIFY_CATALOG_INTEGRATION

Vous pouvez utiliser la fonctionnalité SYSTEM$VERIFY_CATALOG_INTEGRATION pour vérifier la configuration de l’intégration de votre catalogue.

L’exemple suivant montre comment la fonction système détecte et signale les problèmes liés à une intégration de catalogue mal configurée.

L’instruction suivante crée une intégration de catalogue REST avec un secret client OAuth non valide (exécution sans erreur) :

CREATE CATALOG INTEGRATION my_rest_cat_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://abc123.us-west-2.aws.myapi.com/polaris/api/catalog'
    WAREHOUSE = 'my_warehouse'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '123AbC ...'
    OAUTH_CLIENT_SECRET = '1365910abIncorrectSecret ...'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;
Copy

Utiliser la fonction système pour vérifier l’intégration de catalogue, où un échec est attendu :

SELECT SYSTEM$VERIFY_CATALOG_INTEGRATION('my_rest_cat_int');
Copy

Sortie :

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                                                                                              SYSTEM$VERIFY_CATALOG_INTEGRATION('MY_REST_CAT_INT')                                                                                                               |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| {                                                                                                                                                                                                                                                                               |
|  "success" : false,                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                    |
|   "errorCode" : "004155",                                                                                                                                                                                                                                                       |
|   "errorMessage" : "SQL Execution Error: Failed to perform OAuth client credential flow for the REST Catalog integration MY_REST_CAT_INT due to error: SQL execution error: OAuth2 Access token request failed with error 'unauthorized_client:The client is not authorized'.." |
| }                                                                                                                                                                                                                                                                               |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Vérifier une configuration pour OAuth

Suivez ces étapes pour vérifier votre configuration pour OAuth avec votre catalogue REST distant.

Étape 1 : Récupérer un jeton d’accès

Utilisez une commande curl pour récupérer un jeton d’accès dans votre catalogue. L’exemple suivant demande un jeton d’accès à Snowflake Open Catalog :

curl -X POST https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "scope=PRINCIPAL_ROLE:ALL" \
    --data-urlencode "client_id=<my_client_id>" \
    --data-urlencode "client_secret=<my_client_secret>" | jq
Copy

Où :

  • https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens est le point de terminaison pour récupérer un jeton OAuth (getToken).

  • scope est identique à la valeur que vous spécifiez pour le paramètre OAUTH_ALLOWED_SCOPES lorsque vous créez une intégration au catalogue. Pour les champs d’application multiples, utilisez un espace comme séparateur.

  • my_client_id est le même ID de client que celui que vous spécifiez pour le paramètre OAUTH_CLIENT_ID lorsque vous créez une intégration de catalogue.

  • my_client_secret est le même secret client que celui que vous spécifiez pour le paramètre OAUTH_CLIENT_SECRET lorsque vous créez une intégration de catalogue.

Exemple de valeur de retour :

{
  "access_token": "xxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "expires_in": 3600
}

Étape 2 : Vérifier les autorisations du jeton d’accès

À l’aide du jeton d’accès que vous avez récupéré à l’étape précédente, vérifiez que vous avez l’autorisation d’accéder à votre serveur de catalogue.

Vous pouvez utiliser la commande curl pour dresser la liste des paramètres de configuration de votre catalogue :

curl -X GET "https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>" \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq
Copy

Où :

  • ?warehouse=warehouse spécifie éventuellement le nom de l’entrepôt à requérir dans votre catalogue (si pris en charge). Pour Snowflake Open Catalog, le nom de l’entrepôt est le nom de votre catalogue.

  • ACCESS_TOKEN est une variable qui contient le access_token que vous avez récupéré à l’étape précédente.

Exemple de valeur de retour :

{
  "defaults": {
    "default-base-location": "s3://my-bucket/polaris/"
  },
  "overrides": {
    "prefix": "my-catalog"
  }
}

Étape 3 : Charger une table à partir du catalogue

Vous pouvez également faire une requête GET pour charger une table. Snowflake utilise l’opération loadTable pour charger les données de table de votre catalogue REST.

curl -X GET "https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/<prefix>/namespaces/<namespace>/tables/<table>" \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq
Copy

Où :

  • prefix spécifie éventuellement le préfixe obtenu à partir de la réponse précédente de getConfig.

  • namespace est l’espace de noms de la table que vous souhaitez récupérer. Si l’espace de noms est imbriqué, utilisez le séparateur %1F ; par exemple, parentNamespace%1FchildNamespace.

  • table est le nom de la table.

Vérifier la configuration d’un jeton de support

Suivez ces étapes pour vérifier votre configuration avec votre catalogue REST distant pour l’utilisation d’un jeton de support.

Étape 1 : Vérifier les autorisations du jeton d’accès

Utilisez une commande curl pour vérifier que vous avez l’autorisation d’accéder à votre serveur de catalogue :

curl -X GET "https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>" \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer ${BEARER_TOKEN}" | jq
Copy

Où :

  • https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens est le point de terminaison pour récupérer un jeton OAuth (getToken).

  • ?warehouse=warehouse spécifie éventuellement le nom de l’entrepôt à requérir dans votre catalogue (si pris en charge).

  • BEARER_TOKEN est une variable qui contient le access_token que vous avez récupéré à l’étape précédente.

Exemple de valeur de retour :

{
  "defaults": {
    "default-base-location": "s3://my-bucket/polaris"
  },
  "overrides": {
    "prefix": "my-catalog"
  }
}

Étape 2 : Charger une table à partir du catalogue

Vous pouvez également faire une requête GET pour charger une table. Snowflake utilise l’opération loadTable pour charger les données de table de votre catalogue REST.

curl -X GET "https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/<prefix>/namespaces/<namespace>/tables/<table>" \
    -H "Accepts: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer ${BEARER_TOKEN}" | jq
Copy

Où :

  • prefix spécifie éventuellement le préfixe obtenu à partir de la réponse précédente de getConfig.

  • namespace est l’espace de noms de la table que vous souhaitez récupérer. Si l’espace de noms est imbriqué, utilisez le séparateur %1F ; par exemple, parentNamespace%1FchildNamespace.

  • table est le nom de la table.

Vérifier une configuration pour SigV4

Suivez ces étapes pour vérifier votre configuration pour SigV4 avec AWS.

Étape 1 : Ajouter votre utilisateur à la relation de confiance du rôle IAM

Lorsque vous créez une intégration au catalogue REST pour SigV4, Snowflake prévoit un utilisateur AWS IAM pour votre compte Snowflake. Vous ajoutez cet utilisateur IAM Snowflake à la relation de confiance pour un rôle IAM avec l’autorisation d’accès à vos ressources API Gateway.

Pour tester votre configuration, vous pouvez endosser le rôle d’utilisateur dans votre compte AWS après avoir ajouté votre utilisateur AWS au document de politique de confiance du rôle. Pour récupérer votre utilisateur actuel IAM ARN, utilisez la commande sts get-caller-identity pour l’interface de ligne de commande AWS (CLI) :

aws sts get-caller-identity
Copy

Exemple de sortie :

{
  "UserId": "ABCDEFG1XXXXXXXXXXX",
  "Account": "123456789XXX",
  "Arn": "arn:aws:iam::123456789XXX:user/managed/my_user"
}

Le document de politique de confiance mis à jour doit inclure à la fois l’ARN d’utilisateur Snowflake et l’ARN de votre utilisateur, comme suit :

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

Pour des instructions complètes, voir Mettre à jour une politique de confiance dans les rôles dans la documentation AWS IAM.

Étape 2 : Endosser votre rôle IAM pour obtenir des identifiants temporaires

Pour obtenir des identifiants de sécurité temporaires pour AWS, utilisez la commande sts assume-role pour AWS CLI.

aws sts assume-role \
  --role-arn <my_role_arn> \
  --role-session-name <session_name>
Copy

Où :

  • my_role_arn est le nom de ressource Amazon (ARN) du rôle IAM que vous avez configuré pour Snowflake.

  • session_name est un identificateur de chaîne de votre choix pour la session du rôle assumé ; par exemple, my_rest_session.

Exemple de sortie :

{
  "Credentials": {
      "AccessKeyId": "XXXXXXXXXXXXXXXXXXXXX",
      "SecretAccessKey": "XXXXXXXXXXXXXXXXXXXXX",
      "SessionToken": "XXXXXXXXXXXXXXXXXXXXX",
      "Expiration": "2024-10-09T08:13:15+00:00"
  },
  "AssumedRoleUser": {
      "AssumedRoleId": "{AccessKeyId}:my_rest_catalog_session",
      "Arn": "arn:aws:sts::123456789XXX:assumed-role/my_catalog_role/my_rest_catalog_session"
  }
}

Note

Si la commande assume-role échoue, cela signifie que votre utilisateur actuel AWS n’est pas inclus dans la politique de confiance du rôle en tant que principal autorisé.

De même, si l’ARN de l’utilisateur IAM Snowflake n’est pas inclus dans votre politique de confiance, Snowflake ne pourra pas se connecter aux ressources de API Gateway. Pour plus d’informations, voir Configuration de la relation de confiance dans IAM.

Étape 3 : Vérifier que votre rôle IAM dispose des autorisations nécessaires

En utilisant les identifiants temporaires que vous avez récupérés à l’étape précédente, vérifiez que votre rôle IAM a l’autorisation d’invoquer vos APIs API Gateway.

Vous pouvez utiliser la commande curl pour dresser la liste des paramètres de configuration de votre catalogue :

curl -v -X GET  "https://123xxxxxxx.execute-api.us-west-2.amazonaws.com/test_v2/v1/config?warehouse=<warehouse>" \
  --user "$AWS_ACCESS_KEY_ID":"$AWS_SECRET_ACCESS_KEY" \
  --aws-sigv4 "aws:amz:us-west-2:execute-api" \
  -H "x-amz-security-token: $AWS_SESSION_TOKEN"
Copy

Où :

  • 123xxxxxxx.execute-api.us-west-2.amazonaws.com est le nom d’hôte de votre API Gateway.

  • test_v2 est le nom de la zone de préparation dans laquelle votre API est déployée.

  • v1/config spécifie l’opération getConfig à partir de la définition du catalogue Iceberg OpenAPI.

  • ?warehouse=warehouse spécifie éventuellement le nom de l’entrepôt à requérir dans votre catalogue (si pris en charge).

  • $AWS_ACCESS_KEY_ID est une variable qui contient le AccessKeyId que vous avez récupéré à l’aide de la commande sts assume-role.

  • $AWS_SECRET_ACCESS_KEY est une variable qui contient le SecretAccessKey que vous avez récupéré à l’aide de la commande sts assume-role.

  • aws:amz:us-west-2:execute-api est le nom de signature du protocole SigV4. Pour AWS Glue, utilisez plutôt aws:amz:us-west-2:glue.

  • $AWS_SESSION_TOKEN est une variable qui contient le SessionToken que vous avez récupéré à l’aide de la commande sts assume-role.

Exemple de valeur de retour :

{
  "defaults": {},
  "overrides": {
    "prefix": "my-catalog"
  }
}

Vous pouvez également faire une requête GET pour charger une table. Snowflake utilise l’opération loadTable pour charger les données de table de votre catalogue REST.

curl -v -X GET "https://123xxxxxxx.execute-api.us-west-2.amazonaws.com/test_v2/v1/<prefix>/namespaces/<namespace>/tables/<table>" \
    --user "$AWS_ACCESS_KEY_ID":"$AWS_SECRET_ACCESS_KEY" \
    --aws-sigv4 "aws:amz:us-west-2:execute-api" \
    -H "x-amz-security-token: $AWS_SESSION_TOKEN"
Copy

Où :

  • prefix spécifie éventuellement le préfixe obtenu à partir de la réponse précédente de getConfig.

  • namespace est l’espace de noms de la table que vous souhaitez récupérer. Si l’espace de noms est imbriqué, utilisez le séparateur %1F ; par exemple, parentNamespace%1FchildNamespace.

  • table est le nom de la table.

API privée

Pour une API privée, vous pouvez spécifier votre point de terminaison VPC et le nom d’hôte de Amazon API Gateway privée dans les mêmes commandes curl.

Par exemple :

curl -v -X GET  "https://vpce-xxxxxxxxxxxxxxxxxxxxxxxxxx.execute-api.us-west-2.vpce.amazonaws.com/test_v2/v1/config?warehouse=<warehouse>" \
  --user "$AWS_ACCESS_KEY_ID":"$AWS_SECRET_ACCESS_KEY" \
  --aws-sigv4 "aws:amz:us-west-2:execute-api" \
  -H "x-amz-security-token: $AWS_SESSION_TOKEN"
  -H "Host: abc1defgh2.execute-api.us-west-2.amazonaws.com"
Copy

Où :

  • https://vpce-xxxxxxxxxxxxxxxxxxxxxxxxxx.execute-api.us-west-2.vpce.amazonaws.com/... est le nom d’hôte de votre point de terminaison VPC.

  • abc1defgh2.execute-api.us-west-2.amazonaws.com est le nom d’hôte de votre API privée dans Amazon API Gateway.