Procedimentos armazenados para manutenção diária

Introdução

O Snowflake Connector for Google Analytics Aggregate Data fornece vários procedimentos armazenados que permitem gerenciar programaticamente a ingestão de dados e a configuração do conector. Abaixo estão detalhes sobre cada procedimento armazenado, incluindo seu uso, parâmetros e exemplos.

Configuração de um novo relatório

O procedimento CONFIGURE_REPORT configura um novo relatório para ingestão de dados do Google Analytics 4 (GA4) no Snowflake. Esse procedimento usa os parâmetros do relatório como entrada, incluindo dimensões, métricas e cronograma de ingestão.

CALL CONFIGURE_REPORT( <report_name>, <property_id>, <dimensions>, <metrics>, <start_date>, <refresh_interval>[, <keep_empty_rows>][, <avoid_sampling>]);
Copy

Onde:

report_name

Uma cadeia de caracteres que especifica o nome do relatório a ser configurado. Esse nome será usado como prefixo para as tabelas com dados brutos criadas no banco de dados de destino. Após a ingestão inicial, o nome do relatório será usado para as exibições criadas no banco de dados de destino. Obrigatório.

O nome do relatório deve:

  • começar com uma letra (maiúscula ou minúscula) ou um sublinhado.

  • continuar com um ou mais caracteres que podem ser letras (maiúsculas ou minúsculas), dígitos ou sublinhados.

  • ter 150 caracteres ou menos.

property_id

Uma cadeia de caracteres que especifica o ID da propriedade do Google Analytics 4 a ser usado para o relatório. O ID da propriedade é um número que pode ser obtido da conta do GA4. Certifique-se de que o PROPERTY_ID corresponde a uma propriedade do GA4 que possa ser acessada pelo método de autenticação dos conectores (oauth2 ou conta de serviço). Obrigatório.

dimensions

Uma lista separada por vírgulas com as dimensões do GA4 a serem incluídas no relatório. As dimensões devem ser separadas por vírgulas. Se a dimensão date não for especificada de forma explícita, ela será adicionada automaticamente. No máximo nove dimensões podem ser especificadas (incluindo date). Obrigatório.

Exemplo: 'country,city,deviceCategory,sessions'

metrics

Uma lista separada por vírgulas com métricas do GA4 a serem incluídas no relatório. É necessária pelo menos uma métrica, e é possível ter no máximo dez métricas. Obrigatório.

Exemplo: 'sessions,pageViews'.

start_date

Uma cadeia de caracteres que especifica a data de início do relatório. A data deve estar no formato YYYY-MM-DD. Os dados a partir dessa data serão ingeridos. Obrigatório.

refresh_interval

Uma cadeia de caracteres que especifica o intervalo de atualização do relatório. Obrigatório. O intervalo deve ter um dos seguintes formatos:

  • 'EVERY <número de minutos> MINUTE'

  • 'EVERY <número de horas> HOUR'

  • 'EVERY <número de dias> DAY'

keep_empty_rows

Opcional. O valor padrão é false. Se true, a tabela de saída incluirá registros com combinações de dimensões em que todas as métricas são zero. Serve para analisar combinações de dimensões sem eventos.

avoid_sampling

Opcional. O valor padrão é false. Se true, o conector poderá ajustar a maneira de buscar os dados da API GA4 para tentar evitar a amostragem de dados. Pode melhorar a precisão dos dados, mas também aumentar a frequência de chamadas da API.

Nota

Não há garantia de que os dados não serão amostrados. O conector tentará evitar a amostragem, mas talvez isso não seja possível em todos os casos. Isso se deve às limitações da API GA4.

Exemplo:

CALL CONFIGURE_REPORT(
    REPORT_NAME => 'USER_ENGAGEMENT_REPORT',
    PROPERTY_ID => '123456789',
    DIMENSIONS => 'country,deviceCategory',
    METRICS => 'activeUsers,newUsers',
    START_DATE => '2023-01-01',
    REFRESH_INTERVAL => 'EVERY 1 DAY',
    KEEP_EMPTY_ROWS => TRUE,
    AVOID_SAMPLING => TRUE
);
Copy

Remoção de relatório existente

O procedimento DELETE_REPORT exclui a configuração de um relatório existente do conector, interrompendo qualquer outra ingestão de dados desse relatório. Os dados que já foram ingeridos não serão removidos.

CALL DELETE_REPORT( <report_name> );
Copy

Onde:

report_name

Uma cadeia de caracteres que especifica o nome do relatório a ser excluído. Deve corresponder ao REPORT_NAME usado em CONFIGURE_REPORT. Obrigatório.

Exemplo:

