Einstellung der Looker API 3.x

API 3.x wird im August 2023 deaktiviert.

Zuvor hatten wir angekündigt, dass diese Änderung im Juli 2023 eingeführt wird. Aufgrund des Feedbacks unserer Kunden haben wir diese Frist auf August 2023 verschoben, um die Umstellung zu erleichtern. Schließen Sie dieses Dialogfeld, um weitere Details zu sehen.

Nach der Veröffentlichung der API 4.0 GA in Looker 22.4 haben wir die Einstellung der API 3.1 angekündigt, zusätzlich zur bereits eingestellten API 3.0.

Seit der Ankündigung der Einstellung im Juni 2022 sind sowohl die 3.1-API als auch die 3.0-API, die als 3.x bezeichnet werden, im Status „Eingestellt“. Die API-Versionen 3.x werden ab der Veröffentlichung von Looker-Version 23.14 im August 2023 deaktiviert.

Dieses Upgrade wird zwischen dem 14. August und dem 24. August während der Wartungszeiten auf von Looker gehosteten Instanzen eingeführt. Daher müssen alle von Looker gehosteten Instanzen ihre Anwendungen vor dem 14. August 2023 aktualisieren, um 4.0-API-Endpunkte anstelle von 3.x-API-Endpunkten zu verwenden. Alle Funktionen, die auf 3.x-Endpunkten basieren, funktionieren nach dieser Änderung nicht mehr.

Wenn Ihre Instanz selbst gehostet wird, müssen Sie Ihre Anwendungen aktualisieren, bevor Sie Ihre Looker-Instanz auf Version 23.14 oder höher aktualisieren.

Die API 4.0 deckt die Funktionen der eingestellten APIs vollständig ab. Wir gehen davon aus, dass das Upgrade von 3.x auf 4.0 für die meisten Kunden unkompliziert ist.

Kunden, die nicht erfolgreich zur API 4.0 migrieren können, sollten sich an den Looker-Support wenden.

Zeitachse

  • Vor 2022: API 3.0 ist veraltet, 3.1 ist stabil und 4.0 ist in der Betaphase.
  • März 2022: API 4.0 erreicht den Status „Stabil“ und ist in Looker 22.4 allgemein verfügbar.
  • Juni 2022: Die Einstellung von API 3.1 wird angekündigt.
  • August 2023: API 3.x wird in Looker deaktiviert

An wen richtet sich dieser Artikel?

Dieses Dokument richtet sich an Sie, wenn Sie die Looker API über von Looker unterstützte SDKs, von der Community unterstützte SDKs oder die API selbst verwenden. Im Folgenden erfahren Sie mehr über funktionsgefährdende Änderungen, die sich auf Ihre Anwendung auswirken können, und darüber,

Was muss ich tun?

Sie müssen die folgenden Änderungen an Ihrem Code vornehmen. Diese werden weiter unten auf dieser Seite ausführlicher beschrieben.

  • Ändern Sie Ihren Code so, dass er auf die neue API verweist.
  • Ermitteln Sie die Verwendung entfernter Endpunkte und ersetzen Sie diese Verweise durch die entsprechenden API 4.0-Endpunkte.
  • Aktualisieren Sie ID-Werte, die zuvor als Zahlen angegeben wurden, sodass sie als Strings angegeben werden.

Details zur Migration auf API 4.0

Code so ändern, dass er auf die neue API verweist

Wenn Sie API-Aufrufe direkt über die Befehlszeile oder Programme wie Postman ausführen, müssen Sie die URL anpassen, die Sie für die Anfrage verwenden.

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

Wenn Sie eines unserer SDKs verwenden, müssen Sie darauf achten, dass Sie die richtige Version des SDKs initialisieren. Hier ist ein einfaches Beispiel dafür, wie der Anfang eines Python-Skripts mit unserem SDK in beiden Versionen aussehen könnte:

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

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

Nachdem Sie die Änderung an der 4.0 API vorgenommen haben, sollten Sie Ihren Code testen und auf die folgenden Änderungen achten.

Ersatz für API 3.x-Endpunkte

Damit die Terminologie zwischen der Looker API und der Looker-Benutzeroberfläche konsistent bleibt, werden in API 4.0 einige eingestellte API 3.x-Endpunkte durch gleichwertige oder verbesserte Endpunkte ersetzt, die unten aufgeführt sind:

Die Endpunkte für „Space“ wurden umbenannt. Verwenden Sie stattdessen die synonymen „Folder“-Endpunkte.

Python SDK-Beispiel

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

cURL-Beispiel

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

„Homepage“-Endpunkte wurden entfernt. Verwenden Sie stattdessen die Endpunkte für die erweiterte Funktionalität „board“.

