הגדרת מארחים וירטואליים

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

לקוחות Cloud עם חשבון בתשלום וכל לקוחות Edge for Private Cloud יכולים ליצור מארח וירטואלי בארגון. המשתמש שיוצר את המארח הווירטואלי צריך להיות בעל התפקיד אדמין ארגוני, או תפקיד מותאם אישית עם הרשאות לשינוי מארח וירטואלי. למשתמשים בתפקידים אחרים אין הרשאה ליצור מארחים וירטואליים.

יצירת מארח וירטואלי

כדי ליצור את המארח הווירטואלי, מבצעים את התהליך הבסיסי הבא. ההליך שבו תשתמשו תלוי בשאלה אם אתם לקוחות של Cloud או Private Cloud, וגם בשאלה אם אתם מפעילים TLS:

1. יוצרים רשומת DNS ורשומת CNAME לדומיין שפונה לציבור.
2. אם מפעילים TLS במארח הווירטואלי:
1. יוצרים ומגדירים מאגר מפתחות באמצעות התהליך שמתואר כאן: מאגרי מפתחות ומאגרי אישורים.
2. מעלים את האישור ואת המפתח למאגר המפתחות. מוודאים ששם הדומיין שצוין באישור תואם לכינוי המארח שבו רוצים להשתמש עבור המארח הווירטואלי.
3. יוצרים הפניה למאגר המפתחות באמצעות ממשק המשתמש או ה-API של Edge. ההפניה מציינת את השם של מאגר המפתחות ואת סוג ההפניה כ-KeyStore. מידע נוסף על יצירה ושינוי של הפניות זמין במאמר בנושא עבודה עם הפניות.
4. אם מבצעים TLS דו-כיווני, צריך ליצור מאגר אישורים, להעלות את האישור וליצור הפניה למאגר האישורים. יוצרים את מאגר האישורים באמצעות התהליך שמתואר כאן: Keystores and Truststores (מאגרי מפתחות ומאגרי אישורים).
3. יוצרים את המארח הווירטואלי באמצעות ממשק ה-API‏ Create a Virtual Host. אם מפעילים TLS, צריך לוודא שמציינים את ההפניה הנכונה למאגר המפתחות, ההפניה הנכונה למאגר האישורים והכינוי הנכון למפתח.
4. אם יש לכם שרתי proxy קיימים של API, מוסיפים את המארח הווירטואלי ל-ProxyEndpoint. המארח הווירטואלי נוסף אוטומטית לכל ה-API Proxy החדשים. מידע נוסף זמין במאמר בנושא הגדרת proxy ל-API לשימוש במארח וירטואלי.
   

אחרי שמעדכנים את proxy ל-API לשימוש במארח וירטואלי, ויוצרים את רשומת ה-DNS ורשומת ה-CNAME של הכינוי של המארח, אפשר לגשת ל-proxy ל-API כמו שמוצג בהמשך:

https://api.myCompany.com/v1/project-base-path/resource-path

לדוגמה:

https://api.myCompany.com/v1/weather/forecastrss?w=12797282

יצירת מארח וירטואלי באמצעות ממשק ה-API או ממשק המשתמש

אפשר ליצור מארח וירטואלי באמצעות Edge API או Edge UI.

רוב הדוגמאות שבהמשך מתבססות על Edge API. כדי לגשת לממשק המשתמש כדי ליצור, לשנות ולמחוק מארחים וירטואליים בממשק המשתמש של Edge:

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. משתמשים בשם כדי להפנות למארח הווירטואלי ב-proxy ל-API או בקריאה ל-API.
• מציינים את כינוי המארח בתור api.myCompany.com. זהו הדומיין שפונה לציבור ומשמש לגישה לממשקי ה-API שלכם, כפי שמוגדר בהגדרת DNS וברשומת CNAME.
• מציינים את מספר היציאה כ-80. אם לא מציינים יציאה, ברירת המחדל היא יציאה 443.

• יש נכסים נוספים שאפשר להגדיר במארח הווירטואלי. לעיון בכל המאפיינים, אפשר לעבור אל מאמרי העזרה בנושא מאפיינים של מארח וירטואלי.

אם יש לכם שרתי proxy קיימים של API, מוסיפים את המארח הווירטואלי לרכיב <HTTPConnection> בנקודת הקצה של ה-Proxy. המארח הווירטואלי נוסף אוטומטית לכל ה-API Proxy החדשים. הסבר על הגדרת proxy ל-API לשימוש במארח וירטואלי אם יוצרים proxy ל-API חדש שלא אמורה להיות אליו גישה דרך מארח וירטואלי מסוים, צריך לערוך את ה-proxy ל-API כדי להסיר את המארח הווירטואלי הזה מ-ProxyEndpoint.

לאחר מכן תוכלו לגשת ל-proxy ל-API דרך המארח הווירטואלי הזה על ידי שליחת בקשה אל:

http://api.myCompany.com/proxy-base-path/resource-path
https://api.myCompany.com/proxy-base-path/resource-path

יוצרים את המארח הווירטואלי באמצעות ממשק ה-API‏ Create a Virtual Host:

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>

בהגדרה הזו מפעילים TLS על ידי הגדרת הרכיב <Enable> כ-true, ומשתמשים ברכיבים <KeyStore> ו-<KeyAliase> כדי לציין את מאגר המפתחות ואת הכינוי של המפתח שמשמשים את חיבור ה-TLS.

למידע נוסף על שימוש ב-TLS, ראו TLS/SSL.

החלטה איך לציין את השם של מאגר המפתחות ומאגר האישורים במארח הווירטואלי

כשמגדירים מארח וירטואלי לתמיכה ב-TLS, מציינים מאגר מפתחות באמצעות הפניה. הפניה היא משתנה שמכיל את השם של מאגר המפתחות או מאגר האישורים, במקום לציין את השם של מאגר המפתחות או מאגר האישורים ישירות, כמו בדוגמה הבאה:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>

היתרון בשימוש בהפניה הוא שאפשר לשנות את הערך של ההפניה כדי לשנות את מאגר המפתחות שבו משתמש המארח הווירטואלי, בדרך כלל כי תוקף האישור במאגר המפתחות הנוכחי עומד לפוג בעתיד הקרוב. שינוי הערך של ההפניה לא מחייב הפעלה מחדש של נתב Edge. מידע נוסף על יצירה ושינוי של הפניות זמין במאמר עבודה עם הפניות.

אפשר להשתמש רק בהפניה למאגר המפתחות ולמאגר האישורים, ולא בהפניה לכינוי. כשמשנים את ההפניה למאגר מפתחות, חשוב לוודא ששם הכינוי של האישור זהה לזה שבמאגר המפתחות הישן.

הגבלות על השימוש בהפניות למאגרי מפתחות ולמאגרי אישורים מהימנים

כשמשתמשים בהפניות למאגרי מפתחות ולמאגרי אישורים, צריך להביא בחשבון את ההגבלה הבאה:

• אפשר להשתמש בהפניות למאגר מפתחות ולמאגר אישורים במארחים וירטואליים רק אם אתם תומכים ב-SNI ומסיימים את ה-SSL בנתבי Apigee.
• אם יש לכם מאזן עומסים לפני נתבי Apigee, ואתם מסיימים את ה-TLS במאזן העומסים, אתם לא יכולים להשתמש בהפניות למאגר מפתחות ולמאגר אישורים במארחים וירטואליים.

יצירת מארח וירטואלי ל-TLS דו-כיווני

כדי להפעיל TLS דו-כיווני, מגדירים את הרכיב <ClientAuthEnabled> לערך true, ומציינים מאגר אישורים באמצעות reference עם הרכיב <TrustStore>. מאגר האישורים מכיל את מנפיק האישור של הלקוח ואת שרשרת רשות האישורים של האישור, שנדרשים. בנוסף, צריך להגדיר את הלקוח בצורה נכונה כדי להשתמש ב-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>

בהגדרה הזו:

• כדי להפעיל TLS דו-כיווני, מגדירים את <ClientAuthEnabled> כ-true.
• מציינים את ההפניה למאגר האישורים באמצעות הרכיב <TrustStore>. מאגר האישורים מכיל את מנפיק האישור של הלקוח ואת שרשרת רשות האישורים של האישור, שנדרשים.

למידע נוסף על שימוש ב-TLS, ראו TLS/SSL.

שינוי של מארח וירטואלי

לקוחות Cloud עם חשבון בתשלום וכל לקוחות Edge for Private Cloud יכולים להשתמש ב-API‏ Update a Virtual Host כדי לעדכן מארח וירטואלי. ה-API הזה מאפשר להגדיר את כל המאפיינים של המארח הווירטואלי שמתוארים במאמר הפניה למאפיינים של מארח וירטואלי.

מעדכנים את המארח הווירטואלי באמצעות ה-API של Update a Virtual Host. כשמשתמשים ב-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 לשימוש במארח וירטואלי.

מוחקים את המארח הווירטואלי באמצעות ה-API‏ Delete a Virtual Host:

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/virtualhosts/vhost_name \
  -u orgAdminEmail:password

הצגת מידע על מארח וירטואלי

אפשר להציג מידע על המארחים הווירטואליים שמוגדרים בסביבה, כמו שמתואר בהמשך.

צפייה במארח וירטואלי באמצעות Edge API

אפשר גם להשתמש בממשקי ה-API של Edge כדי להציג מידע על מארחים וירטואליים. לדוגמה, ה-API‏ List Virtual Hosts מחזיר רשימה של כל המארחים הווירטואליים:

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"
]

כדי לראות מידע על מארח וירטואלי ספציפי, משתמשים ב-API‏ Get Virtual Host:

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>

הגדרת proxy ל-API לשימוש במארח וירטואלי

כשיוצרים proxy ל-API חדש, ‏ Edge מגדיר אותו באופן אוטומטי לשימוש בכל המארחים הווירטואליים שזמינים בארגון. בקשה ל-proxy ל-API דרך מארח וירטואלי משתמשת בפורמט:

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

כאשר:

• ‫host-alias הוא בדרך כלל שם ה-DNS של המארח הווירטואלי.
• ‫proxy-base-path מוגדר כשיוצרים proxy ל-API והוא ייחודי לכל proxy ל-API.
• resource-path הנתיב למשאב שאפשר לגשת אליו דרך ה-proxy ל-API.

שליטה במארחים הווירטואליים שמשמשים כ-proxy ל-API

בתצורת ה-XML של שרת proxy ל-API, משתמשים בתג virtualhost כדי לציין את השם של המארח הווירטואלי שמשויך לשרת ה-proxy ל-API:

<HTTPProxyConnection>
  <BasePath>/v1/my/proxy/basepath</BasePath>
  <VirtualHost>secure</VirtualHost>
  <VirtualHost>default</VirtualHost>
</HTTPProxyConnection>

לדוגמה, <VirtualHost>secure</VirtualHost> אומר שהלקוח יכול לקרוא ל-proxy ל-API באמצעות כינוי המארח של המארח הווירטואלי secure.

בדרך כלל משנים את המארחים הווירטואליים שמשויכים ל-proxy ל-API במקרים הבאים:

• אתם יוצרים מארח וירטואלי חדש ויש לכם שרתי proxy קיימים של API. צריך לערוך את כל ה-API proxy הקיים כדי להוסיף את המארח הווירטואלי החדש.
• אתם יוצרים שרת proxy חדש ל-API שאסור שתהיה אליו גישה דרך מארח וירטואלי מסוים. צריך לערוך את ה-proxy ל-API כדי להסיר את המארח הווירטואלי מההגדרה שלו.

כדי לשנות את המארחים הווירטואליים שמשויכים לשרת proxy ל-API:

1. ניגשים לכלי לעריכת שרתי proxy ל-API, כמו שמתואר בהמשך.

   Edge

   כדי לגשת לעורך של proxy ל-API באמצעות ממשק המשתמש של Edge:

   1. נכנסים לחשבון בכתובת apigee.com/edge.

      לקוחות Edge for Private Cloud משתמשים ב-http://ms-ip:9000 (במקום), כאשר ms-ip היא כתובת ה-IP או שם ה-DNS של צומת שרת הניהול.

   2. בסרגל הניווט הימני, בוחרים באפשרות פיתוח > שרתי proxy של API.
   3. בוחרים ברשימה את ה-proxy ל-API שרוצים לערוך.

   ‫Classic Edge (ענן פרטי)

   כדי לגשת לכלי לעריכת proxy ל-API באמצעות ממשק המשתמש הקלאסי של Edge:

   1. מתחברים אל http://ms-ip:9000, כאשר ms-ip היא כתובת ה-IP או שם ה-DNS של צומת שרת הניהול.
   2. בסרגל הניווט העליון, בוחרים באפשרות APIs > API proxies (ממשקי API > שרתי proxy של API).
   3. בוחרים ברשימה את ה-proxy ל-API שרוצים לערוך.
2. לוחצים על הכרטיסייה פיתוח.
3. בקטע נקודות קצה של שרת proxy, בוחרים באפשרות ברירת מחדל.
4. באזור הקוד:
   1. מסירים רכיבי <VirtualHost> עבור מארחים וירטואליים שלא נתמכים על ידי שרת ה-proxy של ה-API.
   2. מוסיפים רכיב <VirtualHost> חדש עם השם של המארח הווירטואלי החדש. לדוגמה, אם המארח הווירטואלי החדש נקרא MyVirtualHost, מוסיפים את התג הבא:
      

      <HTTPProxyConnection>
        <BasePath>/v1/my/proxy/basepath</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
        <VirtualHost>MyVirtualHost</VirtualHost>
      </HTTPProxyConnection>

5. שומרים את ה-proxy ל-API. אם proxy ל-API נפרס, שמירתו תגרום לפריסה מחדש שלו עם ההגדרה החדשה.

הגדרת כתובת ה-URL הבסיסית שמוצגת בממשק המשתמש של Edge ל-proxy ל-API

בממשק המשתמש של Edge מוצגת כתובת ה-URL של proxy ל-API על סמך ההגדרות במארח הווירטואלי שתואם למיקום שבו ה-proxy נפרס. התצוגה הזו יכולה לכלול את מספר היציאה של הנתב של המארח הווירטואלי.

ברוב המקרים, כתובת ה-URL שמוצגת בממשק המשתמש של Edge היא כתובת ה-URL הנכונה לשליחת בקשות חיצוניות ל-proxy. עם זאת, בחלק מההגדרות, כתובת ה-URL שמוצגת לא נכונה. לדוגמה, כל אחת מההגדרות הבאות יכולה לגרום לכך שכתובת ה-URL שמוצגת לא תתאים לכתובת ה-URL בפועל שמשמשת ליצירת בקשות חיצוניות ל-Proxy:

• סיום ה-SSL מתרחש במאזן עומסים
• מיפוי יציאות מתבצע בין מאזן עומסים לבין נתבי Apigee
• מאזן עומסים שהוגדר עם שכתוב נתיבים

‫Edge תומך במאפיין במארח הווירטואלי שנקרא <BaseUrl>, שמאפשר לכם לשנות את כתובת ה-URL שמוצגת בממשק המשתמש של Edge. בדוגמה הבאה מוצג אובייקט של מארח וירטואלי עם המאפיין <BaseUrl>. בדוגמה הזו, הערך http://myCo.com מופיע בממשק המשתמש של Edge:

<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>, כתובת ה-URL שמוצגת בממשק המשתמש של Edge תהיה כתובת ברירת המחדל: api.myCompany.com, אבל הכינוי בפועל של המארח הוא http://myCo.com.