CALL DELETE_REPORT('USER_ENGAGEMENT_REPORT');
Copy

Listagem de propriedades da conta do Google Analytics 4

O procedimento GET_PROPERTIES retorna uma lista com todas as propriedades do Google Analytics 4 disponíveis para serem ingeridas pelo conector.

CALL GET_PROPERTIES();
Copy

Exemplo de saída do procedimento:

{[
  { "propertyName": "test1", "propertyId": "1" },
  { "propertyName": "test2", "propertyId": "2" },
  { "propertyName": "test3", "propertyId": "3" }
]}
Copy

Nota

O conector deve ter as permissões necessárias para acessar as propriedades. Se um resultado estiver vazio, verifique os direitos de acesso no GA4.

Busca de dimensões e métricas para uma propriedade doGA4

O procedimento GET_DIMENSIONS_AND_METRICS recupera a lista de dimensões e métricas disponíveis para uma determinada propriedade do GA4.

CALL GET_DIMENSIONS_AND_METRICS( <property_id> );
Copy

Onde:

property_id

Uma cadeia de caracteres que especifica o ID da propriedade do Google Analytics 4 a ser usado para o relatório. O ID da propriedade é um número que pode ser obtido da conta do GA4. Certifique-se de que o property_id corresponde a uma propriedade do GA4 que possa ser acessada pelo método de autenticação dos conectores (oauth2 ou conta de serviço). Obrigatório.

Exemplo:

CALL GET_DIMENSIONS_AND_METRICS('123456789');
Copy

Exemplo de saída do procedimento:

{
  "dimensions": [
    {
      "dimension": "achievementId", "category": "Other", "description": "Some description."
    }
  ],
  "metrics": [
    {
      "metric": "active1DayUsers", "category": "User", "description": "Some description."
    },
    {
      "metric": "active28DayUsers", "category": "User", "description": "Some description."
    }
  ]
}
Copy

Nota

As dimensões e métricas disponíveis para cada propriedade podem variar.

Pausa do conector

O procedimento PAUSE_CONNECTOR pausa o conector, interrompendo toda a ingestão e o processamento de dados.

CALL PAUSE_CONNECTOR();
Copy

Nota

  • A pausa do conector interrompe a ingestão de dados de todos os relatórios configurados.

  • A ingestão de dados pode ser retomada usando RESUME_CONNECTOR.

  • Os dados existentes permanecem acessíveis durante a pausa.

Retomada do conector

O procedimento RESUME_CONNECTOR retoma o conector, iniciando toda a ingestão e o processamento de dados que foram pausados anteriormente. A ingestão de dados continuará do ponto em que parou.

CALL RESUME_CONNECTOR();
Copy

Ingestão sob demanda

O procedimento INGEST_NOW agenda a ingestão de dados para o relatório especificado no conector. Esse procedimento pode ser usado para iniciar manualmente a ingestão de dados para um relatório específico fora dos intervalos programados.

Nota

O procedimento agenda a ingestão imediata para o relatório especificado usando EXECUTE TASK .... Isso significa que a ingestão começará o mais rápido possível, mas pode não ser instantânea, especialmente se o mesmo relatório já estiver sendo ingerido. Certifique-se de que o conector não esteja pausado antes de chamar esse procedimento.

CALL INGEST_NOW('<report_name>');
Copy

Onde:

report_name

Uma cadeia de caracteres que especifica o nome do relatório a ser ingerido. Deve corresponder ao REPORT_NAME usado em CONFIGURE_REPORT. Obrigatório.

Exemplo:

CALL INGEST_NOW('USER_ENGAGEMENT_REPORT');
Copy

Como saber o status atual do conector

Nota

No contexto deste documento, o state e o status do conector são usados de forma intercambiável. O status/estado do conector pode ser recuperado usando o procedimento GET_CONNECTOR_STATUS.

CALL GET_CONNECTOR_STATUS();
Copy

Exemplo de saída do procedimento:

{
  "response_code": "OK",
  "status": "STARTED",
  "configurationStatus": "PREREQUISITES_DONE"
}
Copy

