Usando a API do desenvolvedor para adicionar modelos definidos pelo consumidor¶

No fluxo tradicional do Snowflake Data Clean Rooms, um provedor usa a API do desenvolvedor para criar modelos personalizados e, em seguida, os adiciona à sala limpa que o provedor compartilha com um consumidor. O consumidor então usa esse modelo para executar análises na sala limpa.

Em alguns casos, o consumidor deseja poder criar seu próprio modelo personalizado para controlar o tipo de análise que pode ser executada na sala limpa. Nesse cenário, o provedor ainda cria e compartilha a sala limpa, mas o consumidor define um modelo dentro dessa sala limpa. Como se trata de uma sala limpa, o provedor deve permitir explicitamente que esse modelo definido pelo consumidor seja adicionado à sala limpa.

A capacidade de adicionar um modelo definido pelo consumidor à sala limpa de um provedor geralmente é necessária em uma sala limpa com vários provedores, onde o consumidor está executando análises de dados de mais de um provedor ao mesmo tempo. Nesse ambiente, o consumidor pode estar na melhor posição para saber como extrair insights de dados provenientes de diversas partes e pode usar a API do desenvolvedor para criar um modelo personalizado para fazer isso. Com modelos definidos pelo consumidor em um ambiente de vários provedores, cada provedor deve aprovar o modelo antes que ele possa ser usado. Para um exemplo mais detalhado mostrando como usar uma sala limpa com vários provedores, consulte Snowflake Data Clean Rooms: salas limpas de múltiplos provedores.

Fluxo de trabalho básico para modelos definidos pelo consumidor¶

O processo de usar a API do desenvolvedor para adicionar modelos definidos pelo consumidor à sala limpa de um provedor envolve ações coordenadas tanto pelo consumidor quanto pelo provedor. Este fluxo de trabalho básico é:

Consumidor:

Envia uma solicitação ao provedor da sala limpa para que um modelo personalizado seja adicionado. Esta solicitação inclui a definição do modelo, que é escrito na linguagem de modelos Jinja.

Provedor:

Verifica novas solicitações de consumidores que desejam adicionar modelos à sala limpa.
Após revisar a definição do modelo, aprova ou rejeita a solicitação.

Consumidor:

Verifica se a solicitação foi aprovada. O consumidor pode consultar o status da solicitação a qualquer momento.

Envio de solicitações a um provedor¶

Um consumidor executa o comando consumer.create_template_request para enviar uma solicitação ao provedor de uma sala limpa. Esta solicitação inclui o nome do modelo junto com o código Jinja que define o modelo.

Por exemplo, suponha que o provedor compartilhou uma sala limpa dcr_cleanroom com um consumidor. O consumidor deseja adicionar um modelo nomeado à sala limpa my_overlap_analysis. Para enviar uma solicitação ao provedor da sala limpa, o consumidor executa o seguinte comando:

CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom',
  'my_analysis',
  $$
  SELECT
      identifier({{ dimensions[0] | column_policy }})
  FROM
      identifier({{ my_table[0] }}) c
    INNER JOIN
      identifier({{ source_table[0] }}) p
        ON
          c.identifier({{ consumer_id  }}) = identifier({{ provider_id | join_policy }})
       {% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
  $$);

Copy

O terceiro argumento é o código Jinja que define o modelo.

Para obter documentação de referência para o comando consumer.create_template_request, consulte a seção Modelos definidos pelo consumidor em Snowflake Data Clean Rooms: Guia de referência da API do consumidor.

Verificação se há novas solicitações dos consumidores¶

Para verificar novas solicitações de consumidores, um provedor executa o comando provider.list_template_requests e analisa os resultados para identificar solicitações com status PENDING. Um status PENDING indica que o consumidor enviou uma nova solicitação à qual o provedor ainda não tomou ação. A resposta a provider.list_template_requests inclui o código Jinja do modelo, que permite ao provedor decidir se deseja aprovar ou rejeitar a solicitação.

