Verificação da configuração de catálogo REST¶

Etapa 1: recuperação de um token de acesso¶

Use um comando curl para recuperar um token de acesso de seu catálogo. O exemplo a seguir solicita um token de acesso no 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

Onde:

• https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens é o ponto de extremidade para recuperar um token OAuth (getToken).

• scope é o mesmo valor que você especifica para o parâmetro OAUTH_ALLOWED_SCOPES ao criar uma integração de catálogo. Para vários escopos, use um espaço como separador.

• my_client_id é o mesmo ID de cliente que você especifica para o parâmetro OAUTH_CLIENT_ID ao criar uma integração de catálogo.

• my_client_secret é o mesmo segredo de cliente que você especifica para o parâmetro OAUTH_CLIENT_SECRET ao criar uma integração de catálogo.

Exemplo de valor de retorno:

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

Etapa 2: verifique as permissões do token de acesso¶

Usando o token de acesso recuperado na etapa anterior, verifique se você tem permissão para acessar o servidor de catálogo.

É possível usar o comando curl para listar as definições de configuração de seu catálogo:

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

Onde:

• ?warehouse=warehouse especifica opcionalmente o nome do warehouse a ser solicitado de seu catálogo (se compatível). Para Snowflake Open Catalog, o nome do warehouse é o nome do catálogo.

• ACCESS_TOKEN é uma variável que contém o access_token recuperado na etapa anterior.

Exemplo de valor de retorno:

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

Etapa 3: carregamento de uma tabela do catálogo¶

Você também pode fazer uma solicitação GET para carregar uma tabela. O Snowflake usa a operação loadTable para carregar dados de tabela de seu catálogo 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

Onde:

• prefix especifica opcionalmente o prefixo obtido da resposta anterior de getConfig.

• namespace é o namespace da tabela que você deseja recuperar. Se o namespace estiver aninhado, use o separador %1F; por exemplo, parentNamespace%1FchildNamespace.

• table é o nome da tabela.

Etapa 1: verificação das permissões do token de acesso¶

Use um comando curl para verificar se você tem permissão para acessar o servidor de catálogo:

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

Onde:

• https://xx123xx.us-west-2.aws.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens é o ponto de extremidade para recuperar um token OAuth (getToken).

• ?warehouse=warehouse especifica opcionalmente o nome do warehouse a ser solicitado de seu catálogo (se compatível).

• BEARER_TOKEN é uma variável que contém o access_token recuperado na etapa anterior.

Exemplo de valor de retorno:

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

Etapa 2: carregamento de uma tabela do catálogo¶

Você também pode fazer uma solicitação GET para carregar uma tabela. O Snowflake usa a operação loadTable para carregar dados de tabela de seu catálogo 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

Onde:

• prefix especifica opcionalmente o prefixo obtido da resposta anterior de getConfig.

• namespace é o namespace da tabela que você deseja recuperar. Se o namespace estiver aninhado, use o separador %1F; por exemplo, parentNamespace%1FchildNamespace.

• table é o nome da tabela.

Etapa 1: adicione seu usuário à relação de confiança da função IAM¶

Ao criar uma integração de catálogo REST para SigV4, o Snowflake provisiona um usuário AWS IAM para sua conta Snowflake. Você adiciona esse usuário do Snowflake IAM à relação de confiança para uma função IAM com permissão para acessar os recursos do API Gateway.

Para testar a configuração, você pode assumir a função de usuário em sua conta AWS após adicionar o usuário AWS ao documento de política de confiança da função. Para recuperar o ARN de seu usuário IAM atual, use o comando sts get-caller-identity para a interface de linha de comando (CLI) AWS :

aws sts get-caller-identity

Exemplo de saída:

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

O documento de política de confiança atualizado deve incluir o ARN do usuário Snowflake e o ARN do usuário da seguinte forma:

{
  "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"
        }
      }
    }
  ]
}

Para obter instruções completas, consulte Atualização de uma política de confiança de função na documentação AWS IAM.

Etapa 2: assuma sua função IAM para obter credenciais temporárias¶

Para obter credenciais de segurança temporárias para AWS, use o comando sts assume-role para AWS CLI.

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

Onde:

• my_role_arn é o nome de recurso da Amazon (ARN) da função IAM que você configurou para o Snowflake.

• session_name é um identificador de cadeia de caracteres de sua escolha para a sessão de função assumida; por exemplo, my_rest_session.

Exemplo de saída:

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

Etapa 3: verifique se a função IAM tem as permissões corretas¶

Usando as credenciais temporárias que você recuperou na etapa anterior, verifique se a função IAM tem permissão para invocar as APIs do API Gateway.

É possível usar o comando curl para listar as definições de configuração de seu catálogo:

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"

Onde:

• 123xxxxxxx.execute-api.us-west-2.amazonaws.com é o nome de host do API Gateway.

• test_v2 é o nome do estágio em que seu API foi implementado.

• v1/config especifica a operação getConfig da definição OpenAPI do catálogo Iceberg.

• ?warehouse=warehouse especifica opcionalmente o nome do warehouse a ser solicitado de seu catálogo (se compatível).

• $AWS_ACCESS_KEY_ID é uma variável que contém o AccessKeyId que você recuperou usando o comando sts assume-role.

• $AWS_SECRET_ACCESS_KEY é uma variável que contém o SecretAccessKey que você recuperou usando o comando sts assume-role.

• aws:amz:us-west-2:execute-api é o nome de assinatura do protocolo SigV4. Para AWS Glue, use aws:amz:us-west-2:glue.

• $AWS_SESSION_TOKEN é uma variável que contém o SessionToken que você recuperou usando o comando sts assume-role.

Exemplo de valor de retorno:

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

Você também pode fazer uma solicitação GET para carregar uma tabela. O Snowflake usa a operação loadTable para carregar dados de tabela de seu catálogo 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"

Onde:

• prefix especifica opcionalmente o prefixo obtido da resposta anterior de getConfig.

• namespace é o namespace da tabela que você deseja recuperar. Se o namespace estiver aninhado, use o separador %1F; por exemplo, parentNamespace%1FchildNamespace.

• table é o nome da tabela.

API privada

Para uma API privada, é possível especificar o ponto de extremidade da VPC e o nome de host privado do Amazon API Gateway nos mesmos comandos curl.

Por exemplo:

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"

Onde:

• https://vpce-xxxxxxxxxxxxxxxxxxxxxxxxxx.execute-api.us-west-2.vpce.amazonaws.com/... é o nome de host de seu ponto de extremidade de VPC.

• abc1defgh2.execute-api.us-west-2.amazonaws.com é o nome de host de sua API privada no Amazon API Gateway.