Abandon de l'API Looker 3.x

L'API 3.x sera désactivée en août 2023

Nous avions précédemment annoncé que ce changement interviendrait dans la version de juillet 2023. Suite aux commentaires de nos clients, nous avons repoussé cette date limite à août 2023 afin de faciliter la transition. Fermez cette boîte de dialogue pour en savoir plus.

Suite à la disponibilité générale de l'API 4.0 dans Looker 22.4, nous avons annoncé l'abandon de l'API 3.1, en plus de l'API 3.0 déjà obsolète.

Depuis l'annonce de l'abandon en juin 2022, les API 3.1 et 3.0, appelées 3.x, sont obsolètes. Les versions 3.x de l'API seront désactivées à partir de la sortie de la version 23.14 de Looker en août 2023.

Cette mise à niveau sera déployée sur les instances hébergées par Looker pendant les heures de maintenance, entre le 14 et le 24 août. Par conséquent, toutes les instances hébergées par Looker doivent mettre à niveau leurs applications pour utiliser les points de terminaison de l'API 4.0 au lieu de ceux de l'API 3.x avant le 14 août 2023. Toutes les fonctionnalités qui s'appuient sur les points de terminaison 3.x cesseront de fonctionner après ce changement.

Si votre instance est auto-hébergée, vous devez mettre à niveau vos applications avant de mettre à niveau votre instance Looker vers la version 23.14 ou une version ultérieure.

L'API 4.0 couvre entièrement les fonctionnalités proposées par les API obsolètes, et nous pensons que la mise à niveau de la version 3.x vers la version 4.0 sera simple pour la plupart des clients.

Les clients qui ne parviennent pas à migrer vers l'API 4.0 doivent contacter l'assistance Looker.

Chronologie

  • Avant 2022 : l'API 3.0 est obsolète, la version 3.1 est stable et la version 4.0 est en version bêta.
  • Mars 2022 : l'API 4.0 passe à l'état stable et est en disponibilité générale dans Looker 22.4.
  • Juin 2022 : annonce de l'abandon de l'API 3.1
  • Août 2023 : l'API 3.x sera désactivée dans Looker.

À qui s'adresse ce document ?

Ce document s'adresse à vous si vous utilisez l'API Looker via des SDK compatibles avec Looker, des SDK compatibles avec la communauté ou l'API elle-même. Poursuivez la lecture pour en savoir plus sur les modifications destructives susceptibles d'affecter votre application et découvrir

Que dois-je faire ?

Vous devrez apporter les modifications suivantes à votre code. Ces options sont décrites plus en détail plus loin sur cette page.

  • Modifiez votre code pour qu'il pointe vers la nouvelle API.
  • Identifiez l'utilisation des points de terminaison supprimés et remplacez ces références par l'équivalent de l'API 4.0.
  • Mettez à jour les valeurs d'ID qui étaient auparavant exprimées sous forme de nombres pour qu'elles soient exprimées sous forme de chaînes.

Détails de la migration vers l'API 4.0

Modifier votre code pour qu'il pointe vers la nouvelle API

Lorsque vous effectuez des appels d'API directement via la ligne de commande ou des programmes comme Postman, vous devez ajuster l'URL que vous utilisez pour effectuer la requête.

### 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

Si vous utilisez l'un de nos SDK, vous devez vous assurer que vous initialisez la bonne version du SDK. Voici un exemple de base de ce à quoi pourrait ressembler le début d'un script Python utilisant notre SDK dans les deux versions :

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

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

Une fois que vous avez effectué la modification pour l'API 4.0, vous devez tester votre code et vérifier les modifications suivantes.

Remplacements de points de terminaison de l'API 3.x

Afin de maintenir la cohérence de la terminologie entre l'API Looker et l'interface utilisateur de Looker, l'API 4.0 remplace quelques points de terminaison d'API 3.x obsolètes par des points de terminaison équivalents ou améliorés, listés ci-dessous :

Les points de terminaison "Space" ont été renommés. Utilisez plutôt les points de terminaison "Folder" synonymes.

Exemple de 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"
      )
    )

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

