Esta página foi traduzida pela API Cloud Translation.

Extensões de mosaicos de edifícios

A partir do Looker 24.0, as extensões podem ser desenvolvidas para serem executadas num mosaico nos painéis de controlo. As extensões que suportam a execução como um mosaico ou uma visualização podem ser adicionadas enquanto o painel de controlo está no modo de edição ou guardadas num painel de controlo como uma visualização a partir de uma exploração. As extensões também podem ser configuradas como mosaicos em painéis de controlo do LookML.

Estão disponíveis exemplos de extensões que podem ser usadas como mosaicos de painéis de controlo:

A extensão de visualização de mosaicos mostra como criar uma visualização personalizada através da estrutura de extensão.
A extensão do SDK de mosaicos mostra os métodos da API disponíveis específicos das extensões de mosaicos.

Usar o SDK de extensões do Looker com extensões de mosaicos

As extensões de mosaicos requerem que o parâmetro mount_points seja definido no ficheiro de manifesto do projeto do LookML para que as extensões sejam carregadas como mosaicos num painel de controlo. Existem dois tipos de mount_points relacionados com extensões de mosaicos:

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }

dashboard_vis — Quando ativada, a extensão é apresentada nas opções de visualização de uma análise detalhada, onde pode ser selecionada como uma visualização e guardada como um mosaico do painel de controlo. Quando o painel de controlo é executado, executa a consulta associada ao mosaico e disponibiliza os dados à extensão. Isto é semelhante ao funcionamento das visualizações personalizadas. A principal diferença entre uma visualização personalizada e uma extensão executada num mosaico do painel de controlo com a opção dashboard_vis ativada é que a extensão pode fazer chamadas à API Looker.
dashboard_tile: quando ativada, a extensão é apresentada no painel Extensões, que é apresentado quando um utilizador está a editar um painel de controlo e seleciona a opção Extensões depois de clicar no botão Adicionar. Este tipo de extensão é responsável por obter os seus próprios dados, em vez de a consulta de mosaicos fornecer automaticamente dados à extensão.

Um ponto de montagem adicional, standalone, faz com que a extensão apareça na secção Aplicações do menu principal do Looker. É possível que uma extensão tenha vários pontos de montagem definidos. Em tempo de execução, a extensão é notificada sobre a forma como está montada e pode ajustar o respetivo comportamento em conformidade. Por exemplo, as extensões de standalone podem ter de definir a sua própria altura, ao passo que as extensões de mosaicos não o fazem.

APIs adicionais de extensão de mosaicos

As extensões de mosaicos são fornecidas com APIs e dados adicionais no tempo de execução. Estes são obtidos a partir do contexto da extensão:

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)

tileSDK: fornece funções específicas do mosaico para permitir que a extensão interaja com o anfitrião do painel de controlo do Looker. Por exemplo, para permitir que a extensão apresente e limpe mensagens de erro.
tileHostData — Fornece dados de mosaicos à extensão. Os dados são atualizados automaticamente com base nas interações com o painel de controlo de alojamento. Um exemplo é o indicador isDashboardEditing.
visualizationSDK: fornece funções específicas de visualização para permitir que a extensão interaja com o anfitrião do painel de controlo do Looker. Um exemplo é a função updateRowLimit.
visualizationData — Fornece dados de visualização à extensão. Os dados são atualizados automaticamente com base nas interações com o painel de controlo de alojamento. Os dados são semelhantes aos dados fornecidos às visualizações personalizadas.

Criar extensões reativas

Os iFrames em que as extensões são executadas são redimensionados automaticamente à medida que a janela do anfitrião do Looker principal é redimensionada. Isto reflete-se automaticamente na janela de conteúdo do iFrame. O componente iframe não tem nenhum preenchimento nem margem, pelo que cabe à extensão fornecer o seu próprio preenchimento e margem para que tenha um aspeto consistente com a aplicação Looker. No caso das extensões autónomas, cabe à extensão controlar a altura da extensão. Para extensões executadas em mosaicos do painel de controlo ou visualizações de exploração, a janela de conteúdo do iFrame é automaticamente definida para a altura disponibilizada pelo iFrame.

Considerações sobre a renderização

É importante ter em atenção que as extensões de mosaicos são renderizadas quando um painel de controlo é transferido como PDF ou imagem. O renderizador espera que o mosaico o notifique quando a renderização estiver concluída. Se não o fizer, o renderizador deixa de responder. Segue-se um exemplo de como notificar o renderizador de que o mosaico foi renderizado.

  const { extensionSDK } = useContext(ExtensionContext40)

  useEffect(() => {
    extensionSDK.rendered()
  }, [])

