地理空間 API 和 Cloud Anchors 等 ARCore 功能會使用託管於 Google Cloud 的 ARCore API。使用這些功能時,您的應用程式會使用憑證存取 ARCore API 服務。
本快速入門導覽課程說明如何設定應用程式,使其能與託管於 Google Cloud 的 ARCore API 服務通訊。
建立新的 Google Cloud 專案或使用現有專案
如果已有專案,請選取該專案。
如果您目前沒有 Google Cloud 專案,請建立一個。
啟用 ARCore API
如要使用 ARCore API,您必須在專案中啟用。
設定授權方法
iOS 應用程式可以使用兩種不同的授權方式與 ARCore API 通訊:無金鑰授權 (這是建議做法) 和 API 金鑰授權:
- 無金鑰授權會使用已簽署的權杖來控制 API 的存取權。這個方法需要您擁有的伺服器來簽署權杖,並控管 API 的存取權。
- API 金鑰是可識別 Google Cloud 專案的字串。一般來說,用戶端可存取 API 金鑰,因此通常不安全。建議使用權杖授權與 ARCore API 通訊。
無金鑰
ARCore 支援在 iOS 中使用 (JSON Web 權杖) 呼叫 API 呼叫。憑證必須由 Google 服務帳戶簽署。
如要針對 iOS 產生權杖,您的伺服器上必須有符合以下要求的端點:
您自己的授權機制必須保護端點。
端點每次都必須產生新的權杖,如下所示:
- 每位使用者都會取得專屬權杖。
- 權杖不會立即過期。
建立服務帳戶和簽署金鑰
如要建立 Google 服務帳戶和簽署金鑰,請按照下列步驟操作:
- 在 Google Cloud 中開啟「憑證」頁面。
憑證 - 依序按一下「建立憑證」>「服務帳戶」。
- 在「Service account details」(服務帳戶詳細資料) 下方輸入新帳戶的名稱,然後按一下「Create」(建立)。
- 在「服務帳戶權限」頁面,前往「請選擇角色」下拉式選單。依序選取「Service Accounts」(服務帳戶) >「Service Account Token Creator」(服務帳戶憑證建立者),然後按一下「Continue」(繼續)。
- 在「將這個服務帳戶的存取權授予使用者」頁面中,按一下「完成」。
- 在「Credentials」(憑證) 頁面上找到「Service Account」(服務帳戶) 部分,然後按一下您剛建立的帳戶名稱。
- 在「Service account details」(服務帳戶詳細資料) 頁面中,向下捲動至「Keys」(金鑰) 部分,然後選取「Add Key」(新增金鑰) >「Create new key」(建立新的金鑰)。
選取「JSON」做為金鑰類型,然後按一下「建立」。
即可將包含私密金鑰的 JSON 檔案下載至您的電腦。將下載的 JSON 金鑰檔案儲存在安全的位置。
在伺服器上建立權杖
如要在伺服器上建立新權杖 (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 工作階段中傳送權杖
使用
GARSession#sessionWithError:
建構工作階段。NSError *error = nil; GARSession *garSession = [GARSession sessionWithError:&error];
取得權杖後,請使用
setAuthToken:
將權杖傳遞至工作階段。否則,工作階段就會使用您傳入的最新有效授權權杖。每次更新權杖時,請呼叫這個方法:[garSession setAuthToken: authToken]
您的應用程式已設為使用無金鑰驗證。
將權杖傳入工作階段時,請注意下列事項:
如果您使用 API 金鑰建立工作階段,ARCore 會忽略該權杖並記錄錯誤。
如果您不再需要 API 金鑰,請前往 Google Developers Console 刪除該金鑰,並將其從應用程式中移除。
ARCore 會忽略含有空格或特殊字元的權杖。
權杖通常會在一小時後失效。如果權杖在使用期間可能會過期,請取得新權杖並傳遞至 API。
API 金鑰
- 在 Google Cloud 中開啟「憑證」頁面。
憑證 - 按一下「建立憑證」,然後在選單中選取「API 金鑰」。
「建立的 API 金鑰」對話方塊會顯示新建金鑰的字串。 建立
GARSession
時,請使用GARSession#sessionWithAPIKey:bundleIdentifier:error:
並插入 API 金鑰:self.garSession = [GARSession sessionWithAPIKey:@"your-api-key" bundleIdentifier:nil error:&error];
- 請參閱 API 金鑰限制說明文件,確保 API 金鑰安全無虞。
應用程式現已設為使用 API 金鑰。
後續步驟
設定授權後,請查看下列使用這個 API 的 ARCore 功能: