Descontinuação da API Looker 3.x

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

Anteriormente, comunicámos que esta alteração iria ocorrer no lançamento de julho de 2023. Com base no feedback dos clientes, alterámos este prazo para agosto de 2023 para ajudar a tornar esta transição mais simples. Feche esta caixa de diálogo para ver mais detalhes.

Após o nosso lançamento da DG da API 4.0 no Looker 22.4, anunciámos a descontinuação da nossa API 3.1, além da API 3.0 já descontinuada.

Desde o nosso anúncio de descontinuação em junho de 2022, a API 3.1 e a API 3.0, referidas como 3.x, estão no estado de descontinuação. As versões 3.x da API vão ser desativadas a partir do lançamento da versão 23.14 do Looker em agosto de 2023.

Esta atualização vai ser implementada nas instâncias alojadas no Looker durante o período de manutenção, entre 14 e 24 de agosto. Como resultado, todas as instâncias alojadas no Looker têm de atualizar as respetivas aplicações para usar pontos finais da API 4.0 em vez de pontos finais da API 3.x antes de 14 de agosto de 2023. Qualquer funcionalidade que dependa de pontos finais 3.x vai deixar de funcionar após esta alteração.

Se a sua instância for autoalojada, tem de atualizar as suas aplicações antes de atualizar a instância do Looker para a versão 23.14 ou posterior.

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

Os clientes que não conseguirem migrar com êxito para a API 4.0 devem contactar o apoio técnico do Looker.

Linha cronológica

  • Antes de 2022: a API 3.0 está no estado descontinuado, a 3.1 está no estado estável e a 4.0 está no estado beta
  • Março de 2022: a API 4.0 entra no estado estável e está geralmente disponível no Looker 22.4
  • Junho de 2022: é anunciada a descontinuação da API 3.1
  • Agosto de 2023: a API 3.x vai ser desativada no Looker

Quem deve ler isto?

Este documento destina-se a si se usar a API Looker através de SDKs suportados pelo Looker, SDKs suportados pela comunidade ou a própria API. Continue a ler para saber mais sobre as alterações interruptivas que podem afetar a sua aplicação e

O que necessito de fazer?

Tem de fazer as seguintes alterações ao seu código. Estas opções são descritas mais detalhadamente mais adiante nesta página.

  • Altere o código para apontar para a nova API.
  • Identifique a utilização de pontos finais removidos e substitua essas referências pelo equivalente da API 4.0.
  • Atualizar os valores de ID que foram expressos anteriormente como números para serem expressos como strings.

Detalhes da migração da API 4.0

Alterar o código para apontar para a nova API

Quando faz chamadas API diretamente através da linha de comandos ou de programas como o Postman, tem de ajustar o URL que está a usar para fazer o pedido.

### 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 estiver a usar um dos nossos SDKs, tem de se certificar de que está a inicializar a versão correta do SDK. Segue-se um exemplo básico de como o início de um script Python pode ser apresentado com o nosso SDK em ambas as 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 alteração à API 4.0, é altura de testar o seu código e procurar as seguintes alterações.

Substituições de pontos finais da API 3.x

Para manter a terminologia consistente entre a API Looker e a IU do Looker, a API 4.0 substitui alguns pontos finais da API 3.x descontinuados por pontos finais equivalentes ou melhorados, indicados abaixo:

Os pontos finais "Space" foram renomeados. Em alternativa, use os pontos finais "Folder" sinónimos.

Exemplo do SDK 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 pontos finais "Homepage" foram removidos. Em alternativa, use os pontos finais "board" com funcionalidade expandida.

Exemplo do SDK 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\"}"

API 4.0: tipos de campos de ID com alterações significativas

A API 4.0 atualizou os tipos de alguns campos de ID de números para strings. Use a nossa ferramenta de comparação de referências da API para determinar que campos de ID foram alterados entre a versão 3.1 e a 4.0. Use SDKs de linguagem suportados pelo Looker atualizados (23.0 ou superior) para garantir que as suas aplicações têm o tipo correto durante e após a migração. A maioria dos SDKs de idiomas suportados pela comunidade, incluindo Kotlin, Swift, R, C# e Go, também já funciona com os tipos atualizados.

Os programadores que usam bibliotecas personalizadas devem pesquisar no respetivo código referências a estes campos para garantir que são processados adequadamente.

Diferença da API 4.0

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

Desativar/ativar a API 3.x através da ativação/desativação de funcionalidades antigas

Para clientes alojados no Looker que usam o Looker 23.6, 23.8, 23.10 e 23.12, os administradores têm atualmente a capacidade de desativar todas as chamadas para os pontos finais da API 3. Isto permite-lhe fazer testes na sua instância para garantir que nenhum serviço ou aplicação integrada é interrompido antes do prazo de 14 de agosto. Para o fazer, pode ativar a opção "Recusar pedidos da API 3.x" no painel de administração de funcionalidades antigas.

Os clientes autoalojados que usam o Looker 23.6, 23.8, 23.10 e 23.12 podem executar o seguinte comando de shell antes de iniciar o Looker para adicionar uma variável de ambiente que tornará visível o botão "Recusar pedidos da API 3.x" (nota: depois de executar o comando, ainda tem de ativar/desativar o botão no painel Funcionalidades antigas na IU do Looker para parar as chamadas da API 3):

export FF_DENY_API3=true

Perguntas frequentes

Não tenho a certeza se estão a ser feitas chamadas da API 3.x na minha instância. Como posso encontrar estas informações?

A partir do Looker 23.8, a coluna Origem no painel Administração > Consultas apresenta agora corretamente a versão da API (v3 ou v4) para consultas iniciadas a partir da API Looker. Isto não inclui informações sobre tarefas de administrador ou programador, como a criação de utilizadores ou o desenvolvimento de LookML/tarefas do Git.

O nosso serviço de relatórios interno tem informações mais detalhadas sobre os pedidos de API, incluindo os usados para concluir tarefas de administração e desenvolvimento de LookML. Os clientes com instâncias que seguem a configuração de rede recomendada podem contactar o apoio técnico do Looker para pedir uma exportação destes dados.

A minha instância está alojada por mim. Tenho de fazer a atualização até 14 de agosto de 2023?

Se a sua instância for autoalojada, tem de fazer as alterações antes de atualizar para a versão de agosto de 2023 (versão 23.14) ou qualquer versão subsequente. Recomendamos que comece a fazer este trabalho assim que possível para poder manter-se numa versão suportada e ter a melhor experiência com o Looker.

A minha instância está alojada no Looker, mas no programa ESR. Tenho de fazer a atualização até 14 de agosto de 2023?

Tem de fazer as alterações antes de a sua instância ser atualizada para a versão de agosto de 2023 (versão 23.14) ou qualquer versão subsequente. Recomendamos que comece este trabalho assim que possível para não ter pressa quando a sua instância estiver agendada para receber essa atualização.

Li a documentação, mas continuo a ter problemas ou não sei como proceder.

Os clientes que não conseguirem migrar com êxito para a API 4.0 devem contactar o apoio técnico do Looker.