As animações também devem ser desativadas durante a renderização. Segue-se um exemplo em que as configurações de animação estão desativadas durante a renderização:

  const { lookerHostData} = useContext(ExtensionContext40)
  const isRendering = lookerHostData?.isRendering

  const config = isRendering
    ? {
        ...visConfig,
        valueCountUp: false,
        waveAnimateTime: 0,
        waveRiseTime: 0,
        waveAnimate: false,
        waveRise: false,
      }
    : visConfig

  if (mountPoint === MountPoint.dashboardVisualization) {
    return <VisualizationTile config={config} />
  }

Funções e propriedades do SDK de mosaicos

O SDK de mosaicos fornece funções que permitem a uma extensão de mosaicos interagir com o respetivo painel de controlo de alojamento.

As funções e as propriedades disponíveis são apresentadas na tabela seguinte:

Função ou propriedade	Descrição
`tileHostData` (propriedade)	Alojamento de dados específicos da extensão de mosaico. Consulte a secção Dados do Tile SDK para ver detalhes.
`addError`	Quando é chamado, o painel de controlo ou a funcionalidade Explorar apresenta uma mensagem de erro abaixo da visualização.
`clearError`	Quando é chamado, o painel de controlo ou o elemento Explorar oculta qualquer mensagem de erro apresentada abaixo da visualização.
`openDrillMenu`	Para extensões de visualização, esta chamada abre um menu de detalhe. Esta chamada é ignorada se a extensão não for uma visualização de extensão de mosaico.
`runDashboard`	Executa o painel de controlo atual. Esta chamada é ignorada por uma extensão de visualização de mosaicos em execução num Explore.
`stopDashboard`	Para um painel de controlo em execução. Esta chamada é ignorada por uma extensão de visualização de mosaicos em execução num Explore.
`updateFilters`	Atualiza os filtros no painel de controlo atual ou em Explorar.
`openScheduleDialog`	Abre a caixa de diálogo de agendamento. Esta chamada é ignorada quando executada numa análise detalhada.
`toggleCrossFilter`	Ativa/desativa filtros cruzados. Esta chamada é ignorada quando executada numa análise detalhada.

Dados do SDK de mosaicos

As propriedades de dados do SDK de mosaicos disponíveis são apresentadas na tabela seguinte:

Propriedade	Descrição
`isExploring`	Quando é verdadeiro, indica que o mosaico está a ser configurado como uma visualização numa análise detalhada.
`dashboardId`	O ID do painel de controlo do mosaico que está a ser renderizado. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida.
`elementId`	O ID do elemento do mosaico que está a ser renderizado. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida.
`queryId`	O ID da consulta do mosaico que está a ser renderizado, se estiver associado a uma visualização. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida. O `queryId` é o ID da consulta criada quando a visualização é incorporada no Looker Explore. Não contém filtros nem filtragem cruzada a aplicar ao painel de controlo. Para refletir os dados apresentados no `QueryResponse`, é necessário aplicar filtros e filtros cruzados, bem como gerar uma nova consulta. Como resultado, pode haver mais propriedades úteis do que `queryId`. Consulte `filteredQuery` para ver um objeto de consulta com filtros aplicados.
`querySlug`	A consulta slug do mosaico que está a ser renderizado se estiver associado a uma visualização. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida. O `querySlug` é um slug da consulta que é criado quando a visualização é incorporada no Looker Explore. Não contém filtros nem filtragem cruzada aplicados ao painel de controlo. Para refletir os dados apresentados no `QueryResponse`, é necessário aplicar filtros e filtros cruzados, bem como gerar uma nova consulta. Como resultado, pode haver mais propriedades úteis do que `querySlug`. Consulte `filteredQuery` para ver um objeto de consulta com filtros aplicados.
`dashboardFilters`	Os filtros que estão a ser aplicados ao painel de controlo. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida.
`dashboardRunState`	Indica se o painel de controlo está em execução. Se o mosaico estiver a ser configurado como uma exploração, o estado é `UNKNOWN`. Por motivos de desempenho do painel de controlo, o runstate pode nunca ser apresentado como em execução. Geralmente, isto acontece se não existirem outros mosaicos associados a uma consulta, incluindo o mosaico ao qual a extensão está associada. Se a extensão precisar de saber com certeza que um painel de controlo foi executado, a deteção de diferenças no `lastRunStartTime` é a forma fiável.
`isDashboardEditing`	Quando é verdadeiro, o painel de controlo está a ser editado. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida.
`isDashboardCrossFilteringEnabled`	Quando é verdadeiro, a filtragem cruzada está ativada no painel de controlo. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida.
`filteredQuery`	Um objeto de consulta que corresponde ao ID da consulta associado ao elemento do painel de controlo subjacente que aplica todos os filtros do painel de controlo e alterações de fuso horário feitas ao nível do painel de controlo.
`lastRunSourceElementId`	O ID do elemento de extensão de mosaico que acionou a última execução do painel de controlo. O ID não está definido se a execução do painel de controlo tiver sido acionada pelo botão Executar do painel de controlo ou pela atualização automática, ou se a execução tiver sido acionada através do SDK de incorporação. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida. Tenha em atenção que o `lastRunSourceElementId` pode ser igual ao ID do elemento da instância da extensão atual. Por exemplo, se a extensão acionar uma execução do painel de controlo, recebe uma notificação quando a execução do painel de controlo é iniciada e concluída.
`lastRunStartTime`	Indica a hora de início da última execução do painel de controlo. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida. Tenha em atenção que as horas de início e fim comunicadas não devem ser usadas para captar métricas de desempenho.
`lastRunEndTime`	Indica a hora de fim da última execução do painel de controlo. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida. Se o mosaico estiver em execução, esta propriedade não é preenchida. Tenha em atenção que as horas de início e fim comunicadas não devem ser usadas para captar métricas de desempenho.
`lastRunSuccess`	Indica se a última execução do painel de controlo foi bem-sucedida ou não. Se o mosaico estiver a ser configurado como uma análise detalhada, esta propriedade não é preenchida. Se o mosaico estiver em execução, esta propriedade não é preenchida.

