Looker API 疑難排解

本頁面列出 Looker API 可能發生的問題，並提供相應的疑難排解程序：

• 無法存取 API 端點
• API 結果是無意義的文字
• API 呼叫未回應
• 無效的編碼錯誤
• 找不到方法錯誤
• 錯誤的要求 (400) 錯誤
• 未授權 (401) 錯誤
• 禁止 (403) 錯誤
• 找不到 (404) 錯誤
• Method Not Allowed (405) 錯誤
• Conflict (409) 錯誤
• 驗證 (422) 錯誤
• 要求數量過多 (429) 錯誤
• 內部伺服器錯誤 (500)

無法連上 API 端點

如果無法存取 API 端點：

• 驗證 API 憑證
• 驗證 API 主機網址
• 驗證 API 連接埠
• 驗證 API 呼叫網址

驗證 API 憑證

如果無法連線至 Looker API 端點，請先確認 API 憑證是否正確。如要查看 API 憑證，請按照下列步驟操作：

1. 在 Looker 中，選取左側導覽面板中的「管理」選項，即可存取「管理」面板。
2. 在「管理」頁面的左側面板中，向下捲動並按一下「使用者」。
3. 在使用者清單中搜尋您的使用者名稱，然後按一下該名稱即可編輯使用者頁面。
4. 點選「編輯 API 金鑰」。您可以看到「Client ID」，並點選眼睛圖示，查看已設定的每個 API 金鑰的「Client Secret」。確認您的 API 憑證與指令碼中使用的憑證相符。

驗證 API 網址

另一個常見的問題是 API 主機網址不正確，導致無法存取 API 端點。大多數 Looker 執行個體都會使用 API 的預設網址。不過，使用其他 API 路徑的 Looker 安裝作業，或是位於負載平衡器 (例如叢集設定) 或任何其他 Proxy 後方的 Looker 安裝作業，可能不會使用預設網址。在這種情況下，API 主機網址必須指出面向使用者的 API 主機名稱和通訊埠。

Looker 管理員可以在 API 管理員設定中查看 API 主機網址 (詳情請參閱「管理員設定 - API」說明文件頁面)。如要查看 API 主機網址，請按照下列步驟操作：

1. 按一下 Looker「主選單」圖示 menu，然後選取「管理」，開啟「管理」面板。
2. 按一下「管理」面板中的「API」。

3. 查看 API 主機網址。

   如果「API 主機網址」欄位留空，Looker 執行個體會使用預設格式，如下所示：

   https://<instance_name>.cloud.looker.com:<port>
   

如要測試 API 主機網址：

1. 開啟瀏覽器，然後開啟瀏覽器控制台。

2. 輸入 API 主機網址，後面加上 /alive。舉例來說，如果您的 API 主機網址是 https://company.cloud.looker.com，請輸入：

   https://company.cloud.looker.com/alive
   

   如果 API 主機網址欄位為空白，請使用預設的 API 網址。舉例來說，如果是 2020 年 7 月 7 日當天或之後建立的 Google Cloud、Microsoft Azure 和 Amazon Web Services (AWS) 託管執行個體，預設 Looker API 路徑會使用 443 連接埠：

   https://<instance_name>.cloud.looker.com:443/alive
   

   如果是 2020 年 7 月 7 日前建立的 AWS 代管執行個體，預設的 Looker API 路徑會使用 19999 這個連接埠：

   https://<instance_name>.cloud.looker.com:19999/alive
   

如果 API 主機網址正確，這個網址會產生空白網頁，而非錯誤頁面。

您也可以在瀏覽器控制台中查看網路回應，確認是否已連上 API。網路回應應為 200。

如果這些檢查失敗，可能是因為您呼叫 API 的方式不正確，或是程式碼有其他錯誤。請檢查指令碼中的 API 呼叫和程式碼。如果這些資訊正確無誤，請參閱下一節，瞭解如何驗證端口。

驗證 API 連接埠

如果先前的檢查未通過，且您有客戶代管的 Looker 部署，可能需要在網路基礎架構中開啟 API 通訊埠。

API 通訊埠應轉送至 Looker 伺服器。如果是客戶代管的 Looker 部署作業，請要求網路管理員檢查 API 連接埠設定。API 連接埠通常為 443 或 19999。API 通訊埠的設定應與 Looker 執行個體通訊埠相同 (預設為 9999)。網路管理員應確認下列設定與 API 通訊埠和 Looker 執行個體通訊埠相同：

• Proxy
• 負載平衡器
• 防火牆

驗證 API 呼叫網址

請確認您使用的是正確的 API 呼叫網址。API 端點網址的格式如下：

<API Host URL>/api/<API version>/<API call>

