Especificação de contexto do Snowflake com Snowflake REST APIs

Você pode especificar aspectos do contexto do Snowflake ao fazer uma solicitação para Snowflake REST APIs.

Usando cabeçalhos de solicitação, você pode especificar o seguinte no contexto de uma chamada de API REST:

  • A função do Snowflake usada para autorizar a solicitação com o cabeçalho X-Snowflake-Role.

  • O warehouse do Snowflake usado para executar a solicitação com o cabeçalho X-Snowflake-Warehouse.

Em vez de confiar nas configurações padrão de um usuário, esses cabeçalhos tornam cada chamada explícita, isolada e auditável. Você garante que cada solicitação use a função e o warehouse corretos sem precisar de chamadas de API extras para definir o contexto.

Ao especificar o contexto durante a criação das solicitações de API REST, você pode realizar as seguintes tarefas:

  • Executar chamadas sem estado.

    Garanta que a chamada use uma função específica sem precisar primeiro de uma chamada de API separada para definir o contexto da sessão.

  • Evitar mutação de usuários.

    Alterne funções com segurança por solicitação em vez de executar ALTER USER … SET DEFAULT_ROLE=…, que é lento e afeta todas as outras sessões do usuário.

  • Habilitar computação sob demanda.

    Permita que usuários ou contas de serviço sem um warehouse padrão executem consultas ou criem procedimentos apenas inserindo o cabeçalho X-Snowflake-Warehouse.

  • Simplificar o gerenciamento de usuários.

    Utilize um usuário de serviço com várias funções concedidas; por exemplo, READER e WRITER. Seu aplicativo envia o cabeçalho X-Snowflake-Role para escolher a permissão correta para a tarefa certa. Dessa forma, você evita ter que gerenciar vários usuários com uma única função.

Precedência

Quando um cabeçalho é inserido, ele tem precedência sobre as configurações padrão do usuário, na seguinte ordem:

  1. Os cabeçalhos são usados (se fornecidos).

  2. Caso contrário, a função padrão da sessão ou o warehouse padrão é usado.

  3. Se nenhum deles estiver disponível quando necessário, haverá falha na chamada.

Especificação da função que será usada ao autorizar a solicitação

Você pode especificar a função que será usada ao autorizar a solicitação por meio do cabeçalho X-Snowflake-Role.

Requisitos

  • A função especificada deve existir, ser concedida ao usuário e ser permitida pelo método de autenticação em uso.

  • Se você usar um token de acesso programático (Programmatic Access Token, PAT), a função solicitada deverá estar em ROLE_RESTRICTION do PAT. Se você especificar uma função mais privilegiada do que o permitido pelo PAT, a solicitação falhará mesmo que o usuário tenha recebido a função especificada.

Exemplo

O exemplo a seguir cria um banco de dados usando a função ACCOUNTADMIN para autorização, seja qual for a função padrão do usuário.

Você pode especificar o valor do cabeçalho X-Snowflake-Role entre aspas duplas ou sem aspas.

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

Especificação do warehouse no qual executar uma instrução

Você pode especificar o warehouse que será usado ao executar instruções por meio do cabeçalho X-Snowflake-Warehouse. Essas instruções incluem as que executam procedimentos, criam funções do Python e executam consultas que precisam de recursos computacionais.

Requisitos

  • A função em vigor deve ter o privilégio USAGE no warehouse.

  • Se nenhum warehouse padrão for definido e esse cabeçalho for omitido, as chamadas dependentes de warehouse falharão.

Exemplo

O exemplo a seguir cria um procedimento Python que usa o warehouse BUILD_WH. A função especificada deve ter o privilégio USAGE no warehouse. O procedimento PYTHON_WH_TEST criado retorna o nome do warehouse ativo.

Você pode especificar o valor do cabeçalho X-Snowflake-Warehouse entre aspas duplas ou sem aspas.

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
Linguagem: Português