Funções e propriedades do SDK de visualização

As funções e as propriedades do SDK de visualização disponíveis são apresentadas na tabela seguinte:

Função ou propriedade	Descrição
`visualizationData` (propriedade)	Visualização (combinação de dados de `visConfig` e `queryResponse`).
`visConfig` (propriedade)	Dados de configuração da visualização: Configurações de medição Configurações de dimensões Cálculos da tabela Configurações de tabela dinâmica Configurações de visualização Estas são usadas para personalizar o aspeto e a funcionalidade de uma visualização numa exploração.
`queryResponse` (propriedade)	Dados de resposta da consulta
`configureVisualization`	Define a configuração predefinida para uma visualização de extensão. A configuração é renderizada no editor de visualização da ferramenta Explorar. Esta função só deve ser chamada uma vez.
`setVisConfig`	Atualiza a configuração da visualização.
`updateRowLimit`	Atualiza o limite de linhas da consulta.

Dados do SDK de visualização

O SDK de visualização é composto pelo seguinte:

Dados de configuração da visualização
Dados de resposta à consulta

Dados de configuração da visualização

Propriedade	Descrição
`queryFieldMeasures`	Informações de medição
`queryFieldDimensions`	Informações da dimensão
`queryFieldTableCalculations`	Informações do cálculo da tabela
`queryFieldPivots`	Informações de mudança de direção
`visConfig`	Dados de configuração visual. Esta configuração deve ser unida à configuração predefinida e aplicada à visualização renderizada pela extensão.

export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Dados de resposta à consulta

Propriedade	Descrição
`data`	Matriz de dados de linhas
`fieldMeasures`	Informações de medição de campo.
`fieldDimensions`	Informações da dimensão do campo.
`fieldTableCalculations`	Informações sobre os cálculos da tabela de campos.
`fieldPivots`	Informações de rotação de campos.
`fieldMeasureLike`	Uma matriz concatenada de informações de medidas de campos e cálculos de tabelas que se comportam como medidas.
`fieldDimensionLike`	Uma matriz concatenada de informações de dimensões de campos e cálculos de tabelas que se comportam como dimensões.

Usar o SDK Embed

A utilização do SDK incorporado numa extensão de mosaico não é recomendada pelos seguintes motivos:

É possível que a extensão acabe por renderizar um painel de controlo no qual a extensão é um mosaico. A estrutura de extensões não tem forma de detetar esta situação e, como resultado, o navegador pode falhar.
A renderização de PDF de conteúdo incorporado numa extensão de mosaico não funciona.