Descontinuação da API Looker 3.x

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

Já havíamos comunicado que essa mudança aconteceria na versão de julho de 2023. Com base no feedback dos clientes, mudamos esse prazo para agosto de 2023, para facilitar essa transição. Feche esta caixa de diálogo para mais detalhes.

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

No anúncio de descontinuação em junho de 2022, as APIs 3.1 e 3.0, chamadas de 3.x, estão obsoletas. 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 nas instâncias hospedadas pelo Looker durante as horas de manutenção entre 14 e 24 de agosto. Por isso, todas as instâncias hospedadas pelo Looker vão precisar fazer upgrade dos aplicativos para usar endpoints de API 4.0 em vez de 3.x antes de 14 de agosto de 2023. Todas as funcionalidades que dependem de endpoints 3.x deixarão de funcionar após essa mudança.

Se a instância for auto-hospedada, faça o upgrade dos aplicativos antes de fazer o upgrade da 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 precisam entrar em contato com o suporte do Looker.

Cronograma

  • Antes de 2022: a API 3.0 está em status descontinuado, a 3.1 está em status estável e a 4.0 está em status Beta.
  • Março de 2022: a API 4.0 entra no status estável e tem disponibilidade 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 usando SDKs com suporte do Looker, SDKs com suporte da comunidade ou a própria API. Continue lendo para saber mais sobre alterações interruptivas que podem afetar seu aplicativo e aprenda

O que eu preciso fazer?

Você vai precisar fazer as seguintes mudanças no código. Eles são descritos em mais detalhes posteriormente 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 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

Ao fazer chamadas de API diretamente pela linha de comando ou por programas como o Postman, você precisa ajustar o URL que 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 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 alteração na API 4.0, é hora de testar seu código e observar as seguintes alterações.

Substituições de endpoint da API 3.x

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

"Espaço" endpoints foram renomeados. Use endpoints "Pasta" sinônimos.

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

"Página inicial" endpoints foram removidos. Usar "quadro" com funcionalidade expandida endpoints.

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\"}"

Detalhamento dos tipos de campos de ID da API 4.0

A API 4.0 atualizou os tipos de alguns campos de ID de números a strings. Use nossa ferramenta de diferença de referência da API para determinar quais campos de ID foram alterados entre as versões 3.1 e 4.0. Use SDKs de linguagem com suporte do Looker (versão 23.0 ou mais recente) e atualizados para garantir que os aplicativos tenham o 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 devem pesquisar no código as referências a esses campos para garantir que sejam tratados adequadamente.

Diferenças da API 4.0

Além das diretrizes listadas 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 4.0.

Como desativar/ativar a API 3.x usando o Legacy Feature Toggle

Para clientes hospedados pelo 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 vai permitir que você faça testes na sua instância para garantir que nenhum serviço ou aplicativo integrado seja corrompido antes do prazo de 14 de agosto. Para isso, ative a opção "Negar solicitações da API 3.x" no painel do administrador de recursos legados.

Os clientes auto-hospedados que usam o Looker 23.6, 23.8, 23.10 e 23.12 podem executar o seguinte comando shell antes de iniciar o Looker para adicionar uma variável de ambiente que vai fazer as "solicitações da API Deny 3.x" Alternar visível. Observação: depois de executar o comando, você ainda vai ter que alternar 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 sei se há chamadas da API 3.x sendo feitas na minha instância. Como encontro essa informação?

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

Nosso serviço interno de relatórios tem informações mais detalhadas sobre solicitações de API, incluindo aquelas usadas para concluir tarefas de desenvolvimento do LookML e Admin. 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ê vai 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 subsequente. Recomendamos que você comece a fazer esse trabalho o mais rápido possível para que possa permanecer em uma versão compatível 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?

Faça as mudanças antes do upgrade da instância para a versão 23.14 de agosto de 2023 (23.14) ou qualquer versão posterior. Recomendamos que você comece a fazer isso o quanto antes para não perder tempo quando sua instância estiver programada para receber esse 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.