Ritiro dell'API Looker 3.x

L'API 3.x verrà disabilitata ad agosto 2023

In precedenza, avevamo comunicato che questa modifica sarebbe stata apportata nella release di luglio 2023. In base al feedback dei clienti, abbiamo riportato questa scadenza ad agosto 2023 per semplificare la transizione. Chiudi questa finestra di dialogo per ulteriori dettagli.

A seguito della nostra release dell'API 4.0 GA in Looker 22.4, abbiamo annunciato il ritiro dell'API 3.1, oltre all'API 3.0, già ritirata.

A partire dal nostro annuncio sul ritiro di giugno 2022, sia l'API 3.1 sia l'API 3.0, denominata 3.x, sono in stato deprecato. Le versioni dell'API 3.x verranno disabilitate a partire dal rilascio di Looker versione 23.14 ad agosto 2023.

Questo upgrade verrà implementato nelle istanze ospitate da Looker durante gli orari di manutenzione tra il 14 e il 24 agosto. Di conseguenza, tutte le istanze ospitate da Looker devono eseguire l'upgrade delle proprie applicazioni in modo che utilizzino endpoint API 4.0 anziché endpoint API 3.x prima del 14 agosto 2023. Dopo questa modifica, tutte le funzionalità che si basano su endpoint 3.x non funzioneranno più.

Se l'istanza è in hosting autonomo, devi eseguire l'upgrade delle applicazioni prima di eseguire l'upgrade dell'istanza di Looker alla versione 23.14 o successive.

L'API 4.0 copre completamente le funzionalità offerte dalle API ritirate e prevediamo che l'upgrade dalla versione 3.x alla 4.0 sia semplice per la maggior parte dei clienti.

I clienti che non riescono a eseguire correttamente la migrazione all'API 4.0 devono contattare l'assistenza di Looker.

Cronologia

  • Prima del 2022: l'API 3.0 era in stato deprecato, la versione 3.1 era in stato stabile e la versione 4.0 era in stato beta
  • Marzo 2022: l'API 4.0 entra in stato stabile ed è in disponibilità generale in Looker 22.4
  • Giugno 2022: annuncio del ritiro dell'API 3.1
  • Agosto 2023: l'API 3.x verrà disattivata in Looker

Chi dovrebbe leggerlo?

Questo documento è rivolto a te se utilizzi l'API Looker tramite gli SDK supportati da Looker, quelli supportati dalla community o l'API stessa. Continua a leggere per scoprire di più sulle modifiche che provocano errori che potrebbero interessare la tua applicazione e scopri

Cosa devo fare?

Dovrai apportare le seguenti modifiche al codice. Questi aspetti sono descritti più dettagliatamente di seguito. - Modificare il codice in modo che punti alla nuova API - Identificare l'utilizzo degli endpoint rimossi e sostituire questi riferimenti con l'equivalente dell'API 4.0 - Aggiornare i valori degli ID precedentemente espressi come numeri da esprimere come stringhe

Dettagli sulla migrazione dell'API 4.0

Modifica del codice in modo che punti alla nuova API

Quando effettui chiamate API direttamente tramite riga di comando o programmi come Postman, devi modificare l'URL che utilizzi per effettuare la richiesta.

### 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 utilizzi uno dei nostri SDK, dovrai assicurarti di inizializzare la versione corretta dell'SDK. Ecco un esempio di base di come potrebbe apparire l'inizio di uno script Python usando il nostro SDK in entrambe le versioni:

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

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

Una volta apportata la modifica all'API 4.0, è il momento di testare il codice e controllare le modifiche indicate di seguito.

Sostituzioni di endpoint API 3.x

Al fine di mantenere la terminologia coerente tra l'API Looker e l'interfaccia utente di Looker, l'API 4.0 sostituisce alcuni endpoint dell'API 3.x deprecati con endpoint equivalenti o migliorati, elencati di seguito:

Gli endpoint "spazio" sono stati rinominati. Utilizza invece simili endpoint "Cartella".

Esempio di 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"
      )
    )

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

Gli endpoint della "home page" sono stati rimossi. Usa invece gli endpoint "board" con funzionalità espansa.

