Visão geral das especificações do aplicativo¶

Types of controlled access for Snowflake Native Apps¶

Snowflake Native Apps often need to interact with resources beyond the consumer’s Snowflake account. These interactions can include connecting to external services, authenticating with third-party providers, or sharing data with other Snowflake accounts.

To access external services and share data, Snowflake provides the following objects:

Integrações de acesso externo:

permitem acesso seguro a pontos de extremidade de rede externa dentro de uma função definida pelo usuário ou procedimento armazenado. Integrações de acesso externo usam regras de rede para restringir o acesso a locais de rede externos específicos.

Integrações de segurança:

Permitir acesso seguro a provedores de autenticação de terceiros, como OAuth. As integrações de segurança fornecem autenticação e controle de acesso.

Shares and listings:

Allow apps to share data back to providers or third-party Snowflake accounts. Shares contain database objects to be shared, and listings provide the mechanism to share data across accounts and regions.

When using automated granting of privileges, an app has the required privileges to create these objects when running the setup script. However, because these objects enable external connections or data sharing, consumers must approve these operations when configuring the app.

Usar a concessão automatizada de privilégios com especificações de aplicativo oferece os seguintes benefícios:

• Consumers do not have to manually create integrations, shares, or listings required by the app and approve access to them using references.

• Os provedores não precisam escrever um código que verifique a existência dos privilégios e objetos necessários durante a instalação ou atualização.

• Consumers have clear visibility and control over external connections and data sharing requests.

Use app specifications for consumer approval¶

App specifications allow you to specify what controlled access the app requires. After the consumer installs the app, they review the app specification and approve or decline each request as necessary. This includes requests for external connections, authentication integrations, and data sharing permissions.

• For information about using app specifications to request access to external endpoint access, see Solicitação de integrações de acesso externo (EAIs) com especificações do aplicativo.

• For information about using app specifications to request access to OAuth integrations, see Solicitação de integrações de segurança com especificações de aplicativos.

• For information about using app specifications to share data through listings, see Request data sharing with app specifications.

Definição da especificação de aplicativo¶

An app specification definition contains the properties that are required for the app to perform controlled operations such as external connections or data sharing. These properties are displayed to the consumer for approval. The app specification definition contains a subset of the metadata and properties specific to each type of operation: external access integration, security integration, or listing.

Para informações sobre a definição da especificação do aplicativo para integrações de segurança, consulte Definição da especificação de aplicativo para integrações de segurança.

Para informações sobre a definição da especificação do aplicativo para integrações de acesso externo, consulte App specification definition for an EAI.

For information about the app specification definition for listings, see Create an app specification for a listing.

Sequence numbers of an app specification¶

O número sequencial é semelhante a um número de versão para a especificação de aplicativo. Os números sequenciais são incrementados automaticamente quando um provedor altera a definição da especificação de aplicativo. A definição de uma especificação de aplicativo inclui detalhes de configuração e outras informações necessárias. Os campos que não fazem parte da definição, como description, não acionam uma atualização para o número sequencial.

Os números sequenciais permitem que provedores e consumidores identifiquem diferentes versões de uma especificação do aplicativo. Por exemplo, se um provedor adicionar um novo detalhe de configuração às especificações do aplicativo, o número de sequência será incrementado. Quando o consumidor visualiza a especificação do aplicativo, ele pode ver que o número de sequência foi alterado e pode revisar a especificação atualizada do aplicativo.

Práticas recomendadas ao usar especificações de aplicativos¶

Automated granting of privileges ensures that the app has the required privileges to create objects like external access integrations, security integrations, or listings. However, consumers can choose to decline the app specification that enables external connections or data sharing. When developing an app, you must account for situations where app specifications might not be approved.

Consider the following scenarios:

• An app might request multiple network ports for an external access integration, but the consumer might allow only one. The app should include logic to handle errors that occur if a network port is not available.

• A data sharing request might be declined or only partially approved for some target accounts but not others. The app should gracefully handle these cases.

• Authentication integrations might be rejected, requiring the app to use alternative methods.

As a best practice, always include proper error handling and provide clear feedback to consumers about which features require approved specifications to function.

Uso de funções de retorno de chamada com especificações de aplicativo¶

In some contexts, an app might need to know when the consumer has approved or declined an app specification. For example:

• The app might need to wait until an external access specification is approved before making API calls.

• Data population might need to start only after a listing specification is approved.

• OAuth flows might need to be initialized after security integration approval.

Para lidar com essa situação, o Snowflake Native App Framework fornece um mecanismo que permite ao provedor definir um procedimento armazenado de retorno de chamada que é executado quando o consumidor aprova ou recusa uma especificação de aplicativo.

Os provedores podem adicionar um procedimento armazenado ao arquivo de manifesto, conforme mostrado no exemplo a seguir:

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

This example shows how to add a stored procedure named callbacks.on_spec_update to the manifest file. In the setup script, providers can add a stored procedure as shown in the following example:

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
  ...

This example shows the signature of a stored procedure called callbacks.on_spec_update. You include the code in the body of this procedure to check the status of the app specification, create objects, and perform actions as required.