Python SDK-Beispiel

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

cURL-Beispiel

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

API 4.0-ID-Feldtypen mit funktionsgefährdenden Änderungen

In API 4.0 wurden die Typen für einige ID-Felder von Zahlen in Strings geändert. Mit unserem Diff-Tool für die API-Referenz können Sie feststellen, welche ID-Felder sich zwischen Version 3.1 und 4.0 geändert haben. Verwenden Sie aktuelle (23.0+) von Looker unterstützte Sprach-SDKs, um sicherzustellen, dass Ihre Anwendungen während und nach der Migration typkorrekt sind. Die meisten von der Community unterstützten Sprach-SDKs, darunter Kotlin, Swift, R, C# und Go, funktionieren ebenfalls bereits mit den aktualisierten Typen.

Entwickler, die benutzerdefinierte Bibliotheken verwenden, sollten ihren Code nach Verweisen auf diese Felder durchsuchen, um sicherzustellen, dass sie richtig verarbeitet werden.

API 4.0-Vergleich

Zusätzlich zu den auf dieser Dokumentationsseite aufgeführten Richtlinien bietet der Looker API Explorer eine vollständige Liste aller Unterschiede zwischen den 3.x-APIs und der 4.0-API.

API 3.x über die Ein-/Aus-Schaltfläche für Legacy-Funktionen deaktivieren/aktivieren

Für von Looker gehostete Kunden, die Looker 23.6, 23.8, 23.10 und 23.12 verwenden, können Administratoren derzeit alle Aufrufe von API 3-Endpunkten deaktivieren. So können Sie auf Ihrer Instanz testen, ob alle integrierten Dienste oder Anwendungen vor dem 14. August funktionieren. Dazu können Sie im Admin-Bereich für Legacy-Funktionen die Option „API 3.x-Anfragen ablehnen“ aktivieren.

Kunden mit selbst gehosteten Instanzen, die Looker 23.6, 23.8, 23.10 und 23.12 verwenden, können vor dem Starten von Looker den folgenden Shell-Befehl ausführen, um eine Umgebungsvariable hinzuzufügen, die die Ein/Aus-Schaltfläche „API 3.x-Anfragen ablehnen“ sichtbar macht. (Hinweis: Nach dem Ausführen des Befehls müssen Sie die Ein/Aus-Schaltfläche im Bereich „Legacy-Funktionen“ der Looker-Benutzeroberfläche aktivieren, um API 3-Aufrufe zu beenden.)

export FF_DENY_API3=true

FAQ

Ich bin mir nicht sicher, ob auf meiner Instanz API 3.x-Aufrufe ausgeführt werden. Wo finde ich diese Informationen?

Ab Looker 23.8 wird in der Spalte „Quelle“ im Bereich „Admin“ > „Abfragen“ die API-Version (v3 oder v4) für Abfragen, die über die Looker API initiiert werden, korrekt angezeigt. Informationen zu Administrator- oder Entwickleraufgaben wie das Erstellen von Nutzern oder LookML-Entwicklungs-/Git-Aufgaben sind nicht enthalten.

Unser interner Berichtsdienst bietet detailliertere Informationen zu API-Anfragen, einschließlich derer, die für Admin- und LookML-Entwicklungsaufgaben verwendet werden. Kunden mit Instanzen, die der empfohlenen Netzwerkkonfiguration entsprechen, können sich an den Looker-Support wenden, um einen Export dieser Daten anzufordern.

Ich hoste meine eigene Instanz. Muss ich bis zum 14. August 2023 umstellen?

Wenn Ihre Instanz selbst gehostet wird, müssen Sie die Änderungen vornehmen, bevor Sie ein Upgrade auf die Version vom August 2023 (Version 23.14) oder eine spätere Version durchführen. Wir empfehlen Ihnen, so bald wie möglich mit dieser Arbeit zu beginnen, damit Sie ein unterstütztes Release verwenden können und Looker optimal nutzen können.

Meine Instanz wird von Looker gehostet, nimmt aber am ESR-Programm teil. Muss ich bis zum 14. August 2023 umstellen?

Sie müssen die Änderungen vornehmen, bevor Ihre Instanz auf die Version vom August 2023 (Version 23.14) oder eine spätere Version aktualisiert wird. Wir empfehlen Ihnen, so bald wie möglich mit der Arbeit zu beginnen, damit Sie nicht unter Zeitdruck geraten, wenn Ihre Instanz das Upgrade erhalten soll.

Ich habe die Dokumentation gelesen, habe aber immer noch Probleme oder bin mir nicht sicher, wie ich vorgehen soll.

Kunden, die nicht erfolgreich zur API 4.0 migrieren können, sollten sich an den Looker-Support wenden.