API 金鑰是必須保密的憑證,用來驗證發出請求的身分。服務帳戶則是供應用程式或自動化工作負載使用的非人員身分。服務帳戶可以擁有 API 金鑰:在同一套驗證機制中,帳戶代表身分,金鑰則是驗證該身分的憑證。
進行個人開發時,請使用你自己擁有的專案金鑰。應用程式或自動化作業若需要獨立的權限和生命週期,請使用服務帳戶。透過管理員 API 管理組織時,請使用管理員 API 金鑰。
選擇合適的身分
| 工作負載 | 身分與憑證 | 原因 |
|---|---|---|
| 個人在本機開發或測試功能 | 你的使用者帳戶和專案 API 金鑰 | 發出請求時,使用的是你對該專案的存取權。 |
| 已部署的應用程式、排程作業或 CI 工作流程 | 專案服務帳戶及其 API 金鑰 | 工作負載有獨立的身分,不依附於個別開發人員。 |
| 使用 OpenAI 支援的身分提供者的工作負載 | 搭配工作負載身分聯盟的專案服務帳戶 | 工作負載無須儲存長效的 OpenAI API 金鑰即可完成身分驗證。 |
| 建立專案或管理專案服務帳戶與金鑰的自動化作業 | 管理員 API 金鑰 | 組織管理使用專屬的管理端點和權限。 |
使用者擁有的金鑰會以該使用者的存取權執行操作。請勿讓整個團隊共用某位開發人員的金鑰,也不要將該開發人員的身分當作正式環境中應用程式的永久身分。
服務帳戶隸屬於專案。請在專案內為每個工作負載提供所需的身分和存取權。為不同的應用程式或環境分別建立專案,即可區隔各自的資源、成員和用量。若只需區分工作負載,可在同一個專案內使用不同的服務帳戶,無須另建專案。
瞭解權限與範圍
API 金鑰可執行的操作,同時取決於金鑰本身及其擁有者的權限。設定金鑰的權限範圍可以限制可執行的操作,但無法授予使用者或服務帳戶原本沒有的權限。即使金鑰本身未設限,也只能在擁有者的有效權限範圍內執行操作。
請只為服務帳戶指派其工作負載所需的角色,再視需要限制金鑰的權限範圍。如需瞭解授權模型,請參閱權限與角色。如需建立身分、指派自訂角色並核發有特定權限範圍的金鑰,請參閱使用 Terraform 管理服務帳戶中的設定範例。
管理員 API 金鑰與專案工作負載使用的金鑰各有用途。請將管理員憑證保存在負責佈建和管理資源的受信任服務中。應用程式發出模型請求時,請使用所屬專案的服務帳戶憑證。
自動化管理專案與金鑰
如果你的應用程式會為客戶佈建專案,可以使用專案服務帳戶,讓每個工作負載都有自己的身分,無須依賴執行佈建流程的開發人員。佈建服務使用管理員 API 來管理專案及其服務帳戶,佈建完成的應用程式則使用自己的專案憑證。
相關的管理操作如下:
| 操作 | 用途 |
|---|---|
| 建立專案 | 建立專案,讓工作負載的資源與服務帳戶歸屬於該專案。 |
| 建立服務帳戶 | 在該專案中為工作負載建立身分。使用 create_service_account_only 選項時,只會建立服務帳戶,不會指派預設角色,也不會核發初始 API 金鑰。 |
| 建立服務帳戶 API 金鑰 | 為現有服務帳戶核發金鑰,並視需要設定金鑰的權限範圍與到期時間。 |
| 管理專案 API 金鑰 | 列出、取得、更新或撤銷現有的專案金鑰,包括服務帳戶的金鑰。 |
專案 API 金鑰管理端點不支援代替其他使用者建立歸其所有的專案金鑰。如需透過程式建立金鑰,請使用服務帳戶,並呼叫服務帳戶的金鑰建立端點。
建立服務帳戶時,若未指派預設角色,帳戶不會因此取得發出模型請求的權限。請先指派必要權限,再使用該帳戶的憑證。建立金鑰時,組織和專案的金鑰政策也都適用,使用服務帳戶無法略過這些政策。
管理憑證的生命週期
只有在建立服務帳戶金鑰時,API 才會傳回金鑰的完整值。請將金鑰儲存在機密管理工具中,並在伺服器端提供給工作負載使用。請勿將金鑰放在瀏覽器端程式碼、行動應用程式、版本控制系統、記錄檔或傳給客戶的回應中。
請依照組織和專案的政策設定金鑰的到期時間。輪替金鑰時,請先核發新金鑰,再更新工作負載以使用新金鑰。確認工作負載運作正常後,再撤銷舊金鑰。輪替金鑰時可以沿用同一個服務帳戶身分。
工作負載的職責有變時,請重新檢視其存取權。停用工作負載時,請撤銷其憑證。如需瞭解金鑰治理和到期政策,請參閱正式環境 API 金鑰使用指南。如需在不儲存 API 金鑰的情況下驗證身分,請參閱工作負載身分聯盟。