Megosztás a következőn keresztül:

Névvel ellátott értékek használata az Azure API Management-szabályzatokban

ÉRVÉNYES: Minden API Management rétegre

Az API Management-szabályzatok a rendszer hatékony funkciói, amelyek lehetővé teszik a közzétevő számára, hogy konfiguráción keresztül módosítsa az API viselkedését. A szabályzatok olyan utasítások gyűjteményei, amelyeket az API egyes kéréseire vagy válaszaira egymást követően hajtanak végre. A házirend-utasítások konstans szöveges értékek, szabályzatkifejezések és elnevezett értékek használatával hozhatók létre.

Az elnevezett értékek az egyes API Management-példányokban található név-érték párok globális gyűjteményei. Az elnevezett értékekkel konstans sztringértékeket és titkos kódokat kezelhet minden API-konfigurációban és szabályzatban.

Elnevezett értékek az Azure Portalon

Értéktípusok

Típus Leírás
Egyszerű Literális karakterlánc vagy szabályzatkifejezés
Titok Az API Management által titkosított literális sztring vagy szabályzatkifejezés
Kulcstároló Egy Azure-kulcstartóban tárolt titkos kód azonosítója.

Az egyszerű értékek vagy titkos kódok szabályzatkifejezéseket tartalmazhatnak. A kifejezés @(DateTime.Now.ToString()) például egy sztringet ad vissza, amely az aktuális dátumot és időt tartalmazza.

A névvel ellátott értékattribútumokról az API Management REST API-referenciában talál további információt.

Kulcstartó titkai

A titkos értékek titkosított sztringekként tárolhatók az API Managementben (egyéni titkos kódok), vagy hivatkozhatnak titkos kulcsokra az Azure Key Vaultban.

A Key Vault titkos kulcsok használatát javasoljuk, mert ezek segítenek az API Management biztonságának javításában:

Feljegyzés

A key vaulttal való integráció jelenleg nem érhető el a munkaterületeken.

  • A kulcstartókban tárolt titkos kulcsokat több szolgáltatásban is felhasználhatja.
  • Részletes hozzáférési szabályzatokat alkalmazhat titkos kódokra.
  • A kulcstárban frissített titkok automatikusan rotálódnak az API-kezelésben. A key vault frissítése után az API Management egy elnevezett értéke négy órán belül frissül. A titkos kód manuálisan is frissíthető az Azure Portalon vagy a felügyeleti REST API-val.

Feljegyzés

Az Azure Key Vaultban tárolt titkos kódoknak 1 és 4096 karakter közöttinek kell lenniük, mivel az API Management nem tudja lekérni azokat az értékeket, amelyek túllépik ezt a korlátot.

Előfeltételek

A Key Vault integrációjának előfeltételei

Feljegyzés

Ez a funkció jelenleg nem érhető el a munkaterületeken.

A Key Vaulthoz való hozzáférés konfigurálása

  1. A portálon nyissa meg a kulcstárat.
  2. A bal oldali menüben válassza a Beállítások>hozzáférés konfigurációja lehetőséget. Jegyezze fel a konfigurált engedélymodellt .
  3. Az engedélymodelltől függően konfiguráljon kulcstartó-hozzáférési szabályzatot vagy Azure RBAC-hozzáférést egy API Management által felügyelt identitáshoz.

Kulcstár hozzáférési szabályzatának hozzáadása:

  1. A bal oldali menüben válassza az Access-szabályzatok lehetőséget.
  2. Az Access-szabályzatok lapon válassza a + Létrehozás lehetőséget.
  3. Az Engedélyek lap Titkos engedélyek csoportjában válassza a Beolvasás és a Lista lehetőséget, majd a Tovább lehetőséget.
  4. Az Egyszerű lapon keresse meg a felügyelt identitás erőforrásnevét, majd válassza a Tovább gombot. Ha rendszer által hozzárendelt identitást használ, a fő felhasználó az API Management-példány neve.
  5. Kattintson ismét a Tovább gombra. A Véleményezés + létrehozás lapon válassza a Létrehozás lehetőséget.

Az Azure RBAC-hozzáférés konfigurálása:

  1. A bal oldali menüben válassza a Hozzáférés-vezérlés (IAM) lehetőséget.
  2. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelés hozzáadása lehetőséget.
  3. A Szerepkör lapon válassza a Key Vault titkos kulcsainak felhasználója, majd a Tovább gombot.
  4. A Tagok lapon válassza a Kezelt identitás>+ Tagok kiválasztása lehetőséget.
  5. A Felügyelt identitás kiválasztása lapon válassza ki a rendszer által hozzárendelt felügyelt identitást vagy az API Management-példányhoz társított felhasználó által hozzárendelt felügyelt identitást, majd válassza a Kiválasztás lehetőséget.
  6. Válassza az Áttekintés + hozzárendelés lehetőséget.

A Key Vault tűzfalának követelményei

