Spécifier le contexte Snowflake avec Snowflake REST APIs

Vous pouvez spécifier des aspects du contexte Snowflake lorsque vous envoyez une requête au Snowflake REST APIs.

En utilisant des en-têtes de requête, vous pouvez spécifier les éléments suivants dans le contexte d’un appel d’API REST :

  • Le rôle Snowflake utilisé pour autoriser la requête avec l’en-tête X-Snowflake-Role.

  • L’entrepôt Snowflake utilisé pour exécuter la requête avec l’en-tête X-Snowflake-Warehouse.

Au lieu de s’appuyer sur les paramètres par défaut d’un utilisateur, ces en-têtes rendent chaque appel explicite, isolé et auditable. Vous garantissez que chaque requête utilise le bon rôle et le bon entrepôt sans avoir besoin de davantage d’appels API pour définir le contexte.

En spécifiant le contexte lors de la création de requêtes d’API REST, vous pouvez accomplir les tâches suivantes :

  • Exécutez des appels sans état.

    Garantissez qu’un appel utilise un rôle spécifique sans avoir besoin d’un appel API distinct au préalable pour définir le contexte de la session.

  • Évitez de muter les utilisateurs.

    Changez de rôle en toute sécurité par requête au lieu d’exécuter ALTER USER … SET DEFAULT_ROLE=…, ce qui est lent et affecte toutes les autres sessions de cet utilisateur.

  • Activez le calcul à la demande.

    Permettez aux utilisateurs ou aux comptes de service sans entrepôt par défaut d’exécuter des requêtes ou de créer des procédures en fournissant simplement l’en-tête X-Snowflake-Warehouse.

  • Simplifiez la gestion des utilisateurs.

    Utilisez un utilisateur de service auquel ont été accordés plusieurs rôles, par exemple READER et WRITER. Votre application envoie ensuite l’en-tête X-Snowflake-Role pour choisir l’autorisation appropriée pour la tâche appropriée. De cette manière, vous pouvez éviter de gérer plusieurs utilisateurs à rôle unique.

Ordre de précédence

Lorsqu’un en-tête est fourni, celui-ci a la priorité sur les paramètres par défaut de l’utilisateur, dans l’ordre suivant :

  1. Les en-têtes (si fournis) sont utilisés.

  2. Dans le cas contraire, le rôle par défaut ou l’entrepôt par défaut de la session est utilisé.

  3. Si aucun des deux n’est disponible en cas de besoin, l’appel échoue.

Spécifier le rôle à utiliser lors de l’autorisation de la requête

Vous pouvez spécifier le rôle à utiliser lors de l’autorisation de la requête en utilisant l’en-tête X-Snowflake-Role.

Exigences

  • Le rôle que vous spécifiez doit exister, être accordé à l’utilisateur et être autorisé par la méthode d’authentification utilisée.

  • Si vous utilisez un jeton d’accès programmatique (PAT), le rôle demandé doit se trouver dans le ROLE_RESTRICTION du PAT. Si vous spécifiez un rôle plus privilégié que le PAT autorise, la requête échouera même si le rôle spécifié a été accordé à l’utilisateur.

Exemple

L’exemple suivant crée une base de données à l’aide du rôle ACCOUNTADMIN pour l’autorisation, quel que soit le rôle par défaut de l’utilisateur.

Vous pouvez spécifier la valeur de l’en-tête X-Snowflake-Role entre guillemets doubles ou sans guillemets.

curl -X POST "$API_BASE/database/databases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Snowflake-Role: ACCOUNTADMIN" \
  -d '{"name": "HDR_DEMO_DB", "comment": "Created via REST with role header"}'
Copy

Spécifier l’entrepôt sur lequel une instruction doit être exécutée

Vous pouvez spécifier l’entrepôt à utiliser lors de l’exécution d’instructions en utilisant l’en-tête X-Snowflake-Warehouse. Ces instructions incluent celles qui exécutent des procédures, créent des fonctions Python et exécutent des requêtes qui nécessitent des ressources de calcul.

Exigences

  • Le rôle en vigueur doit disposer du privilège USAGE sur l’entrepôt.

  • Si aucun entrepôt par défaut n’est défini et que cet en-tête est omis, les appels dépendants de l’entrepôt échoueront.

Exemple

L’exemple suivant crée une procédure Python qui utilise l’entrepôt BUILD_WH. Le rôle spécifié doit disposer du privilège USAGE sur l’entrepôt. La procédure PYTHON_WH_TEST créée renvoie le nom de l’entrepôt actif.

Vous pouvez spécifier la valeur de l’en-tête X-Snowflake-Warehouse entre guillemets doubles ou sans guillemets.

curl -X POST "$API_BASE/procedure/databases/TEST_DB/schemas/TEST_SCHEMA/procedures" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Snowflake-Role: ACCOUNTADMIN" \
  -H "X-Snowflake-Warehouse: BUILD_WH" \
  -d '{
        "name": "PYTHON_WH_TEST",
        "arguments": [],
        "return_type": {"datatype": "VARIANT", "nullable": true},
        "language_config": {
          "python_function": {
            "handler":"main",
            "runtime_version":"3.11",
            "packages":["snowflake-snowpark-python"]
          }
        },
        "body": "def main(session):\n    return {\"warehouse\": session.get_current_warehouse()}"
      }'
Copy
Langage: Français