Suspensão de uso da API Looker 3.x

A API 3.x será desativada em agosto de 2023

Anteriormente, informamos que essa mudança aconteceria na versão de julho de 2023. Com base no feedback dos clientes, adiamos esse prazo para agosto de 2023 para facilitar a transição. Feche esta caixa de diálogo para mais detalhes.

Após o lançamento da API 4.0 GA no Looker 22.4, anunciamos a descontinuação da API 3.1, além da API 3.0, que já foi descontinuada.

Conforme nosso anúncio de descontinuação em junho de 2022, as APIs 3.1 e 3.0, chamadas de 3.x, estão descontinuadas. As versões 3.x da API serão desativadas a partir do lançamento da versão 23.14 do Looker em agosto de 2023.

Esse upgrade será lançado para instâncias hospedadas pelo Looker durante o horário de manutenção entre 14 e 24 de agosto. Por isso, todas as instâncias hospedadas pelo Looker precisam fazer upgrade dos aplicativos para usar os endpoints de API 4.0 em vez dos endpoints de API 3.x antes de 14 de agosto de 2023. Qualquer funcionalidade que dependa de endpoints 3.x vai deixar de funcionar após essa mudança.

Se a instância for auto-hospedada, faça upgrade dos aplicativos antes de atualizar a instância do Looker para a versão 23.14 ou mais recente.

A API 4.0 abrange totalmente a funcionalidade oferecida pelas APIs descontinuadas, e esperamos que o upgrade da versão 3.x para a 4.0 seja simples para a maioria dos clientes.

Os clientes que não conseguirem migrar para a API 4.0 precisam entrar em contato com o suporte do Looker.

Cronograma

  • Antes de 2022: a API 3.0 está no status descontinuado, a 3.1 está no status estável e a 4.0 está no status Beta.
  • Março de 2022: a API 4.0 entra em status estável e está em disponibilidade geral no Looker 22.4
  • Junho de 2022: a descontinuação da API 3.1 é anunciada
  • Agosto de 2023: a API 3.x será desativada no Looker

Quem deve ler este documento?

Este documento é para você se usa a API Looker por meio de SDKs compatíveis com o Looker, SDKs compatíveis com a comunidade ou a própria API. Continue lendo para saber mais sobre as alterações interruptivas que podem afetar seu aplicativo e aprender

O que eu preciso fazer?

Você precisará fazer as seguintes mudanças no seu código. Eles são descritos em mais detalhes mais adiante nesta página.

  • Mude o código para apontar para a nova API.
  • Identifique o uso de endpoints removidos e substitua essas referências pelo equivalente da API 4.0.
  • Atualize os valores de ID que antes eram expressos como números para que sejam expressos como strings.

Detalhes da migração da API 4.0

Como mudar o código para apontar para a nova API

Ao fazer chamadas de API diretamente pela linha de comando ou por programas como o Postman, é necessário ajustar o URL usado para fazer a solicitação.

### API 3.1 ###
GET https://myinstance.looker.com/api/3.1/users/5877

### API 4.0 ###
GET https://myinstance.looker.com/api/4.0/users/5877

Se você estiver usando um dos nossos SDKs, verifique se está inicializando a versão correta dele. Confira um exemplo básico de como o início de um script em Python pode ser usando nosso SDK nas duas versões:

### API 3.1 ###
import looker_sdk
sdk = looker_sdk.init31()

### API 4.0 ###
import looker_sdk
sdk = looker_sdk.init40()

Depois de fazer a mudança para a API 4.0, é hora de testar o código e ficar de olho nas mudanças a seguir.

Substituições de endpoints da API 3.x

Para manter a consistência da terminologia entre a API Looker e a interface do Looker, a API 4.0 substitui alguns endpoints descontinuados da API 3.x por endpoints equivalentes ou aprimorados, listados abaixo:

Os endpoints "Space" foram renomeados. Em vez disso, use os endpoints "Folder" sinônimos.

Exemplo do SDK do Python

    #####################
    ##### API 3 #########
    #####################

    # Create Folder in Shared Folders
    response = sdk.create_space(
      body=mdls.CreateSpace(
        name="My New Folder",
        parent_id="1"
      )
    )

    # Get Folder info by ID
    response = sdk.space(space_id="555")

    # Change name of existing Folder
    response = sdk.update_space(
      space_id="555",
      body=mdls.UpdateSpace(
        name="My Updated Folder"
      )
    )

    #####################
    ##### API 4 #########
    #####################

    # Create Folder in Shared Folders
    response = sdk.create_folder(
      body=mdls.CreateFolder(
        name="My New Folder",
        parent_id="1"
      )
    )

    # Get Folder info by ID
    response = sdk.folder(folder_id="555")

    # Change name of existing Folder
    response = sdk.update_folder(
      space_id="555",
      body=mdls.UpdateFolder(
        name="My Updated Folder"
      )
    )
    

Exemplo de cURL

    #####################
    ##### API 3 #########
    #####################

    # Get Folder info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/spaces/555

    # Change name of existing Folder
    curl -X PATCH https://myinstance.looker.com/api/3.1/spaces/555 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"name\": \"My Updated Space\"}"

    #####################
    ##### API 4 #########
    #####################

    # Get Folder info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/folders/555

    # Change name of existing Folder
    curl -X PATCH https://myinstance.looker.com/api/4.0/folders/555 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"name\": \"My Updated Space\"}"
    

