Ritiro dell'API Looker 3.x

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

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

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

Come annunciato nel giugno 2022, sia l'API 3.1 che l'API 3.0, denominate 3.x, sono in stato di ritiro. Le versioni 3.x dell'API verranno disattivate a partire dalla release della versione 23.14 di Looker 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 per utilizzare gli endpoint API 4.0 anziché gli endpoint API 3.x prima del 14 agosto 2023. Dopo questa modifica, tutte le funzionalità che si basano sugli endpoint 3.x smetteranno di funzionare.

Se la tua istanza è self-hosted, 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 sarà semplice per la maggior parte dei clienti.

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

Cronologia

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

A chi è rivolto questo articolo?

Questo documento è rivolto a te se utilizzi l'API Looker tramite SDK supportati da Looker, SDK supportati dalla community o l'API stessa. Continua a leggere per scoprire le modifiche che provocano un errore che potrebbero influire sulla tua applicazione e

Cosa devo fare?

Dovrai apportare le seguenti modifiche al codice. Questi sono descritti in maggiore dettaglio più avanti in questa pagina.

  • Modifica il codice in modo che rimandi alla nuova API.
  • Identifica l'utilizzo degli endpoint rimossi e sostituisci i riferimenti con l'equivalente dell'API 4.0.
  • Aggiorna i valori ID precedentemente espressi come numeri in modo che vengano espressi come stringhe.

Dettagli della migrazione all'API 4.0

Modifica del codice in modo che rimandi 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, devi assicurarti di inizializzare la versione corretta dell'SDK. Ecco un esempio di base di come potrebbe apparire l'inizio di uno script Python utilizzando 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()

Dopo aver apportato la modifica all'API 4.0, è il momento di testare il codice e prestare attenzione alle seguenti modifiche.

Sostituzioni degli endpoint API 3.x

Per mantenere la coerenza della terminologia 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 gli endpoint "Folder" sinonimi.

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 di 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 "Homepage" sono stati rimossi. Utilizza invece gli endpoint "board" con funzionalità estese.

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 di 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 con modifiche incompatibili nell'API 4.0

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

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

Diff 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.

Disattivazione/attivazione dell'API 3.x tramite l'opzione di 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 hanno attualmente la possibilità di disattivare tutte le chiamate agli endpoint dell'API 3. In questo modo potrai eseguire test sulla tua istanza per assicurarti che nessun servizio o applicazione integrato smetta di funzionare prima della scadenza del 14 agosto. Per farlo, puoi attivare l'opzione "Nega richieste API 3.x" nel pannello di amministrazione delle funzionalità legacy.

I clienti con hosting autonomo 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 "Deny API 3.x requests" (Nega richieste API 3.x) (Nota: dopo aver eseguito il comando, dovrai comunque attivare l'opzione nel riquadro Funzionalità legacy nell'interfaccia utente di Looker per interrompere le chiamate API 3):

export FF_DENY_API3=true

Domande frequenti

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

A partire da Looker 23.8, la colonna Origine nel riquadro Amministrazione > Query ora mostra correttamente la versione dell'API (v3 o v4) per le query avviate dall'API Looker. Non includerà informazioni sulle attività di amministrazione o sviluppo, come la creazione di utenti o le attività di sviluppo LookML/Git.

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

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

Se la tua istanza è in hosting autonomo, dovrai apportare le modifiche prima di eseguire l'upgrade alla release di agosto 2023 (versione 23.14) o a qualsiasi release successiva. Ti consigliamo di iniziare questa attività il prima possibile, in modo da poter continuare a utilizzare una release supportata per un'esperienza ottimale con Looker.

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

Dovrai apportare le modifiche prima che venga eseguito l'upgrade della tua istanza alla release di agosto 2023 (versione 23.14) o a qualsiasi release successiva. Ti consigliamo di iniziare a svolgere questo lavoro il prima possibile, in modo da non avere poco tempo a disposizione quando è previsto l'upgrade della tua istanza.

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

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