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 posticipato questa scadenza ad agosto 2023 per semplificare la transizione. Chiudi questa finestra di dialogo per ulteriori dettagli.

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

A partire dal nostro annuncio di ritiro di giugno 2022, sia l'API 3.1 sia l'API 3.0, indicate come 3.x, sono in stato di ritiro. Le versioni dell'API 3.x verranno disabilitate a partire dal rilascio 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 applicazioni per utilizzare gli endpoint API 4.0 anziché quelli 3.x prima del 14 agosto 2023. Qualsiasi funzionalità che si basa sugli endpoint 3.x cesserà di funzionare dopo questa modifica.

Se l'istanza è ospitata autonomamente, 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 interamente 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 la migrazione all'API 4.0 devono contattare l'assistenza Looker.

Cronologia

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

Per chi è pensata questa pagina?

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 potrebbero interessare la tua applicazione e come

Che cosa devo fare?

Dovrai apportare le seguenti modifiche al codice. Questi aspetti 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 questi riferimenti con l'equivalente dell'API 4.0.
  • Aggiorna i valori ID che erano espressi in precedenza come numeri da indicare come stringhe.

Dettagli della migrazione dell'API 4.0

Modificare il codice in modo che indichi la 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. Di seguito è riportato un esempio 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()

Una volta apportata la modifica all'API 4.0, occorre testare il codice e verificare le modifiche riportate di seguito.

Sostituzione di endpoint API 3.x

Per 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:

"Spazio" sono stati rinominati. Utilizza gli endpoint "Cartella" 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\"}"

"Home page" sono stati rimossi. Utilizza invece gli endpoint "board" con funzionalità espanse.

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 di interruzione dell'API 4.0

L'API 4.0 ha aggiornato i tipi di alcuni campi ID da numeri a stringhe. Utilizza il nostro strumento diff di riferimento API per stabilire quali campi ID sono stati modificati tra la versione 3.1 e la versione 4.0. Utilizza SDK del linguaggio supportati da Looker (23.0 e versioni successive) per assicurarti che il tipo delle applicazioni sia corretto durante e dopo la migrazione. La maggior parte degli SDK per linguaggi supportati dalla community, tra cui Kotlin, Swift, R, C# e Go, funziona già anche 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.

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 l'opzione di attivazione/disattivazione delle funzionalità legacy

Per i clienti in cui Looker è ospitato e 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 testare l'istanza per assicurarti che le applicazioni o i servizi integrati non vengano interrotti prima della scadenza del 14 agosto. Per farlo, puoi attivare l'opzione "Rifiuta le richieste dell'API 3.x" nel pannello Amministrazione delle funzionalità precedenti.

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 renda visibile l'opzione di attivazione/disattivazione "Rifiuta le richieste API 3.x" (nota: dopo aver eseguito il comando, dovrai comunque attivare l'opzione di attivazione/disattivazione nel riquadro Funzionalità precedenti 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. Dove posso trovare queste informazioni?

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

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

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

Se l'istanza è ospitata autonomamente, 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 a eseguire questa operazione il prima possibile, in modo da poter mantenere una release supportata per un'esperienza ottimale con Looker.

La mia istanza è ospitata su Looker, ma 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 perdere tempo quando l'istanza è in programma per ricevere l'upgrade.

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