您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
具備付費帳戶和所有 Edge for Private Cloud 客戶都能在機構中建立虛擬主機的 Cloud 客戶。建立虛擬主機的使用者必須是機構管理員的角色,或是具備修改虛擬主機權限的自訂角色。其他角色的使用者並沒有建立虛擬主機的授權。
觀看虛擬主辦人的簡介影片。
建立虛擬主機
請按照下列基本程序建立虛擬主機。實際使用的程序會依據您是雲端還是私有雲客戶,以及是否啟用 TLS:
- 為公開的網域建立 DNS 項目和 CNAME 記錄。
- 如果在虛擬主機上啟用傳輸層安全標準 (TLS):
- 按照 Keystore 和 Truststore 的說明,建立及設定 KeyStore。
- 將憑證和金鑰上傳至 KeyStore。請確保憑證指定的網域名稱與要用於虛擬主機的主機別名相符。
- 使用 Edge UI 或 API 建立 KeyStore 的參照。參考資料將 KeyStore 名稱和參照類型指定為
KeyStore
。如要進一步瞭解如何建立及修改參照,請參閱「使用參照」。 - 如果您執行的是雙向傳輸層安全標準 (TLS),請建立信任儲存庫、上傳憑證,然後建立信任存放區的參照。按照以下流程建立信任儲存庫:Keystores 和 Truststore。
- 使用建立虛擬主機 API 建立虛擬主機。啟用 TLS 後,請務必指定正確的 KeyStore 參考資料、信任儲存庫參照和金鑰別名。
- 如果您有現有的 API 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 建立虛擬主機
適用於 Private Cloud 的 Edge 客戶可以透過 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。
- 將 port 號碼指定為 80。如果省略,通訊埠會預設為 443。
您也可以在虛擬主機中設定其他屬性。如需所有屬性的參考資料,請參閱虛擬主機屬性參考資料。
如果您有現有的 API Proxy,請將虛擬主機新增至 Proxy 端點的 <HTTPConnection>
元素。系統會自動將虛擬主機新增至所有新的 API Proxy。
請參閱「設定 API Proxy 以使用虛擬主機」。如果您建立不應透過特定虛擬主機存取的新 API Proxy,就必須編輯 API Proxy,將該虛擬主機從 ProxyEndpoint 中移除。
接著,您可以向以下項目傳送要求,透過這個虛擬主機存取 API Proxy:
http://api.myCompany.com/proxy-base-path/resource-path https://api.myCompany.com/proxy-base-path/resource-path
使用「建立虛擬主機 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 來啟用傳輸層安全標準 (TLS),並使用 <KeyStore>
和 <KeyAliase>
元素指定 TLS 連線使用的 KeyStore 和金鑰別名。
如要進一步瞭解如何使用 TLS,請參閱 TLS/SSL。
決定在虛擬主機中指定 KeyStore 和信任儲存庫名稱的方式
設定支援傳輸層安全標準 (TLS) 的虛擬主機時,必須使用參照來指定 KeyStore。參照是一種包含 KeyStore 或 TrustStore 名稱的變數,而不是直接指定 KeyStore 或信任儲存庫名稱,如下所示:
<SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>false</ClientAuthEnabled> <KeyStore>ref://myTestKeystoreRef</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> </SSLInfo>
使用參照的優點是,您可以變更參照的值來變更虛擬主機使用的 KeyStore,原因通常是因為目前 KeyStore 中的憑證將於近期到期。變更參照值時,不需要重新啟動邊緣路由器。如要進一步瞭解如何建立及修改參照,請參閱「使用參照」。
您只能使用 KeyStore 和 Truststore 的參照,不能使用別名的參照。當您變更 KeyStore 的參照時,請確認憑證的別名名稱與舊的 KeyStore 相同。
使用 KeyStore 和 Truststore 的參照限制
使用 KeyStore 和信任儲存庫的參照時,必須考量下列限制:
- 您必須支援 SNI,並在 Apigee 路由器上終止 SSL,才能在虛擬主機中使用 KeyStore 和 Truststore 參照。
- 如果 Apigee 路由器前方有負載平衡器,且您在負載平衡器上終止 TLS,您就無法在虛擬主機中使用 KeyStore 和 Truststore 參照。
建立雙向傳輸層安全標準 (TLS) 的虛擬主機
如要啟用雙向傳輸層安全標準 (TLS),請將 <ClientAuthEnabled>
元素設為 true
,並使用搭配 <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>
元素指定信任儲存庫的參照。信任儲存庫保存了用戶端的憑證核發者和憑證的 CA 鏈結,為必要項目。
如要進一步瞭解如何使用 TLS,請參閱 TLS/SSL。
修改虛擬主機
具備付費帳戶和所有 Edge for Private Cloud 客戶都能使用 Update a Virtual Host API 來更新虛擬主機的 Cloud 客戶。這個 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 以使用虛擬主機」。
使用 刪除虛擬主機 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,並與虛擬主機建立關聯。如要查看可用憑證的相關資訊,請按照下列步驟操作:
- 在左側導覽列中,依序選取「Admin」>「Environment」>「TLS Keystores」。
- 選取環境 (通常為
prod
或test
)。 - 展開 KeyStore 即可查看憑證。
傳統邊緣 (Private Cloud)
如何使用傳統版 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 指定為「secure」,以查看 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 名稱。
- proxy-base-path 是在建立 API Proxy 時定義,且每個 API Proxy 都有專屬 ID。
- 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
如何使用 Edge UI 存取 API Proxy 編輯器:
- 登入 apigee.com/edge。
私有雲客戶的 Edge 會使用
http://ms-ip:9000
(地端部署),其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 - 在左側導覽列中,依序選取「Develop」(開發) >「API Proxy」。
- 在清單中選取要編輯的 API Proxy。
傳統邊緣 (Private Cloud)
如何使用傳統版 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 已部署,儲存該 Proxy 就會使用新設定重新部署。
為 API Proxy 設定 Edge UI 顯示的基準網址
邊緣 UI 會根據與部署 Proxy 位置相對應的虛擬主機設定,顯示 API Proxy 的網址。這個顯示畫面可包含虛擬主機的路由器通訊埠號碼。
在大多數情況下,Edge 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」。