如果您使用的是預設 API 主機網址，API 端點網址的格式如下：

https://<instance_name>:<port>/api/<API version>/<API call>

您可以透過 API Explorer 或 API 參考資料說明文件，取得 API 端點的網址格式。

舉例來說，API 4.0 參考資料會為 Get All Running Queries 端點提供下列相對路徑：

/api/4.0/running_queries

因此，在 docsexamples.dev.looker.com Looker 例項上，Get All Running Queries 端點的完整 API 端點網址會是以下內容：

https://docsexamples.dev.looker.com:443/api/4.0/running_queries

API 結果是無意義的文字

如果 API 傳回的回應是亂碼，表示您可能看到 PDF、PNG 或 JPG 檔案的二進位內容。部分 HTTP REST 程式庫會假設 API 回應是文字檔案，因此會將其他類型的檔案顯示為二進位文字。

在這種情況下，您必須確保 HTTP REST 程式庫會將 API 回應視為二進位資料，而不是文字。在某些情況下，這可能表示在 API 呼叫上設定標記，告訴 HTTP REST 程式庫這是二進位結果，或是表示以特殊方式處理結果，例如位元組串流或位元組陣列，而非將結果指派給字串變數。

API 呼叫沒有回應

如果您可以開啟 API Explorer，但 API 呼叫沒有回應，請確認 Looker 執行個體的 API 主機網址設定是否正確。Looker 管理員可以在 Looker 的 API 管理員設定中查看 API 主機網址 (請參閱「管理員設定 - API」說明文件頁面)。

無效的編碼錯誤

如果在嘗試呼叫 API 時收到編碼錯誤，您可能需要在要求期間在標頭中設定適當的 Content-Type。根據 HTTP 通訊協定標準，任何 POST、PUT 或 PATCH 要求都必須包含 Content-Type 標頭。由於 Looker API 會在整個過程中使用 JSON，因此應將 Content-Type 標頭設為 application/json。

請注意，使用 Looker SDK 會自動處理這個問題。

找不到方法的錯誤

如果您收到「找不到方法」錯誤 (例如 method not found: all_looks())，請先檢查 API 版本。有幾個 API 呼叫是 API 4.0 中的新功能，或在 API 4.0 中遭到移除。如需更新清單，請參閱 Looker API 4.0 正式發布公告。

錯誤的要求 (400)

400 Bad Request 錯誤表示 API 呼叫中提供的資料無法辨識。造成問題的通常是無效的 JSON，可能是剖析錯誤。在大多數情況下，400 錯誤都已通過驗證，因此錯誤回應訊息會提供更具體的錯誤資訊。

未授權 (401) 錯誤

API 呼叫出現 401 Unauthorized 錯誤，表示 API 呼叫未經過適當驗證。如需更多疑難排解詳細資訊，請參閱「如何排解 401 錯誤？」社群文章。

禁止 (403) 錯誤

當使用者嘗試存取 LookML 物件或其他未授權的內容時，Looker API 不會每次都傳回 403 錯誤。在某些情況下，傳回 403 錯誤 (而非 404 錯誤) 可以驗證特定探索、資訊主頁或 LookML 物件的存在性，但擁有者可能不希望這項資訊公開。為避免發生這種情況，Looker 會在這些情況下傳回 404，Looker UI 隨附的錯誤訊息如下：「找不到您要求的網頁。這個項目不存在，或是您沒有檢視權限。」

視 Looker 執行個體代管的環境和 Looker 執行個體設定而定，可存取 API 的通訊埠號碼和相關網址可能會有所不同。如果使用錯誤的通訊埠號碼，系統可能會顯示 403 錯誤。舉例來說，如果 Looker 執行個體是使用預設的 API 通訊埠 443 進行設定，連線至 https://mycompany.looker.com/api/4.0/login (而非 https://mycompany.looker.com:443/api/4.0/login) 會傳回 403 錯誤。如為客戶代管的執行個體，請參閱 Looker 啟動選項，瞭解如何定義 API 通訊埠。

使用過舊版本的 Ruby SDK gem 時，也可能發生這種情況。請務必更新這些寶石。你可以前往 https://rubygems.org/gems/looker-sdk 查看。

如果你未在網址中加入 /api/<version number>/ 部分，也可能發生這種情況。在這種情況下，如果使用者嘗試連線至 https://mycompany.looker.com:443/login，就會看到 403 回應。

找不到 (404) 錯誤

發生錯誤時 (通常是權限相關問題)，系統會回報 404 Not Found 錯誤做為預設錯誤。404 錯誤的回應訊息會提供最少的資訊 (如果有)。這是有意為之，因為 404 錯誤會顯示給登入憑證錯誤或權限不足的使用者。Looker 不希望在 404 回應訊息中提供特定資訊，因為這些資訊可用於繪製 Looker API 的「攻擊面」。

