如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

API 金鑰與服務帳戶

為開發工作、應用程式和自動化作業選擇合適的身分與憑證。

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 金鑰的情況下驗證身分,請參閱工作負載身分聯盟。