Esempio di 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"
      )
    )

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

Tipi di campi ID in violazione dell'API 4.0

L'API 4.0 ha aggiornato i tipi per alcuni campi ID da numeri a stringhe. Utilizza il nostro strumento per le differenze nei riferimenti delle API per determinare quali campi ID sono cambiati tra 3.1 e 4.0. Utilizza SDK per il linguaggio supportati da Looker (o versioni successive) aggiornati per assicurarti che le applicazioni siano corrette durante e dopo la migrazione. Anche la maggior parte degli SDK per i linguaggi supportati dalla community, inclusi Kotlin, Swift, R, C# e Go, funziona già con i tipi aggiornati.

Gli sviluppatori che usano librerie personalizzate devono cercare nel codice riferimenti a questi campi per assicurarsi che vengano gestiti in modo appropriato.

Differenza API 4.0

Oltre alle linee guida elencate in questa pagina della documentazione, Explorer API di Looker fornisce un elenco completo di tutte le differenze tra le API 3.x e l'API 4.0.

Disabilitazione/attivazione dell'API 3.x tramite attivazione/disattivazione delle funzionalità legacy

Per i clienti ospitati da Looker che utilizzano Looker 23.6, 23.8, 23.10 e 23.12, gli amministratori attualmente possono disabilitare tutte le chiamate agli endpoint API 3. In questo modo potrai eseguire test sull'istanza per assicurarti che nessun servizio o applicazione integrati vada oltre la scadenza del 14 agosto. Per farlo, puoi attivare l'opzione "Rifiuta richieste API 3.x" nel pannello di amministrazione delle funzionalità legacy.

I clienti self-hosted che utilizzano Looker 23.6, 23.8, 23.10 e 23.12 possono eseguire il seguente comando shell prima di avviare Looker per aggiungere una variabile di ambiente che renderà visibile l'opzione "Rifiuta richieste API 3.x". Nota: dopo aver eseguito il comando, dovrai comunque cambiare l'opzione di attivazione/disattivazione nel riquadro Funzionalità legacy dell'interfaccia utente di Looker 3 per interrompere l'API:

export FF_DENY_API3=true

Domande frequenti

Non so se vengono effettuate chiamate API 3.x sulla mia istanza. Come faccio a trovare queste informazioni?

A partire dalla versione 23.8, nella colonna Origine del riquadro Amministratore > Query viene ora visualizzata correttamente la versione dell'API (v3 o v4) per le query avviate dall'API Looker. Non verranno incluse informazioni sulle attività di amministrazione o sviluppatore come la creazione di utenti o le attività di sviluppo LookML/Git.

Il nostro servizio di reporting interno offre informazioni più dettagliate sulle richieste API, incluse quelle utilizzate per completare le attività di amministrazione e sviluppo LookML. I clienti con istanze che seguono la configurazione di rete consigliata possono contattare l'assistenza di Looker per richiedere un'esportazione di questi dati.

Ospito la mia istanza. Devo eseguire l'upgrade entro il 14 agosto 2023?

Se l'istanza è ospitata autonomamente, devi apportare le modifiche prima di eseguire l'upgrade alla release di agosto 2023 (23.14) o a qualsiasi release successiva. Ti consigliamo di iniziare a eseguire questa operazione il prima possibile, in modo da poter continuare a utilizzare una release supportata per avere un'esperienza ottimale con Looker.

La mia istanza è ospitata su Looker, ma si trova nel programma ESR. Devo eseguire l'upgrade entro il 14 agosto 2023?

Dovrai apportare le modifiche prima che venga eseguito l'upgrade dell'istanza alla release di agosto 2023 (versione 23.14) o a qualsiasi release successiva. Ti consigliamo di iniziare a eseguire questa operazione il prima possibile, in modo da non dover attendere il tempo necessario perché l'istanza possa ricevere l'upgrade.

Ho letto la documentazione ma continuo a riscontrare problemi o non so come procedere.

I clienti che non riescono a eseguire correttamente la migrazione all'API 4.0 devono contattare l'assistenza di Looker.