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 o prazo para agosto de 2023 para facilitar a transição. Feche esta caixa de diálogo para mais detalhes.

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

Desde o 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. Como resultado, todas as instâncias hospedadas no Looker precisam atualizar os aplicativos para usar endpoints da API 4.0 em vez dos endpoints da API 3.x antes de 14 de agosto de 2023. Todas as funcionalidades que dependem de endpoints 3.x vão 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 a maioria dos clientes faça a transição da versão 3.x para a 4.0 de forma simples.

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

Cronograma

  • Antes de 2022: a API 3.0 está descontinuada, a 3.1 está estável e a 4.0 está na versão Beta
  • Março de 2022: a API 4.0 entra no status estável e fica disponível em geral no Looker 22.4
  • Junho de 2022: anúncio da descontinuação da API 3.1
  • Agosto de 2023: a API 3.x será desativada no Looker

Quem deve ler este artigo?

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

O que eu preciso fazer?

Você precisará fazer as seguintes mudanças no 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.
  • Os valores de ID que antes eram expressos como números agora são 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 que você está usando 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. Confira um exemplo básico de como o início de um script em Python pode ficar 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 observar as seguintes mudanças.

Substituição de endpoints da API 3.x

Para manter a consistência da terminologia entre a API 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. Use endpoints "Pasta" 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. Use os endpoints "painel" da 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 que serão descontinuados na 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 a versão 3.1 e a 4.0. Use SDKs de linguagem com suporte do Looker atualizados (23.0+ ou mais recentes) para garantir que seus 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, já funcionam com os tipos atualizados.

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

Diferenças da API 4.0

Além das diretrizes listadas nesta página de documentação, o API Explorer do Looker oferece 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 Legacy Feature Toggle

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

Os clientes auto-hospedos que usam o Looker 23.6, 23.8, 23.10 e 23.12 podem executar o comando do shell a seguir 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 legadas" na interface do Looker para interromper as chamadas da API 3.

export FF_DENY_API3=true

Perguntas frequentes

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

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

Nosso serviço de relatórios interno tem informações mais detalhadas sobre solicitações de API, incluindo aquelas usadas para concluir tarefas de desenvolvimento do LookML e do administrador. 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 upgrade até 14 de agosto de 2023?

Se a instância for auto-hospeda, você precisará fazer as mudanças antes de fazer upgrade 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 mais rápido possível para continuar usando uma versão com suporte e ter a melhor experiência com o Looker.

Minha instância é hospedada pelo Looker, mas no programa ESR. Preciso fazer 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 subsequente. Recomendamos que você comece a fazer esse trabalho o mais rápido possível para não ficar sem tempo quando a instância for receber a atualização.

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 devem entrar em contato com o suporte do Looker.