設定虛擬主機

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

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

觀看虛擬主機簡介影片。

建立虛擬主機

請按照下列基本程序建立虛擬主機。您實際採用的程序取決於您是 Cloud 或 Private Cloud 客戶，以及是否啟用 TLS：

  1. 為公開網域建立 DNS 項目和 CNAME 記錄。
  2. 如果在虛擬主機上啟用 TLS：
    1. 請按照「KeyStore 和 TrustStore」一文所述的程序建立及設定 KeyStore。
    2. 將憑證和金鑰上傳至 KeyStore。請確認憑證指定的網域名稱與您要用於虛擬主機的主機別名相符。
    3. 使用 Edge UI 或 API 建立金鑰庫參照。參照會指定金鑰庫的名稱，並將參照類型設為 KeyStore。如要進一步瞭解如何建立及修改參照，請參閱「使用參照」。
    4. 如果您要執行雙向 TLS，請建立信任存放區、上傳憑證，然後建立信任存放區的參照。請按照「KeyStore 和 TrustStore」一文所述的程序建立 TrustStore。
  3. 使用「Create a Virtual Host」API 建立虛擬主機。如果要啟用 TLS，請務必指定正確的 KeyStore 參照、信任區參照和金鑰別名。
  4. 如果您有任何現有的 API Proxy，請將虛擬主機新增至 ProxyEndpoint。系統會自動將虛擬主機新增至所有新的 API 代理程式。請參閱設定 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 for Private Cloud 客戶使用 http://ms-ip:9000 (內部部署)，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。

  2. 在左側導覽列中，依序選取「管理」>「虛擬主機」。
  3. 選取環境，例如「prod」或「test」。
    系統會顯示為環境定義的虛擬主機。
  4. 選取「+ 虛擬主機」建立虛擬主機，或選取現有虛擬主機的名稱進行編輯。

為 HTTP 建立虛擬主機

Edge for Private Cloud 客戶可以使用 HTTP 建立虛擬主機。

如要建立不支援 TLS 的虛擬主機，請建立定義虛擬主機的 XML 物件。舉例來說，以下 XML 物件會定義使用 HTTP 通訊協定的虛擬主機：

<VirtualHost name="myVHost">
   <HostAliases>
     <HostAlias>api.myCompany.com</HostAlias>
   </HostAliases>
   <Interfaces/>
   <Port>80</Port>
</VirtualHost>

在這個定義中，您可以：

  • 將名稱指定為 myVHost。使用這個名稱，在 API 代理程式或 API 呼叫中參照虛擬主機。
  • 請將主機別名指定為 api.myCompany.com。這是公開網域，可用於存取 DNS 定義和 CNAME 記錄中定義的 API。
  • 將「通訊埠」編號設為 80。如果省略，系統會預設將通訊埠設為 443。

  • 您也可以在虛擬主機中設定其他屬性。如需所有屬性的參考資料，請參閱虛擬主機屬性參考資料。

如果您有任何現有的 API Proxy，請將虛擬主機新增至 Proxy Endpoint 中的 <HTTPConnection> 元素。系統會自動將虛擬主機新增至所有新的 API 代理程式。請參閱「設定 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

使用「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 來啟用 TLS，並使用 <KeyStore> 和 <KeyAliase> 元素指定 TLS 連線使用的 KeyStore 和金鑰別名。

如要進一步瞭解如何使用 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 中的憑證即將到期。變更參照值時，您不需要重新啟動 Edge Router。如要進一步瞭解如何建立及修改參照，請參閱「使用參照」。

您只能使用金鑰庫和信任庫的參照，無法使用別名的參照。變更參照至 Keystore 的連結時，請確認憑證的別名名稱與舊 Keystore 中的相同。

使用金鑰庫和信任存放區參照的限制

使用金鑰庫和信任庫參照時，請務必考量下列限制：

  • 您必須支援 SNI，並在 Apigee Router 上終止 SSL，才能在虛擬主機中使用金鑰庫和信任庫參照。
  • 如果 Apigee Router 前方有負載平衡器，且您在負載平衡器上終止 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」。

修改虛擬主機

擁有付費帳戶的 Cloud 客戶和所有 Edge for Private Cloud 客戶，都可以使用「 Update a Virtual Host」API 更新虛擬主機。這個 API 可讓您為虛擬主機設定所有屬性，請參閱「虛擬主機屬性參考資料」一節。

