Vérifier la configuration de votre catalogue REST¶

É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è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

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

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.

É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 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

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.

É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"
  }
}

É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 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"

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"

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.