設定虛擬主機

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。

如果 Cloud 客戶使用付費帳戶，且所有 Edge for Private Cloud 客戶都能在機構中建立虛擬主機，建立虛擬主機的使用者必須具備機構管理員的角色，或是具備修改虛擬主機權限的自訂角色。其他角色的使用者沒有建立虛擬主機的權限。

觀看虛擬主機簡介影片。

建立虛擬主機

請使用下列基本程序建立虛擬主機。 實際執行的程序取決於您是 Cloud 還是私有雲客戶，以及是否啟用傳輸層安全標準 (TLS)：

  1. 為公開網域建立 DNS 項目和 CNAME 記錄。
  2. 啟用虛擬主機的傳輸層安全標準 (TLS) 功能：
    1. 按照這裡所述的程序建立及設定 KeyStore：KeyStores 和 Truststores。
    2. 將憑證和金鑰上傳至 KeyStore。確保憑證指定的網域名稱與您要用於虛擬主機的主機別名相符。
    3. 使用 Edge UI 或 API 建立 KeyStore 參照。該參考資料會將 KeyStore 名稱和參照類型指定為 KeyStore。如要進一步瞭解如何建立及修改參照，請參閱「使用參考檔案」。
    4. 如果您執行雙向傳輸層安全標準 (TLS)，請建立信任儲存庫、上傳憑證，然後建立信任存放區的參照。按照「Keystores and Truststores」所述的程序建立信任儲存庫。
  3. 使用建立虛擬主機 API 建立虛擬主機。啟用傳輸層安全標準 (TLS) 時，請務必指定正確的 KeyStore 參照、信任儲存庫參照和金鑰別名。
  4. 如有任何現有的 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 中建立、修改及刪除虛擬主機：

  1. 登入 apigee.com/edge

    私有雲客戶的 Edge 會使用 http://ms-ip:9000 (地端部署)，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。

  2. 依序選取左側導覽列中的「Admin」(虛擬) >「Virtual Hosts」(虛擬主機)。
  3. 選取環境，例如「prod」或「test」。
    系統會隨即顯示為環境定義的虛擬主機。
  4. 選取「+ 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 查看虛擬主機的相關資訊：

  1. 登入 apigee.com/edge。

    私有雲客戶的 Edge 會使用 http://ms-ip:9000 (地端部署)，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。

  2. 依序選取左側導覽列中的「Admin」(虛擬) >「Virtual Hosts」(虛擬主機)。
  3. 選取環境，例如「prod」或「test」。

    系統會針對環境定義的虛擬主機顯示。如果虛擬主機已設為使用 KeyStore 或 Truststore，請按一下「Show」即可查看更多資訊。

如果虛擬主機設定為使用傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL)，則會在虛擬主機名稱旁邊顯示鎖頭圖示。代表傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 憑證、金鑰和憑證鏈結已上傳到 Edge，並連結至虛擬主機。如要查看可用憑證的相關資訊，請按照下列步驟操作：

  1. 在左側導覽列中，依序選取「管理」>「環境」>「TLS KeyStore」。
  2. 選取環境 (通常為 prod 或 test)。
  3. 展開 KeyStore 即可查看憑證。

傳統版 Edge (私有雲)

如要使用傳統版 Edge UI 查看虛擬主機的相關資訊，請按照下列步驟操作：

  1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
  2. 依序選取左側導覽列中的「Admin」(虛擬) >「Virtual Hosts」(虛擬主機)。
  3. 選取環境，例如「prod」或「test」。
  4. 按一下「Virtual Hosts」分頁標籤。

    系統會針對環境定義的虛擬主機顯示。如果虛擬主機已設為使用 KeyStore 或 Truststore，請按一下「Show」即可查看更多資訊。

    「Virtual Hosts」(虛擬主機) 分頁會顯示名稱、通訊埠和別名等資訊。

如果虛擬主機設定為使用傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL)，則會在虛擬主機名稱旁邊顯示鎖頭圖示。代表傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 憑證、金鑰和憑證鏈結已上傳到 Edge，並連結至虛擬主機。如要查看可用憑證的相關資訊，請按照下列步驟操作：

  1. 在頂端導覽列選取「管理」>「傳輸層安全標準 (TLS) 憑證」。
  2. 選取環境 (通常為 prod 或 test)。
  3. 展開 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 相關聯的虛擬主機，請按照下列指示操作：

  1. 存取 API Proxy 編輯器 (說明如下)。

    邊緣

    如何使用 Edge UI 存取 API Proxy 編輯器：

    1. 登入 apigee.com/edge。

      私有雲客戶的 Edge 會使用 http://ms-ip:9000 (地端部署)，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。

    2. 在左側導覽列中依序選取「開發」>「API Proxy」。
    3. 在清單中選取要編輯的 API Proxy。

    傳統版 Edge (私有雲)

    如何使用傳統版 Edge UI 存取 API Proxy 編輯器：

    1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
    2. 在頂端的導覽列中依序選取「API」>「API Proxy」。
    3. 在清單中選取要編輯的 API Proxy。
  2. 按一下「開發」分頁標籤。
  3. 在「Proxy 端點」下方，選取「預設」。
  4. 在程式碼區域中：
    1. 移除 API Proxy 不支援的虛擬主機的任何 <VirtualHost> 元素。
    2. 新增 <VirtualHost> 元素，並提供新虛擬主機的名稱。舉例來說，如果新虛擬主機的名稱是 MyVirtualHost，請加入下列標記：
      <HTTPProxyConnection>
  <BasePath>/v1/my/proxy/basepath</BasePath>
  <VirtualHost>default</VirtualHost>
  <VirtualHost>secure</VirtualHost>
  <VirtualHost>MyVirtualHost</VirtualHost>
</HTTPProxyConnection>
  5. 儲存 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」。