Ha a Key Vault tűzfala engedélyezve van a kulcstartón, az alábbi követelményeknek kell megfelelnie:

  • A kulcstár eléréséhez az API Management példány rendszer által hozzárendelt felügyelt identitását kell használnia.

  • Győződjön meg arról, hogy az API Management példányod hálózati rálátással rendelkezzen a kulcstárra. A forgatókönyvtől függően konfigurálja a következő hálózati hozzáférési lehetőségek egyikét a kulcstartón:

    • Nyilvános hozzáférés engedélyezése az összes hálózatból.

    • Állítson be egy hálózati biztonsági szabályt, amely engedélyezi az API Management-forgalmat az IP-cím vagy a virtuális hálózati kapcsolat alapján.

    • Biztonságossá teheti a forgalmat az API Managementből privát kapcsolattal.

    • A kulcstartó biztonságossá tételéhez és az API Managementből érkező forgalom engedélyezéséhez használjon hálózati biztonsági szegélyt .

  • Győződjön meg arról, hogy a helyi ügyfél IP-címe átmenetileg hozzáférhet a kulcstartóhoz, miközben kiválaszt egy tanúsítványt vagy titkos kulcsot, amelyet fel szeretne adni az Azure API Managementbe. További információ: Az Azure Key Vault hálózati beállításainak konfigurálása.

    A konfiguráció befejezése után letilthatja az ügyfél címét a Key Vault tűzfalán.

Fontos

2026 márciusától az API Managementből az Azure Key Vaulthoz létrehozott megbízható szolgáltatáskapcsolatokat nem fogják támogatni, ha engedélyezik a Megbízható Microsoft-szolgáltatások számára a tűzfal megkerülését a kulcstartó tűzfalbeállításának segítségével. Ha a módosítás után is használni szeretné a Key Vaultot az API Management szolgáltatással, győződjön meg arról, hogy a fent leírtak szerint egy támogatott hálózati hozzáférési lehetőséget választ. További információ.

A virtuális hálózatra vonatkozó követelmények

Ha az API Management-példány virtuális hálózaton van üzembe helyezve, konfigurálja a következő hálózati beállításokat is:

  • Engedélyezze a szolgáltatási végpontot a Key Vaulthoz az API Management alhálózaton.
  • Konfiguráljon egy hálózati biztonsági csoportot (NSG- szabályt) az AzureKeyVault és az AzureActiveDirectory szolgáltatáscímkék kimenő forgalmának engedélyezéséhez.

További információ: Hálózati konfiguráció az API Management virtuális hálózaton való beállításakor.

Névvel ellátott érték hozzáadása vagy szerkesztése

Kulcstár-titok hozzáadása az API Managementhez

Tekintse meg a Key Vault integrációjának előfeltételeit.

Fontos

Amikor kulcstartó-titkos kulcsot ad hozzá az API Management-példányhoz, rendelkeznie kell a kulcstartó titkos kulcsainak listázásához szükséges engedélyekkel.

Figyelemfelhívás

Ha kulcstartó-titkos kulcsot használ az API Managementben, ügyeljen arra, hogy ne törölje a kulcstartó eléréséhez használt titkos kulcsot, kulcstartót vagy felügyelt identitást.

  1. Az Azure Portalon keresse meg az API Management-példányt.

  2. Az API-k alatt válassza az Elnevezett értékek>+ Hozzáadás lehetőséget.

  3. Adjon meg egy névazonosítót, és adjon meg egy megjelenítendő nevet, amellyel a házirendekben hivatkozhat a tulajdonságra.

  4. Adjon hozzá egy vagy több választható címkét a névvel ellátott értékek rendszerezéséhez.

  5. A Típus legördülő listában válassza a Key Vault lehetőséget.

  6. Adja meg a kulcstartó titkának azonosítóját (verzió nélkül), vagy válassza a Kiválasztás lehetőséget, hogy kiválasszon egy titkot egy kulcstartóból.

    Fontos

    Ha saját maga adja meg a key vault titkos azonosítóját, győződjön meg arról, hogy nem rendelkezik verzióinformációval. Ellenkező esetben a titkos kód nem forog automatikusan az API Managementben a kulcstartó frissítését követően.

  7. Az ügyfélidentitásban válasszon ki egy rendszer által hozzárendelt vagy egy meglévő, felhasználó által hozzárendelt felügyelt identitást. Megtudhatja, hogyan vehet fel vagy módosíthat felügyelt identitásokat az API Management szolgáltatásban.

    Feljegyzés

    Az identitásnak engedélyekre van szüksége a kulcstár titkainak lekéréséhez és listázásához. Ha még nem konfigurálta a kulcstartóhoz való hozzáférést, az API Management kéri, hogy automatikusan konfigurálhassa az identitást a szükséges engedélyekkel.

  8. Válassza a Mentés lehetőséget, majd válassza a Létrehozás lehetőséget.

    Kulcstár kulcsérték hozzáadása