請使用 Update a Virtual Host 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

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

  1. 登入 apigee.com/edge。

    Edge for Private Cloud 客戶使用 http://ms-ip:9000 (內部部署)，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。

  2. 在左側導覽列中，依序選取「管理」>「虛擬主機」。
  3. 選取環境，例如「prod」或「test」。

    為環境定義的虛擬主機會顯示出來。如果虛擬主機已設定為使用金鑰庫或信任庫，請按一下「Show」查看更多資訊。

如果虛擬主機已設定為使用 TLS/SSL，虛擬主機名稱旁會顯示鎖頭圖示。這表示 TLS/SSL 憑證、金鑰和憑證鏈結已上傳至 Edge，並與虛擬主機建立關聯。如要查看可用憑證的相關資訊，請按照下列步驟操作：

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

Classic Edge (Private Cloud)

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

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

    為環境定義的虛擬主機會顯示出來。如果虛擬主機已設定為使用金鑰庫或信任庫，請按一下「Show」查看更多資訊。

    「Virtual Hosts」分頁會顯示名稱、通訊埠和別名等資訊。

如果虛擬主機已設定為使用 TLS/SSL，虛擬主機名稱旁會顯示鎖頭圖示。這表示 TLS/SSL 憑證、金鑰和憑證鏈結已上傳至 Edge，並與虛擬主機建立關聯。如要查看可用憑證的相關資訊，請按照下列步驟操作：

  1. 依序選取頂端導覽列中的「管理」>「TLS 憑證」。
  2. 選取環境 (通常為 prod 或 test)。
  3. 展開金鑰庫即可查看憑證。

使用 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 代理程式時，Edge 會自動將其設定為使用機構中所有可用的虛擬主機。透過虛擬主機向 API Proxy 提出要求時，請使用以下格式：

https://host-alias/proxy-base-path/resource-path

在此情況下：

  • host-alias 通常是虛擬主機的 DNS 名稱。
  • proxy-base-path 是在建立 API Proxy 時定義，且每個 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> 表示用戶端可以使用「secure」虛擬主機的主機別名呼叫 API Proxy。

您通常會在下列情況下修改與 API Proxy 相關聯的虛擬主機：

  • 您建立新的虛擬主機，並有現有的 API Proxy。您必須編輯現有的 API 代理程式，才能新增新的虛擬主機。
  • 您建立的新 API Proxy 不應透過特定虛擬主機存取。您必須編輯 API 代理程式，才能從其定義中移除該虛擬主機。

如要修改與 API Proxy 相關聯的虛擬主機，請按照下列步驟操作：

  1. 如要存取 API 代理編輯器，請按照下列說明操作。

    Edge

    如要使用 Edge UI 存取 API Proxy 編輯器，請按照下列步驟操作：

    1. 登入 apigee.com/edge。

      Edge for Private Cloud 客戶使用 http://ms-ip:9000 (內部部署)，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。

    2. 在左側導覽列中，依序選取「Develop」>「API proxies」。
    3. 在清單中選取要編輯的 API 代理。

    Classic Edge (Private Cloud)

    如要使用 Edge 傳統版 UI 存取 API Proxy 編輯器，請按照下列步驟操作：

    1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
    2. 在頂端導覽列中，依序選取「API」>「API 代理程式」。
    3. 在清單中選取要編輯的 API 代理。
  2. 按一下「開發」分頁標籤。
  3. 在「Proxy Endpoints」(Proxy Endpoints) 下方，選取「default」(預設)。
  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，儲存該 Proxy 會以新設定重新部署。

設定 Edge UI 為 API Proxy 顯示的基準網址

Edge UI 會根據虛擬主機中與 Proxy 部署位置相對應的設定，顯示 API Proxy 的網址。這項資訊可包含虛擬主機的路由器通訊埠編號。

在大多數情況下，Edge UI 中顯示的網址是向 Proxy 提出外部要求的正確網址。不過，在某些設定下，顯示的網址會不正確。舉例來說，下列任一設定都可能導致顯示的網址與用於向 Proxy 提出外部要求的實際網址不符：

  • 安全資料傳輸層 (SSL) 終止作業會在負載平衡器上執行
  • 負載平衡器和 Apigee Router 之間會進行通訊埠對應
  • 已設定路徑重寫功能的負載平衡器

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」。