Les points de terminaison "Homepage" ont été supprimés. Utilisez plutôt les points de terminaison "board" aux fonctionnalités étendues.

Exemple de 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"
      )
    )

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

Types de champs d'ID non compatibles avec l'API 4.0

L'API 4.0 a modifié les types de certains champs d'ID, qui sont passés de nombres à des chaînes. Utilisez notre outil de comparaison de la documentation de référence de l'API pour déterminer quels champs d'ID ont changé entre les versions 3.1 et 4.0. Utilisez des SDK de langage compatibles avec Looker à jour (version 23.0 ou ultérieure) pour vous assurer que vos applications sont correctement typées pendant et après la migration. La plupart des SDK de langages compatibles avec la communauté, y compris Kotlin, Swift, R, C# et Go, fonctionnent déjà avec les types mis à jour.

Les développeurs qui utilisent des bibliothèques personnalisées doivent rechercher dans leur code les références à ces champs pour s'assurer qu'ils sont gérés de manière appropriée.

Différences de l'API 4.0

En plus des consignes listées sur cette page de documentation, l'API Explorer de Looker fournit une liste complète de toutes les différences entre les API 3.x et l'API 4.0.

Désactiver/Activer l'API 3.x via l'option "Ancienne fonctionnalité"

Pour les clients hébergés par Looker qui utilisent Looker 23.6, 23.8, 23.10 et 23.12, les administrateurs peuvent actuellement désactiver tous les appels aux points de terminaison de l'API 3. Cela vous permettra de tester votre instance pour vous assurer qu'aucun service ni aucune application intégrés ne seront interrompus avant la date limite du 14 août. Pour ce faire, vous pouvez activer l'option "Refuser les requêtes API 3.x" dans le panneau d'administration des anciennes fonctionnalités.

Les clients auto-hébergés utilisant Looker 23.6, 23.8, 23.10 et 23.12 peuvent exécuter la commande shell suivante avant de démarrer Looker pour ajouter une variable d'environnement qui rendra visible le bouton "Refuser les requêtes API 3.x" (Remarque : Après avoir exécuté la commande, vous devrez toujours activer le bouton dans le panneau "Anciennes fonctionnalités" de l'interface utilisateur de Looker pour arrêter les appels d'API 3) :

export FF_DENY_API3=true

Questions fréquentes

Je ne sais pas si des appels d'API 3.x sont effectués sur mon instance. Comment trouver ces informations ?

Depuis Looker 23.8, la colonne "Source" du panneau "Admin" > "Requêtes" affiche correctement la version de l'API (v3 ou v4) pour les requêtes lancées à partir de l'API Looker. Cela n'inclut pas les informations sur les tâches d'administration ou de développement, telles que la création d'utilisateurs ou les tâches de développement LookML/Git.

Notre service de reporting interne fournit des informations plus détaillées sur les requêtes API, y compris celles utilisées pour effectuer des tâches d'administration et de développement LookML. Les clients dont les instances suivent la configuration réseau recommandée peuvent contacter l'assistance Looker pour demander l'exportation de ces données.

J'héberge ma propre instance. Dois-je effectuer la mise à niveau d'ici le 14 août 2023 ?

Si votre instance est auto-hébergée, vous devrez effectuer les modifications avant de passer à la version d'août 2023 (version 23.14) ou à une version ultérieure. Nous vous recommandons de commencer à effectuer ce travail dès que possible afin de pouvoir continuer à utiliser une version compatible et de bénéficier de la meilleure expérience possible avec Looker.

Mon instance est hébergée par Looker, mais elle fait partie du programme ESR. Dois-je effectuer la mise à niveau d'ici le 14 août 2023 ?

Vous devrez effectuer les modifications avant que votre instance ne soit mise à niveau vers la version d'août 2023 (version 23.14) ou une version ultérieure. Nous vous recommandons de commencer à effectuer ce travail dès que possible, afin de ne pas être pressé par le temps lorsque votre instance sera programmée pour recevoir cette mise à niveau.

J'ai lu la documentation, mais je rencontre toujours des problèmes ou je ne sais pas comment procéder.

Les clients qui ne parviennent pas à migrer vers l'API 4.0 doivent contacter l'assistance Looker.