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;
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;
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;
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.
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.
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.
Dans la console de gestion AWS, recherchez et sélectionnez API Gateway.
Sélectionnez Create API.
Sélectionnez Build sous REST API. Pour créer une API REST privée, sélectionnez Build sous REST API Private.
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.
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.
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.
Dans la console de gestion AWS, recherchez et sélectionnez IAM.
Dans le volet de navigation de gauche, sélectionnez Policies.
Sélectionnez Create policy, puis JSON pour l”Policy editor.
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>:*" } ] }
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.
Sélectionnez Next.
Saisissez un Policy name (par exemple,
snowflake_access
) et une Description facultative.Sélectionnez Create policy.
Dans le volet de navigation gauche du tableau de bord IAM, sélectionnez Roles.
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.
Sur la page Summary du rôle, dans l’onglet Permissions, sélectionnez Add permissions » Attach policies.
Recherchez et cochez la case à côté de la politique que vous avez créée pour API Gateway, puis sélectionnez Add permissions.
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.
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();
Sortie :
{"snowflake-vpc-id":["vpc-c1c234a5"]}
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>" } } } ] }
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 :
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.
Dans la console Amazon API Gateway, sélectionnez votre API REST.
Dans le volet de navigation de gauche, sélectionnez Stages.
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;
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.
Dans Snowflake, appelez la commande DESCRIBE CATALOG INTEGRATION :
DESCRIBE CATALOG INTEGRATION my_rest_catalog_integration;
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é.Dans la console de gestion AWS, recherchez et sélectionnez IAM.
Dans le volet de navigation de gauche, sélectionnez Roles.
Sélectionnez le rôle IAM que vous avez créé pour votre intégration de catalogue.
Sélectionnez l’onglet Trust relationships.
Sélectionnez Edit trust policy.
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>" } } } ] }
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>"
]
}
]
}
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 GlueSi 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;
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;
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');
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
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ètreOAUTH_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ètreOAUTH_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ètreOAUTH_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
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 leaccess_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
Où :
prefix
spécifie éventuellement le préfixe obtenu à partir de la réponse précédente degetConfig
.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
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 leaccess_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
Où :
prefix
spécifie éventuellement le préfixe obtenu à partir de la réponse précédente degetConfig
.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
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"
}
}
}
]
}
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>
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"
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 leAccessKeyId
que vous avez récupéré à l’aide de la commandests assume-role
.$AWS_SECRET_ACCESS_KEY
est une variable qui contient leSecretAccessKey
que vous avez récupéré à l’aide de la commandests assume-role
.aws:amz:us-west-2:execute-api
est le nom de signature du protocole SigV4. Pour AWS Glue, utilisez plutôtaws:amz:us-west-2:glue
.$AWS_SESSION_TOKEN
est une variable qui contient leSessionToken
que vous avez récupéré à l’aide de la commandests 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"
Où :
prefix
spécifie éventuellement le préfixe obtenu à partir de la réponse précédente degetConfig
.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"
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.