Egyszerű vagy titkos érték hozzáadása az API Managementhez

  1. Az Azure Portalon keresse meg az API Management-példányt.
  2. Az API-k alatt válassza az Elnevezett értékek>+Hozzáadás lehetőséget.
  3. Adjon meg egy névazonosítót, és adjon meg egy megjelenítendő nevet, amellyel a házirendekben hivatkozhat a tulajdonságra.
  4. A Típus legördülő listában válassza az Egyszerű vagy a Titkos elemet.
  5. Az Érték mezőbe írjon be egy sztringet vagy egy szabályzatkifejezést.
  6. Adjon hozzá egy vagy több választható címkét a nevezett értékek rendszerezéséhez, majd mentse el.
  7. Válassza a Létrehozás lehetőséget.

A névvel ellátott érték létrehozása után a név kiválasztásával szerkesztheti azt. Ha módosítja a megjelenített nevet, a névvel ellátott értékre hivatkozó házirendek automatikusan frissülnek az új megjelenítendő név használatára.

Névvel ellátott érték használata

Az ebben a szakaszban szereplő példák az alábbi táblázatban látható elnevezett értékeket használják.

Név Érték Titok
ContosoHeader TrackingId Hamis
ContosoHeaderValue •••••••••••••••••••••• Igaz
ExpressionProperty @(DateTime.Now.ToString()) Hamis
ContosoHeaderValue2 This is a header value. Hamis

Ha elnevezett értéket szeretne használni egy szabályzatban, helyezze a megjelenítendő nevét egy dupla zárójelpárba, például {{ContosoHeader}}a következő példában látható módon:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

Ebben a példában ContosoHeader a szabályzat fejlécének set-header neveként használatos, és ContosoHeaderValue az adott fejléc értékeként használatos. Amikor ezt a szabályzatot kiértékeli a rendszer az API Management átjáróhoz irányuló kérés vagy válasz során, az {{ContosoHeader}} és {{ContosoHeaderValue}} helyére a megfelelő értékek kerülnek.

Az elnevezett értékeket teljes attribútumként vagy elemértékként is használhatja az előző példában látható módon, de beszúrhatók vagy kombinálhatók egy literális szövegkifejezés egy részével is, ahogyan az alábbi példában látható:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

A névvel ellátott értékek szabályzatkifejezéseket is tartalmazhatnak. Az alábbi példában a ExpressionProperty kifejezés használatos.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Amikor ezt a szabályzatot kiértékelik, {{ExpressionProperty}}-t lecserélik annak értékére, @(DateTime.Now.ToString()). Mivel az érték egy szabályzatkifejezés, a rendszer kiértékeli a kifejezést, és a szabályzat végrehajtása folytatódik.

Ezt az Azure Portalon vagy a fejlesztői portálon tesztelheti úgy, hogy meghív egy olyan műveletet, amelynek szabályzata nevesített értékekkel rendelkezik a hatókörben. Az alábbi példában a rendszer meghív egy műveletet az előző két példaszabályzattal set-header nevesített értékekkel. Figyelje meg, hogy a válasz két egyéni fejlécet tartalmaz, amelyek nevesített értékekkel rendelkező szabályzatok használatával lettek konfigurálva.

Képernyőkép a Test API-válaszról.

Ha egy olyan hívás kimenő API-nyomkövetését tekinti meg, amely tartalmazza a két korábbi, névvel ellátott mintaszabályzatot, láthatja a két set-header szabályzatot a beszúrt névvel ellátott értékekkel, valamint a szabályzatkifejezést tartalmazó névvel ellátott érték szabályzatkifejezés-kiértékelését.

Képernyőkép egy API Inspector-nyomkövetésről.

Sztring interpolációt is használhat nevesített értékekkel.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

A CustomHeader értéke The URL encoded value is This+is+a+header+value. lesz.

Figyelemfelhívás

Ha egy szabályzat egy titkos kódra hivatkozik az Azure Key Vaultban, a kulcstartóból származó érték azon felhasználók számára látható, akik hozzáférnek az API-kérések nyomon követéséhez engedélyezett előfizetésekhez.

Bár a névvel ellátott értékek tartalmazhatnak szabályzatkifejezéseket, más elnevezett értékeket nem tartalmazhatnak. Ha névvel ellátott értékhivatkozást tartalmazó szöveget használ egy értékhez, például Text: {{MyProperty}}, a hivatkozás nem lesz feloldva és lecserélve.

Névvel ellátott érték törlése

Névvel ellátott érték törléséhez jelölje ki a nevet, majd válassza a Törlés lehetőséget a helyi menüből (...).

Fontos

Ha az elnevezett értékre bármely API Management-szabályzat hivatkozik, nem törölheti, amíg el nem távolítja az elnevezett értéket az azt használó összes szabályzatból.

Kapcsolódó tartalom

További információ a szabályzatok használatával kapcsolatban:

  • Last updated on