在 Google Cloud 中使用 ARCore API

選取平台： Android Unity (AR Foundation) iOS

地理空間 API 和 Cloud Anchors 等 ARCore 功能會使用託管於 Google Cloud 的 ARCore API。使用這些功能時，您的應用程式會使用憑證存取 ARCore API 服務。

本快速入門導覽課程說明如何設定應用程式，使其能與託管於 Google Cloud 的 ARCore API 服務通訊。

建立新的 Google Cloud 專案或使用現有專案

如果已有專案，請選取該專案。

前往專案選取器

如果您目前沒有 Google Cloud 專案，請建立一個。

建立新專案

啟用 ARCore API

如要使用 ARCore API，您必須在專案中啟用。

啟用 ARCore API

設定授權方法

iOS 應用程式可以使用兩種不同的授權方式與 ARCore API 通訊：無金鑰授權 (這是建議做法) 和 API 金鑰授權：

• 無金鑰授權會使用已簽署的權杖來控制 API 的存取權。這個方法需要您擁有的伺服器來簽署權杖，並控管 API 的存取權。
• API 金鑰是可識別 Google Cloud 專案的字串。一般來說，用戶端可存取 API 金鑰，因此通常不安全。建議使用權杖授權與 ARCore API 通訊。

無金鑰

ARCore 支援在 iOS 中使用 (JSON Web 權杖) 呼叫 API 呼叫。憑證必須由 Google 服務帳戶簽署。

如要針對 iOS 產生權杖，您的伺服器上必須有符合以下要求的端點：

• 您自己的授權機制必須保護端點。

• 端點每次都必須產生新的權杖，如下所示：

  • 每位使用者都會取得專屬權杖。
  • 權杖不會立即過期。

建立服務帳戶和簽署金鑰

如要建立 Google 服務帳戶和簽署金鑰，請按照下列步驟操作：

1. 在 Google Cloud 中開啟「憑證」頁面。
   憑證
2. 依序按一下「建立憑證」>「服務帳戶」。
3. 在「Service account details」(服務帳戶詳細資料) 下方輸入新帳戶的名稱，然後按一下「Create」(建立)。
4. 在「服務帳戶權限」頁面，前往「請選擇角色」下拉式選單。依序選取「Service Accounts」(服務帳戶) >「Service Account Token Creator」(服務帳戶憑證建立者)，然後按一下「Continue」(繼續)。
5. 在「將這個服務帳戶的存取權授予使用者」頁面中，按一下「完成」。
6. 在「Credentials」(憑證) 頁面上找到「Service Account」(服務帳戶) 部分，然後按一下您剛建立的帳戶名稱。
7. 在「Service account details」(服務帳戶詳細資料) 頁面中，向下捲動至「Keys」(金鑰) 部分，然後選取「Add Key」(新增金鑰) >「Create new key」(建立新的金鑰)。

8. 選取「JSON」做為金鑰類型，然後按一下「建立」。

   即可將包含私密金鑰的 JSON 檔案下載至您的電腦。將下載的 JSON 金鑰檔案儲存在安全的位置。

   附註： 這個檔案包含不得對外公開的私密金鑰。「請勿」將其提交至 GitHub 等原始碼存放區。

在伺服器上建立權杖

如要在伺服器上建立新權杖 (JWT)，請使用標準 JWT 程式庫，以及您透過新服務帳戶安全下載的 JSON 檔案。

在開發機器上建立權杖

如要在開發機器上產生 JWT，請使用下列 oauth2l 指令：

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

必須使用 --cache 旗標指定空白的快取位置，才能確保每次都會產生不同的憑證。請務必修剪產生的字串。多餘的空格或換行字元會導致 API 拒絕權杖。

簽署權杖

您必須使用 RS256 演算法和下列憑證附加資訊來簽署 JWT：

• iss：服務帳戶電子郵件地址。
• sub：服務帳戶電子郵件地址。
• iat：產生權杖的 Unix Epoch 紀元時間 (以秒為單位)。
• exp - iat + 3600 (1 小時)。權杖的 Unix Epoch 紀元時間，以秒為單位。
• aud - 目標對象。必須設為 https://arcore.googleapis.com/。

JWT 酬載中不需要非標準憑證附加資訊，但您可能會發現 uid 憑證附加資訊有助於識別對應的使用者。

如果您使用其他方法產生 JWT，例如在 Google 代管的環境中使用 Google API 時，請務必使用本節所述的憑證附加資訊簽署 JWT。最重要的是，請確認目標對象正確無誤。

在 ARCore 工作階段中傳送權杖

您的應用程式已設為使用無金鑰驗證。

將權杖傳入工作階段時，請注意下列事項：

• 如果您使用 API 金鑰建立工作階段，ARCore 會忽略該權杖並記錄錯誤。

  如果您不再需要 API 金鑰，請前往 Google Developers Console 刪除該金鑰，並將其從應用程式中移除。

• ARCore 會忽略含有空格或特殊字元的權杖。

• 權杖通常會在一小時後失效。如果權杖在使用期間可能會過期，請取得新權杖並傳遞至 API。

API 金鑰

1. 在 Google Cloud 中開啟「憑證」頁面。
   憑證
2. 按一下「建立憑證」，然後在選單中選取「API 金鑰」。
   「建立的 API 金鑰」對話方塊會顯示新建金鑰的字串。
4. 請參閱 API 金鑰限制說明文件，確保 API 金鑰安全無虞。

應用程式現已設為使用 API 金鑰。

後續步驟

設定授權後，請查看下列使用這個 API 的 ARCore 功能：

• 地理空間 API
• Cloud Anchor API