設定虛擬主機

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

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

觀看虛擬主辦人的簡介影片。

建立虛擬主機

請按照下列基本程序建立虛擬主機。實際使用的程序會依據您是雲端還是私有雲客戶,以及是否啟用 TLS:

  1. 為公開的網域建立 DNS 項目和 CNAME 記錄。
  2. 如果在虛擬主機上啟用傳輸層安全標準 (TLS):
    1. 按照 Keystore 和 Truststore 的說明,建立及設定 KeyStore。
    2. 將憑證和金鑰上傳至 KeyStore。請確保憑證指定的網域名稱與要用於虛擬主機的主機別名相符。
    3. 使用 Edge UI 或 API 建立 KeyStore 的參照。參考資料將 KeyStore 名稱和參照類型指定為 KeyStore。如要進一步瞭解如何建立及修改參照,請參閱「使用參照」。
    4. 如果您執行的是雙向傳輸層安全標準 (TLS),請建立信任儲存庫、上傳憑證,然後建立信任存放區的參照。按照以下流程建立信任儲存庫:Keystores 和 Truststore
  3. 使用建立虛擬主機 API 建立虛擬主機。啟用 TLS 後,請務必指定正確的 KeyStore 參考資料、信任儲存庫參照和金鑰別名。
  4. 如果您有現有的 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 中建立、修改及刪除虛擬主機,請按照下列步驟操作:

  1. 登入 apigee.com/edge

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

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

  1. 登入 apigee.com/edge

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

  2. 在左側導覽列中,依序選取「Admin」>「Virtual Hosts」
  3. 選取環境,例如 prodtest

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

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

  1. 在左側導覽列中,依序選取「Admin」>「Environment」>「TLS Keystores」
  2. 選取環境 (通常為 prodtest)。
  3. 展開 KeyStore 即可查看憑證。

傳統邊緣 (Private Cloud)

如何使用傳統版 Edge UI 查看虛擬主機的相關資訊:

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

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

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

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

  1. 依序選取頂端導覽列的「管理員」>「TLS 憑證」
  2. 選取環境 (通常為 prodtest)。
  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 指定為「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 相關聯的虛擬主機:

  1. 存取 API Proxy 編輯器,方法如下所示。

    Edge

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

    1. 登入 apigee.com/edge

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

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

    傳統邊緣 (Private Cloud)

    如何使用傳統版 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 已部署,儲存該 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」。