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 com o status descontinuado. 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.

Esse upgrade vai 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 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 vão deixar de funcionar após essa mudança.

Se a instância for auto-hospedada, faça 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 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á 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 isto?

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ê precisará fazer as seguintes alterações no seu código. Eles são descritos em mais detalhes abaixo. - Altere seu 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 a versão correta do SDK está sendo inicializada. Veja um exemplo básico de como o início de um script Python pode ficar usando 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 na API 4.0, é hora de testar seu código e observar as alterações mencionadas abaixo.

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:

Os endpoints de "espaço" foram renomeados. Em vez disso, use endpoints de "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\"}"

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

Exemplo de SDK para 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 atualizados (23.0 ou mais recente) para garantir que os tipos dos aplicativos estejam corretos 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 APIs Explorer 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 a alternância de recursos legados

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 interrompido 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 deixar a opçã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 de API 3.x sendo feitas na minha instância. Como encontro essa informação?

A partir do Looker 23.8, a coluna "Origem" no painel "Administrador > Consultas" 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. 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-hospedada, faça as mudanças antes do upgrade para a versão 23.14 de agosto de 2023 (23.14) ou qualquer versão posterior. 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 está hospedada pelo Looker, mas está 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.