Ele retorna um objeto JSON com os seguintes campos:

  • response_code: se o procedimento foi executado com sucesso, o valor OK é retornado. Códigos de resposta diferentes de OK indicam um erro.

  • status: o status atual do conector. Esse status pode mudar somente quando você re/instalar, pausar, retomar o conector ou finalizar o processo de configuração. Ele pode ter um dos seguintes valores:

    • CONFIGURING: é o estado padrão definido após a instalação do conector a partir da listagem ou pacote do aplicativo. O conector permanece nesse estado até que o processo de configuração seja finalizado. Após a finalização da configuração, o conector passa para o estado STARTED.

    • STARTED: quando o conector estiver totalmente configurado ou retomado, ele fará a transição para o estado STARTED.

    • PAUSED: quando o conector é pausado com sucesso, ele passa para o estado PAUSED.

    • ERROR: se o conector encontrar um erro irreversível, ele fará a transição para o estado ERROR, indicando que não pode ser usado ativamente. Quando estiver nesse estado, o procedimento RECOVER_CONNECTOR_STATE poderá ser usado para fazer a transição para um estado válido.

  • configurationStatus: é um substatus do status principal CONFIGURING. O processo de configuração do conector é dividido em poucas etapas que estão sendo rastreadas por esse substatus. Ele pode ter um dos seguintes valores:

    • INSTALLED: a configuração começa no estado INSTALLED após a criação da instância do conector.

    • PREREQUISITES_DONE: depois que o usuário conclui os pré-requisitos e chama o procedimento MARK_ALL_PREREQUISITES_AS_DONE, em que a configuração passa para o estado PREREQUISITES_DONE. Os pré-requisitos são etapas manuais que precisam ser executadas pelo usuário, como configurar a conexão a fontes de dados de terceiros ou criar banco de dados de destino.

    • CONFIGURED: o procedimento CONFIGURE_CONNECTOR(VARIANT) foi chamado.

    • CONNECTED: o procedimento SET_CONNECTION_CONFIGURATION(VARIANT) foi chamado.

    • FINALIZED: por fim, após completar a configuração, ela passa para o estado FINALIZED (o procedimento FINALIZE_CONNECTOR_CONFIGURATION(VARIANT) foi chamado).

Reinicialização do processo de configuração

O procedimento armazenado RESET_CONFIGURATION redefine a configuração do conector para seu estado padrão. Esse procedimento pode ser usado para redefinir a configuração do conector antes que ela seja finalizada. Para que o procedimento funcione, o conector deve ter o status CONFIGURING. Para saber mais sobre os status principais do conector e os substatus de configuração, consulte Como saber o status atual do conector.

Se a fase de configuração for concluída (FINALIZED), esse procedimento retornará um erro.

CALL RESET_CONFIGURATION();
Copy

Recuperação de um estado intermediário ou incorreto

O procedimento RECOVER_CONNECTOR_STATE serve para recuperar o conector quando ele está preso em um estado intermediário ou de erro (ERROR, STARTING, PAUSING), configurando manualmente o status para STARTED ou PAUSED. Algumas operações podem deixar o conector em um estado inconsistente por vários motivos. Por exemplo, quando o usuário descarta permissões para determinados objetos de banco de dados de que o conector precisa.

O procedimento retornará um erro se o novo estado não for válido ou se o conector não estiver em um dos estados predeterminados. As seguintes transições são permitidas:

  • ERROR -> PAUSED

  • ERROR -> STARTED

  • PAUSING -> PAUSED

  • PAUSING -> STARTED

  • STARTING -> PAUSED

  • STARTING -> STARTED

CALL RECOVER_CONNECTOR_STATE('<new_state>');
Copy

Onde:

new_state

Uma cadeia de caracteres que especifica o novo estado do conector. O estado deve ser STARTED ou PAUSED. Obrigatório.

Exemplo:

CALL RECOVER_CONNECTOR_STATE('STARTED');
Copy

Recuperação de relatórios após o descarte de um conector

O procedimento IMPORT_STATE é usado para recuperar relatórios configurados e o histórico de ingestão após a desinstalação do conector. Esse procedimento deve ser feito depois que o conector for reinstalado e o novo conector for configurado. Ele serve para usar o mesmo banco de dados que foi usado pelo conector desinstalado. O estado que está sendo importado está localizado no banco de dados de destino usado pela instância anterior do conector, na forma de tabelas com o sufixo SFSDKEXPORT. Para saber mais sobre o processo, leia o guia Recuperação em caso de desastre. O procedimento não substituirá o estado existente no conector se detectar que o estado não é novo, a menos que o parâmetro force seja definido como true. O estado novo é aquele logo após o processo de configuração ser finalizado e nenhum relatório ser configurado. Se os relatórios foram configurados, mas excluídos posteriormente, o estado também será considerado como não novo.

Nota

Esse procedimento não funciona quando o conector tiver sido desinstalado (descartado) usando a opção CASCADE.

CALL IMPORT_STATE([force]);
Copy

Onde:

force

Opcional. O valor padrão é false. Se true, o procedimento substituirá o estado existente no conector. Inclusive qualquer relatório que já tenha sido configurado. Se false, o procedimento retornará um erro se detectar que o estado não é novo.

Exemplo:

CALL IMPORT_STATE();
Copy
Linguagem: Português