Por exemplo, suponha que o nome da sala limpa do provedor seja dcr_cleanroom. Para verificar se o consumidor enviou uma nova solicitação para adicionar um modelo, o provedor executa os seguintes comandos:

CALL samooha_by_snowflake_local_db.provider.list_template_requests('dcr_cleanroom');

SELECT * FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE status = 'PENDING';

Copy

A resposta ao comando provider.list_template_requests inclui o seguinte para cada solicitação de modelo:

UUID que identifica exclusivamente a solicitação.
Conta do consumidor que enviou a solicitação, no formato do localizador de conta.
Nome do modelo, que foi especificado pelo consumidor quando ele enviou a solicitação.
Código Jinja que define o modelo.
Status da solicitação, que pode ser PENDING, APPROVED ou REJECTED.

Para obter documentação de referência para o comando provider.list_template_requests, consulte a seção Modelos definidos pelo consumidor em Snowflake Data Clean Rooms: Guia de referência da API do provedor.

Como aprovar ou rejeitar uma solicitação¶

Após receber uma solicitação para adicionar um modelo definido pelo consumidor, o provedor decide se aprova ou rejeita a solicitação.

Aprovar uma solicitação

Os provedores executam o comando provider.approve_template_request para aprovar uma solicitação para adicionar um modelo. O provedor especifica qual modelo aprovar passando o identificador da solicitação como um argumento.

CALL samooha_by_snowflake_local_db.provider.approve_template_request('dcr_cleanroom',
  '01b4d41d-0001-b572');

Copy

Rejeitar uma solicitação

Os provedores executam o comando provider.reject_template_request para rejeitar uma solicitação para adicionar um modelo. O provedor especifica qual modelo rejeitar passando o identificador da solicitação como um argumento.

Por exemplo, suponha que o nome da sala limpa do provedor seja dcr_cleanroom e a solicitação do consumidor para adicionar um modelo recebeu o identificador 01b4d41d-0001-b572. Após examinar o modelo Jinja, o provedor determina que ele introduz um risco de segurança na sala limpa, então ele quer rejeitar a solicitação com um motivo descritivo. Para rejeitar a solicitação de adição do modelo, o provedor executa o seguinte comando:

CALL samooha_by_snowflake_local_db.provider.reject_template_request('dcr_cleanroom',
  '01b4d41d-0001-b572',
  'Failed security assessment');

Copy

Para obter documentação de referência para os comandos provider.approve_template_request e provider.reject_template_request, consulte a seção Modelos definidos pelo consumidor em Snowflake Data Clean Rooms: Guia de referência da API do provedor.

Verificação do status da solicitação como consumidor¶

A qualquer momento, o consumidor pode executar o comando consumer.list_template_requests para verificar o status da sua solicitação para adicionar um modelo. O comando retorna as seguintes informações:

UUID que identifica exclusivamente a solicitação.
Conta do provedor para a qual a solicitação foi enviada, no formato do localizador de conta.
Nome do modelo, que foi especificado pelo consumidor quando ele enviou a solicitação.
Código Jinja que define o modelo.
Status da solicitação, que pode ser PENDING, APPROVED ou REJECTED.
Se a solicitação foi rejeitada, o motivo da ação do provedor.

Por exemplo, suponha que o consumidor enviou uma solicitação para adicionar um modelo à sala limpa dcr_cleanroom. Para verificar o status da solicitação e determinar se ela foi aprovada, o consumidor executa o seguinte comando:

CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');

Copy

Para obter documentação de referência para o comando consumer.list_template_requests, consulte a seção Modelos definidos pelo consumidor em Snowflake Data Clean Rooms: Guia de referência da API do consumidor.

Listagem de todas as solicitações dos consumidores¶

Um provedor executa o comando provider.list_template_requests para exibição todas as solicitações, incluindo solicitações que foram aprovadas ou rejeitadas.

Por exemplo, suponha que o nome da sala limpa do provedor seja dcr_cleanroom. Para listar todas as solicitações feitas, independentemente do resultado, o provedor executa o seguinte comando:

CALL samooha_by_snowflake_local_db.provider.list_template_requests('dcr_cleanroom');

Copy