Os endpoints "Página inicial" foram removidos. Em vez disso, use os endpoints de "quadro" com funcionalidade expandida.

Exemplo do SDK do Python

    #####################
    ##### API 3 #########
    #####################

    # Get Board info by ID
    response = sdk.homepage(homepage_id=1348)

    # Update displayed title of Board item
    response = sdk.update_homepage_item(
      homepage_item_id=86,
      body=mdls.WriteHomepageItem(
        custom_title="Volume 3"
      )
    )

    #####################
    ##### API 4 #########
    #####################

    # Get Board info by ID
    response = sdk.board(board_id=1348)

    # Update displayed title of Board item
    response = sdk.update_board_item(
      board_item_id=86,
      body=mdls.WriteBoardItem(
        custom_title="Volume 3"
      )
    )
    

Exemplo de cURL

    #####################
    ##### API 3 #########
    #####################

    # Get Board info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/homepages/1348

    # Update displayed title of Board item
    curl -X PATCH https://myinstance.looker.com/api/3.1/homepage_items/86 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"custom_title\": \"Volume 3\"}"

    #####################
    ##### API 4 #########
    #####################

    # Get Board info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/boards/1348

    # Update displayed title of Board item
    curl -X PATCH https://myinstance.looker.com/api/4.0/boards/86 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"custom_title\": \"Volume 3\"}"
    

Tipos de campo de ID incompatíveis da API 4.0

A API 4.0 atualizou os tipos de alguns campos de ID de números para strings. Use nossa ferramenta de comparação de referência da API para determinar quais campos de ID mudaram entre as versões 3.1 e 4.0. Use SDKs de linguagem compatíveis com o Looker atualizados (23.0+) para garantir que os aplicativos sejam do tipo correto durante e após a migração. A maioria dos SDKs de linguagem com suporte da comunidade, incluindo Kotlin, Swift, R, C# e Go, também já funciona com os tipos atualizados.

Os desenvolvedores que usam bibliotecas personalizadas precisam pesquisar no código as referências a esses campos para garantir que eles sejam processados corretamente.

Diferenças da API 4.0

Além das diretrizes listadas nesta página de documentação, o APIs Explorer do Looker fornece uma lista completa de todas as diferenças entre as APIs 3.x e 4.0.

Como desativar/ativar a API 3.x usando o botão de alternância de recursos legados

Para clientes hospedados pelo Looker que usam as versões 23.6, 23.8, 23.10 e 23.12, os administradores podem desativar todas as chamadas para endpoints da API 3. Isso vai permitir que você faça testes na sua instância para garantir que nenhum serviço ou aplicativo integrado seja interrompido antes do prazo de 14 de agosto. Para isso, ative a opção "Negar solicitações da API 3.x" no painel de admin de recursos legados.

Os clientes autohospedados que usam o Looker 23.6, 23.8, 23.10 e 23.12 podem executar o seguinte comando do shell antes de iniciar o Looker para adicionar uma variável de ambiente que vai tornar o botão "Negar solicitações da API 3.x" visível. Observação: depois de executar o comando, você ainda vai precisar ativar o botão no painel "Recursos legados" na interface do Looker para interromper as chamadas da API 3:

export FF_DENY_API3=true

Perguntas frequentes

Não tenho certeza se há chamadas da API 3.x sendo feitas na minha instância. Como posso encontrar essas informações?

A partir do Looker 23.8, a coluna "Origem" no painel "Administrador > Consultas" agora exibe corretamente a versão da API (v3 ou v4) para consultas iniciadas na API Looker. Isso não inclui informações sobre tarefas de administrador ou desenvolvedor, como criar usuários ou tarefas de desenvolvimento do LookML/Git.

Nosso serviço de relatórios internos tem informações mais detalhadas sobre as solicitações de API, incluindo aquelas usadas para concluir tarefas de desenvolvimento de administrador e LookML. Os clientes com instâncias que seguem a configuração de rede recomendada podem entrar em contato com o suporte do Looker para solicitar uma exportação desses dados.

Eu hospedo minha própria instância. Preciso fazer o upgrade até 14 de agosto de 2023?

Se a instância for auto-hospedada, você precisará fazer as mudanças antes de atualizar para a versão de agosto de 2023 (versão 23.14) ou qualquer versão posterior. Recomendamos que você comece a fazer isso o quanto antes para continuar usando uma versão compatível e ter a melhor experiência com o Looker.

Minha instância é hospedada pelo Looker, mas está no programa ESR. Preciso fazer o upgrade até 14 de agosto de 2023?

Você precisa fazer as mudanças antes que sua instância seja atualizada para a versão de agosto de 2023 (versão 23.14) ou qualquer versão posterior. Recomendamos que você comece a fazer isso o quanto antes para não ficar sem tempo quando sua instância estiver programada para receber o upgrade.

Li a documentação, mas ainda estou com problemas ou não sei como proceder.

Os clientes que não conseguirem migrar para a API 4.0 precisam entrar em contato com o suporte do Looker.