您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。
如果 Cloud 客戶使用付費帳戶,且所有 Edge for Private Cloud 客戶都能在機構中建立虛擬主機,建立虛擬主機的使用者必須具備機構管理員的角色,或是具備修改虛擬主機權限的自訂角色。其他角色的使用者沒有建立虛擬主機的權限。
觀看虛擬主機簡介影片。
建立虛擬主機
請使用下列基本程序建立虛擬主機。 實際執行的程序取決於您是 Cloud 還是私有雲客戶,以及是否啟用傳輸層安全標準 (TLS):
- 為公開網域建立 DNS 項目和 CNAME 記錄。
- 啟用虛擬主機的傳輸層安全標準 (TLS) 功能:
- 按照這裡所述的程序建立及設定 KeyStore:KeyStores 和 Truststores。
- 將憑證和金鑰上傳至 KeyStore。確保憑證指定的網域名稱與您要用於虛擬主機的主機別名相符。
- 使用 Edge UI 或 API 建立 KeyStore 參照。該參考資料會將 KeyStore 名稱和參照類型指定為
KeyStore
。如要進一步瞭解如何建立及修改參照,請參閱「使用參考檔案」。 - 如果您執行雙向傳輸層安全標準 (TLS),請建立信任儲存庫、上傳憑證,然後建立信任存放區的參照。按照「Keystores and Truststores」所述的程序建立信任儲存庫。
- 使用建立虛擬主機 API 建立虛擬主機。啟用傳輸層安全標準 (TLS) 時,請務必指定正確的 KeyStore 參照、信任儲存庫參照和金鑰別名。
- 如有任何現有的 Proxy Proxy,請將虛擬主機新增至 ProxyEndpoint。虛擬主機會自動新增至所有新的 API Proxy。請參閱設定 API Proxy 以使用虛擬主機一文。
更新 API Proxy 以使用虛擬主機,並建立主機別名的 DNS 項目和 CNAME 記錄後,您可以存取 API Proxy,如下所示:
https://api.myCompany.com/v1/project-base-path/resource-path
例如:
https://api.myCompany.com/v1/weather/forecastrss?w=12797282
使用 API 或 UI 建立虛擬主機
您可使用 Edge API 或 Edge UI 建立虛擬主機。
下方大部分的範例使用 Edge API。如要存取 UI,在 Edge UI 中建立、修改及刪除虛擬主機:
- 登入 apigee.com/edge
私有雲客戶的 Edge 會使用
http://ms-ip:9000
(地端部署),其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 - 依序選取左側導覽列中的「Admin」(虛擬) >「Virtual Hosts」(虛擬主機)。
- 選取環境,例如「prod」或「test」。
系統會隨即顯示為環境定義的虛擬主機。 - 選取「+ Virtual Host」建立虛擬主機,或是選取現有虛擬主機的名稱來加以編輯。
建立 HTTP 的虛擬主機
Edge Private Cloud 客戶可以使用 HTTP 建立虛擬主機。
如要建立不支援傳輸層安全標準 (TLS) 的虛擬主機,請建立定義虛擬主機的 XML 物件。舉例來說,下列 XML 物件會定義使用 HTTP 通訊協定的虛擬主機:
<VirtualHost name="myVHost"> <HostAliases> <HostAlias>api.myCompany.com</HostAlias> </HostAliases> <Interfaces/> <Port>80</Port> </VirtualHost>
在此定義中,您:
- 將「name」(名稱) 指定為 myVHost。在 API Proxy 或 API 呼叫中,使用這個名稱來參照虛擬主機。
- 將「主機別名」指定為 api.myCompany.com。這是 DNS 定義和 CNAME 記錄所定義的公開存取 API 的網域。
- 將「通訊埠」號碼指定為 80。如果省略,通訊埠會預設為 443。
您還可以在虛擬主機中設定其他屬性。如需所有屬性的參考資料,請參閱虛擬主機屬性參考資料。
如果您目前有任何 API Proxy,請將虛擬主機新增至 Proxy 端點的 <HTTPConnection>
元素中。虛擬主機會自動新增至所有新的 API Proxy。
請參閱設定 API Proxy 以使用虛擬主機。如果您建立了不應透過特定虛擬主機存取的新 API Proxy,則必須編輯 API Proxy,從該 Proxy 中移除該虛擬主機。
接著,您可以透過下列方式,透過這個虛擬主機存取 API Proxy:
http://api.myCompany.com/proxy-base-path/resource-path https://api.myCompany.com/proxy-base-path/resource-path
使用 Create a Virtual Host API 建立虛擬主機:
curl -X POST -H "Content-Type:application/xml" \ http://ms-IP:8080/v1/o/org_name/environments/env_name/virtualhosts \ -d '<VirtualHost name="myVHost"> <HostAliases> <HostAlias>api.myCompany.com</HostAlias> </HostAliases> <Interfaces/> <Port>80</Port> </VirtualHost>' \ -u sysAdminEmail:password
為單向傳輸層安全標準 (TLS) 建立虛擬主機
下列 XML 物件定義了單向傳輸層安全標準 (TLS) 虛擬主機:
<VirtualHost name="myTLSVHost"> <HostAliases> <HostAlias>api.myCompany.com</HostAlias> </HostAliases> <Port>443</Port> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>false</ClientAuthEnabled> <KeyStore>ref://myTestKeystoreRef</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> </SSLInfo> </VirtualHost>
在此定義中,您可以將 <Enable>
元素設為 true,並使用 <KeyStore>
和 <KeyAliase>
元素指定傳輸層安全標準 (TLS) 連線使用的 KeyStore 和金鑰別名,藉此啟用傳輸層安全標準 (TLS)。
如要進一步瞭解如何使用傳輸層安全標準 (TLS),請參閱「傳輸層安全標準 (TLS)/SSL」一文。
決定如何在虛擬主機中指定 KeyStore 和 Truststore 名稱
將虛擬主機設為支援傳輸層安全標準 (TLS) 時,您可以使用參照來指定 KeyStore。參照是包含 KeyStore 或 Truststore 名稱的變數,而不是直接指定 KeyStore 或 Truststore 名稱,如下所示:
<SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>false</ClientAuthEnabled> <KeyStore>ref://myTestKeystoreRef</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> </SSLInfo>
使用參照的優點是您可以變更參照的值,來變更虛擬主機使用的 KeyStore,原因通常是目前的 KeyStore 中的憑證即將到期。變更參照值不必重新啟動邊緣路由器。如要進一步瞭解如何建立及修改參照,請參閱「使用參考檔案」。
您只能使用 KeyStore 和受信任儲存庫的參照,因此無法使用別名的參照。將 KeyStore 參照變更為其他金鑰時,請確保憑證的別名名稱與舊 KeyStore 中的名稱相同。
使用 KeyStore 和 TrustStore 時須遵守的限制
使用 KeyStore 和 Truststore 時,您必須考量以下限制:
- 如果支援 SNI 並終止 Apigee 路由器的 SSL,您就只能在虛擬主機中使用 KeyStore 和信任儲存庫參照。
- 如果您在 Apigee 路由器之前設有負載平衡器,並在負載平衡器上終止傳輸層安全標準 (TLS),就無法在虛擬主機中使用 KeyStore 和信任儲存庫參考資料。
建立雙向傳輸層安全標準 (TLS) 的虛擬主機
如要啟用雙向傳輸層安全標準 (TLS),請將 <ClientAuthEnabled>
元素設為 true
,然後使用 <TrustStore>
元素的參照來指定信任儲存庫。TrustStore 會保有用戶端憑證授權單位和憑證的 CA 鏈結資訊。另外,用戶端也必須正確設定雙向傳輸層安全標準 (TLS)。
如要建立雙向 TLS 的虛擬主機,請建立用於定義虛擬主機的 XML 物件:
<VirtualHost name="myTLSVHost"> <HostAliases> <HostAlias>api.myCompany.com</HostAlias> </HostAliases> <Port>443</Port> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>ref://myTestKeystoreRef</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> <TrustStore>ref://myTestTruststoreRef</TrustStore> </SSLInfo> </VirtualHost>
在此定義中,您:
- 將
<ClientAuthEnabled>
設為 true,即可啟用雙向傳輸層安全標準 (TLS)。 - 使用
<TrustStore>
元素指定信任儲存庫的參照。TrustStore 會保有用戶端憑證授權單位和憑證的 CA 鏈結資訊。
如要進一步瞭解如何使用傳輸層安全標準 (TLS),請參閱「傳輸層安全標準 (TLS)/SSL」一文。
修改虛擬主機
如果 Cloud 客戶擁有付費帳戶,且所有 Edge for Private Cloud 客戶,都可使用 更新虛擬主機 API 更新虛擬主機。您可以使用這個 API 為虛擬主機屬性參考資料中所述的虛擬主機設定所有屬性。
使用 更新虛擬主機 API 來更新虛擬主機。使用 API 時,您必須在要求主體中指定虛擬主機的完整定義,而不只是要變更的元素。
在這個範例中,您會設定 proxy_read_timeout
屬性的值:
curl -X PUT -H "Content-Type:application/xml" \ https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/virtualhosts/vhost_name \ -d '<VirtualHost name="myTLSVHost"> <HostAliases> <HostAlias>api.myCompany.com</HostAlias> </HostAliases> <Port>443</Port> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>false</ClientAuthEnabled> <KeyStore>ref://myTestKeystoreRef</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> </SSLInfo> <Properties> <Property name="proxy_read_timeout">50</Property> </Properties> </VirtualHost>' \ -u orgAdminEmail:password
刪除虛擬主機
您必須先更新任何參照虛擬主機的 API Proxy,才能移除環境中的虛擬主機。請參閱設定 API Proxy 以使用虛擬主機一文。
使用 Delete a Virtual Host API 刪除虛擬主機:
curl -X DELETE \ https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/virtualhosts/vhost_name \ -u orgAdminEmail:password
查看虛擬主機的相關資訊
查看環境中定義的虛擬主機相關資訊,如下所述。
邊緣
如要使用 Edge UI 查看虛擬主機的相關資訊:
- 登入 apigee.com/edge。
私有雲客戶的 Edge 會使用
http://ms-ip:9000
(地端部署),其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 - 依序選取左側導覽列中的「Admin」(虛擬) >「Virtual Hosts」(虛擬主機)。
- 選取環境,例如「prod」或「test」。
系統會針對環境定義的虛擬主機顯示。如果虛擬主機已設為使用 KeyStore 或 Truststore,請按一下「Show」即可查看更多資訊。
如果虛擬主機設定為使用傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL),則會在虛擬主機名稱旁邊顯示鎖頭圖示。代表傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 憑證、金鑰和憑證鏈結已上傳到 Edge,並連結至虛擬主機。如要查看可用憑證的相關資訊,請按照下列步驟操作:
- 在左側導覽列中,依序選取「管理」>「環境」>「TLS KeyStore」。
- 選取環境 (通常為
prod
或test
)。 - 展開 KeyStore 即可查看憑證。
傳統版 Edge (私有雲)
如要使用傳統版 Edge UI 查看虛擬主機的相關資訊,請按照下列步驟操作:
- 登入
http://ms-ip:9000
,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 - 依序選取左側導覽列中的「Admin」(虛擬) >「Virtual Hosts」(虛擬主機)。
- 選取環境,例如「prod」或「test」。
- 按一下「Virtual Hosts」分頁標籤。
系統會針對環境定義的虛擬主機顯示。如果虛擬主機已設為使用 KeyStore 或 Truststore,請按一下「Show」即可查看更多資訊。
如果虛擬主機設定為使用傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL),則會在虛擬主機名稱旁邊顯示鎖頭圖示。代表傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 憑證、金鑰和憑證鏈結已上傳到 Edge,並連結至虛擬主機。如要查看可用憑證的相關資訊,請按照下列步驟操作:
- 在頂端導覽列選取「管理」>「傳輸層安全標準 (TLS) 憑證」。
- 選取環境 (通常為
prod
或test
)。 - 展開 KeyStore 即可查看憑證。
使用 Edge API 查看虛擬主機
您也可以使用 Edge API 查看虛擬主機的相關資訊。舉例來說,List Virtual Hosts API 會傳回所有虛擬主機的清單:
curl -X GET -H "accept:application/xml" \ https://api.enterprise.apigee.com/v1/o/org_name/environments/env_name/virtualhosts \ -u orgAdminEmail:pWord
其中 orgAdminEmail:pWord 是機構管理員的使用者名稱和密碼,org_name/env_name 會指定包含虛擬主機的機構和環境。回應範例:
[ "default", "secure" ]
如要查看特定虛擬主機的相關資訊,請使用 Get Virtual Host API:
curl -X GET -H "accept:application/xml" \ https://api.enterprise.apigee.com/v1/o/org_name/environments/env_name/virtualhosts/vhost_name \ -u orgAdminEmail:pWord
其中 vhost_name 是虛擬主機的名稱。舉例來說,您可以將 vhost_name 指定為「不安全」,以查看 Apigee 建立的預設安全虛擬主機設定:
<VirtualHost name="secure"> <HostAliases> <HostAlias>api.myCompany.com</HostAlias> </HostAliases> <Port>443</Port> <Properties/> <Interfaces/> <RetryOptions/> <SSLInfo> <ClientAuthEnabled>false</ClientAuthEnabled> <Enabled>true</Enabled> <KeyAlias>freetrial</KeyAlias> <KeyStore>ref://freetrial</KeyStore> <IgnoreValidationErrors>false</IgnoreValidationErrors> </SSLInfo> </VirtualHost>
設定 API Proxy 以使用虛擬主機
建立新的 API Proxy 時,Edge 會自動設為使用機構中的所有可用虛擬主機。透過虛擬主機向 API Proxy 發出的要求會使用以下表單:
https://host-alias/proxy-base-path/resource-path
在此情況下:
- host-alias 通常是虛擬主機的 DNS 名稱。
- 您在建立 API Proxy 時已定義 proxy-base-path,且每個 API Proxy 皆不重複。
- resource-path:透過 API Proxy 存取資源的路徑。
控制 API Proxy 使用的虛擬主機
在 API Proxy 的 XML 設定中,您可以使用 virtualhost
標記來指定與 API Proxy 相關聯的虛擬主機名稱:
<HTTPProxyConnection> <BasePath>/v1/my/proxy/basepath</BasePath> <VirtualHost>secure</VirtualHost> <VirtualHost>default</VirtualHost> </HTTPProxyConnection>
舉例來說,<VirtualHost>secure</VirtualHost>
表示用戶端可以使用「安全」虛擬主機的主機別名呼叫 API Proxy。
發生以下情況時,您通常會修改與 API Proxy 相關聯的虛擬主機:
- 建立新的虛擬主機並擁有現有的 API Proxy。您必須編輯任何現有的 API Proxy,才能新增虛擬主機。
- 建立全新的 API Proxy,無法透過特定虛擬主機存取。您必須編輯 API Proxy,才能移除該虛擬主機的定義。
如要修改與 API Proxy 相關聯的虛擬主機,請按照下列指示操作:
-
存取 API Proxy 編輯器 (說明如下)。
邊緣
如何使用 Edge UI 存取 API Proxy 編輯器:
- 登入 apigee.com/edge。
私有雲客戶的 Edge 會使用
http://ms-ip:9000
(地端部署),其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 - 在左側導覽列中依序選取「開發」>「API Proxy」。
- 在清單中選取要編輯的 API Proxy。
傳統版 Edge (私有雲)
如何使用傳統版 Edge UI 存取 API Proxy 編輯器:
- 登入
http://ms-ip:9000
,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 - 在頂端的導覽列中依序選取「API」>「API Proxy」。
- 在清單中選取要編輯的 API Proxy。
- 登入 apigee.com/edge。
- 按一下「開發」分頁標籤。
- 在「Proxy 端點」下方,選取「預設」。
- 在程式碼區域中:
- 移除 API Proxy 不支援的虛擬主機的任何
<VirtualHost>
元素。 - 新增
<VirtualHost>
元素,並提供新虛擬主機的名稱。舉例來說,如果新虛擬主機的名稱是 MyVirtualHost,請加入下列標記:
<HTTPProxyConnection> <BasePath>/v1/my/proxy/basepath</BasePath> <VirtualHost>default</VirtualHost> <VirtualHost>secure</VirtualHost> <VirtualHost>MyVirtualHost</VirtualHost> </HTTPProxyConnection>
- 移除 API Proxy 不支援的虛擬主機的任何
- 儲存 API Proxy。如果 API Proxy 已完成部署,請儲存設定來使用新的設定重新部署。
為 Edge Proxy 設定 Edge UI 顯示的基準網址
Edge UI 會根據與 Proxy 部署位置對應的虛擬主機設定,顯示 API Proxy 網址。這個螢幕可能包含虛擬主機的路由器通訊埠編號。
在大多數情況下,邊緣 UI 中顯示的網址都是向 Proxy 發出外部要求的正確網址。某些設定中的顯示網址有誤。舉例來說,下列任一設定可能會導致顯示的網址,而非對應到向 Proxy 發出外部要求的實際網址:
- 負載平衡器發生 SSL 終止
- 系統會在負載平衡器和 Apigee 路由器之間進行通訊埠對應
- 已設定路徑重寫的負載平衡器
Edge 支援名為 <BaseUrl>
的虛擬主機上的屬性,可讓您覆寫 Edge UI 顯示的網址。以下是含有 <BaseUrl>
屬性的虛擬主機物件範例。在這個示例中,「http://myCo.com」的值會顯示在 Edge UI 中:
<VirtualHost name="myTLSVHost"> <HostAliases> <HostAlias>api.myCompany.com</HostAlias> </HostAliases> <BaseUrl>http://myCo.com</BaseUrl> <Port>443</Port> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>false</ClientAuthEnabled> <KeyStore>ref://myTestKeystoreRef</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> </SSLInfo> </VirtualHost>
請注意,<BaseUrl>
的值必須包含通訊協定 (例如「http://」或「https://」)。
如未設定 <BaseUrl>
,則 Edge UI 轉譯的預設網址會顯示為「api.myCompany.com」,實際主機別名則為「http://myCo.com」。