Looker API 疑難排解

本頁面提供下列 Looker API 問題的疑難排解程序：

• 無法連線至 API 端點
• API 結果是無意義的文字
• API 呼叫沒有回應
• 編碼無效錯誤
• 找不到方法錯誤
• 錯誤的要求 (400) 錯誤
• 未授權 (401) 錯誤
• 禁止存取 (403) 錯誤
• 找不到 (404) 錯誤
• 「不允許的方法 (405)」錯誤
• 衝突 (409) 錯誤
• 驗證 (422) 錯誤
• 要求數量過多 (429) 錯誤
• 內部伺服器錯誤 (500)

無法連上 API 端點

如果無法連線至 API 端點：

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

驗證 API 憑證

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

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

驗證 API 網址

無法連上 API 端點的另一個常見問題是 API 主機網址不正確。大多數 Looker 執行個體都會使用 API 的預設網址。不過，如果 Looker 安裝作業使用替代 API 路徑，或位於負載平衡器後方 (例如叢集設定) 或任何其他 Proxy，則可能不會使用預設網址。如果是這種情況，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 網址。舉例來說，如果是託管於 Google Cloud、Microsoft Azure 的執行個體，以及在 2020 年 7 月 7 日當天或之後建立的 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 4.0 中新增或移除了一些 API 呼叫。如需更新清單，請參閱「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 使用者介面中隨附的錯誤訊息會顯示：「找不到您要求的網頁。這個項目不存在，或是您沒有檢視權限。"

視代管 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 版本過舊，也可能發生這種情況。請務必更新這些 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 程式碼產生 API 或 Looker SDK，請確認 base_url 值正確無誤：

• 如果是 Swagger 程式碼產生用戶端，base_url 應為下列項目：

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

• 如果 Looker SDK 實作項目使用 looker.ini，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 要求。舉例來說，如果上傳的檔案比伺服器上的現有檔案舊，就會發生版本控管衝突，這是非 Looker 的常見錯誤。

使用 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 社群貼文「Is there a limit to the number of API requests you can send at one time?」(一次可傳送的 API 要求數量是否有限制？)。

內部伺服器錯誤 (500)

500 Internal Server Error 回應代碼表示伺服器發生非預期狀況，導致無法完成要求。

這個錯誤回應是一般「全方位」回應。通常這表示伺服器找不到更具體的 5xx 錯誤代碼，可傳回做為回應。Looker 傳回 500 回應是未預期的情況，因此如果您在嘗試與 Looker 互動時持續看到這項錯誤，建議您提出支援要求。