如果 API 登入嘗試傳回 404 錯誤，很可能是因為 API 客戶端 ID 或客戶端密鑰無效 (請參閱本頁稍早的「驗證 API 憑證」)。API 登入 REST 端點如下：

• https://<your-looker-hostname>:<port>/api/4.0/login

如果您使用 Swagger codegen API 或 Looker SDK，請確認 base_url 值是否正確：

• 對於 Swagger codegen 用戶端，base_url 應為下列內容：

  • https://<your-looker-hostname>:<port>/api/4.0/

• 對於使用 looker.ini 的 Looker SDK 實作項目，api_version 的值應為 4.0，base_url 的值應與 Looker 例項 API 的網址相同，格式為 https://<your-looker-hostname>:<port>。以下是 looker.ini 檔案範例：

  # api_version should be 4.0
  api_version=4.0
  base_url=https://<your-looker-hostname>:<port>
  

您在登入後也可能會收到 404 錯誤訊息。如果您已登入，但收到 404 錯誤，表示您沒有剛才呼叫的 API 指令的權限。

方法不允許 (405) 錯誤

405 Method Not Allowed 錯誤表示伺服器知道要求方法，但目標資源不支援此方法。

伺服器必須在 405 狀態碼回應中產生 Allow 標頭欄位。這個欄位必須包含目標資源支援的方法清單。

舉例來說，如果您嘗試使用 update_dashboard() 端點更新 LookML 資訊主頁的中繼資料，就可能會在 Looker 中遇到這個問題。Looker API 不支援變更 LookML 資訊主頁的 id 參數，因此會發生 405 錯誤。

衝突 (409) 錯誤

409 Conflict 回應狀態碼表示要求與目標資源目前的狀態相衝突。

回應 PUT 要求時，最有可能發生衝突。舉例來說，如果上傳的檔案比伺服器上的現有檔案還舊，就會發生這類錯誤，導致版本控制發生衝突。

在嘗試使用 API 檢查新的 Git 分支，或是使用 create_group() 或 create_dashboard() 等端點時，您可能會在 Looker 中遇到這個錯誤。在這種情況下，請檢查您嘗試建立的物件是否已存在。

驗證 (422) 錯誤

如果要求中的某項內容未通過資料檢查，就會發生驗證錯誤。要求含有一或多個下列類型的錯誤 (錯誤回應會指出確切的錯誤)：

• 缺少欄位：未提供必要參數 (錯誤回應會指出缺少哪個欄位)。
• 無效：提供的值不符於現有值，或值的格式不正確。舉例來說，如果您嘗試建立 Look，但在 API 呼叫中提供的查詢 ID 與現有查詢不符，就會收到驗證錯誤。
• 已存在：API 呼叫嘗試建立的物件 ID 或名稱，已在 Looker 例項中存在。舉例來說，資料庫連線名稱不得重複。如果您嘗試建立使用現有連線名稱的新資料庫連線，系統會傳回驗證錯誤，並顯示代碼 already_exists。

請參閱錯誤回應訊息，瞭解哪些欄位可能缺少或為必填欄位，或是哪些欄位可能含有無效值。回應訊息會同時提供所有驗證錯誤。因此，如果您缺少欄位或欄位不正確，錯誤回應會列出 API 呼叫的所有問題。

回覆範例如下：

{
  "message": "Validation Failed",
  "errors": [
    {
    "field": "dialect",
    "code": "missing_field",
    "message": "This field is required.",
    "documentation_url": "http://docs.looker.com/"
    },
    {
    "field": "db_timezone",
    "code": "invalid",
    "message": "Must specify a database timezone when user timezones are activated.",
    "documentation_url": "http://docs.looker.com/"
    }
  ],
    ...

在這個案例中，API 呼叫缺少必要的 dialect 欄位，且 db_timezone 中提供的值無效。

要求數量過多 (429) 錯誤

429 Too Many Requests 回應狀態碼表示使用者在特定時間內傳送過多要求 (稱為「頻率限制」)。如要進一步瞭解 Looker 的頻率限制政策，請參閱 Looker 社群文章「一次可以傳送的 API 要求數量是否有限制？」。

內部伺服器錯誤 (500)

500 Internal Server Error 回應代碼表示伺服器遇到無法滿足要求的意外情況。

這個錯誤回應是一般「萬用」回應。這通常表示伺服器無法在回應中傳回更明確的 5xx 錯誤代碼。Looker 的任何 500 回應都是意外的，因此如果您在嘗試與 Looker 互動時，持續看到這項錯誤，建議您提出支援要求。