Share via

Azure API Management ilkelerinde adlandırılmış değerleri kullanma

  • Makale

UYGULANANLAR: Tüm API Management katmanları

API Management ilkeleri , yayımcının yapılandırma aracılığıyla API'nin davranışını değiştirmesine olanak sağlayan güçlü bir sistem özelliğidir. İlkeler, bir API isteği veya yanıtı üzerinde sırayla yürütülen deyimlerin bir koleksiyonudur. İlke deyimleri değişmez metin değerleri, ilke ifadeleri ve adlandırılmış değerler kullanılarak oluşturulabilir.

Adlandırılmış değerler , her API Management örneğindeki ad/değer çiftlerinden oluşan genel bir koleksiyonlardır. Koleksiyondaki öğe sayısına uygulanan bir sınır yoktur. Adlandırılmış değerler, tüm API yapılandırmaları ve ilkeleri genelinde sabit dize değerlerini ve gizli dizileri yönetmek için kullanılabilir.

Azure portalında adlandırılmış değerler

Değer türleri

Type Açıklama
Düz Değişmez değer dizesi veya ilke ifadesi
Gizli dizi API Management tarafından şifrelenen değişmez dize veya ilke ifadesi
Anahtar kasası Azure anahtar kasasında depolanan gizli dizi tanımlayıcısı.

Düz değerler veya gizli diziler ilke ifadeleri içerebilir. Örneğin, ifade @(DateTime.Now.ToString()) geçerli tarih ve saati içeren bir dize döndürür.

Adlandırılmış değer öznitelikleri hakkında ayrıntılı bilgi için bkz. API Management REST API başvurusu.

Anahtar kasası gizli dizileri

Gizli dizi değerleri API Management'ta şifrelenmiş dizeler olarak (özel gizli diziler) veya Azure Key Vault'taki gizli dizilere başvurarak depolanabilir.

API Management güvenliğini iyileştirmeye yardımcı olduğundan anahtar kasası gizli dizilerinin kullanılması önerilir:

  • Anahtar kasalarında depolanan gizli diziler hizmetler arasında yeniden kullanılabilir
  • Gizli dizilere ayrıntılı erişim ilkeleri uygulanabilir
  • Anahtar kasasında güncelleştirilen gizli diziler API Management'ta otomatik olarak döndürülür. Anahtar kasasında güncelleştirmeden sonra API Management'taki adlandırılmış bir değer 4 saat içinde güncelleştirilir. Ayrıca Azure portalını veya yönetim REST API'sini kullanarak gizli diziyi el ile yenileyebilirsiniz.

Önkoşullar

Anahtar kasası tümleştirmesi için önkoşullar

Anahtar kasasına erişimi yapılandırma

  1. Portalda anahtar kasanıza gidin.

  2. Sol menüde Erişim yapılandırması'nı seçin ve yapılandırılan İzin modelini not edin.

  3. İzin modeline bağlı olarak, API Management yönetilen kimliği için bir anahtar kasası erişim ilkesi veya Azure RBAC erişimi yapılandırın.

    Anahtar kasası erişim ilkesi eklemek için:

    1. Sol menüde Erişim ilkeleri'ni seçin.
    2. Erişim ilkeleri sayfasında + Oluştur'u seçin.
    3. İzinler sekmesindeki Gizli dizi izinleri'nin altında Al ve Listele'yi ve ardından İleri'yi seçin.
    4. Sorumlu sekmesinde Sorumluyu seçin, yönetilen kimliğinizin kaynak adını arayın ve İleri'yi seçin. Sistem tarafından atanan bir kimlik kullanıyorsanız, sorumlu API Management örneğinizin adıdır.
    5. İleri'yi yeniden seçin. Gözden Geçir + oluştur sekmesinde Oluştur'u seçin.

    Azure RBAC erişimini yapılandırmak için:

    1. Sol menüde Erişim denetimi (IAM) öğesini seçin.
    2. Erişim denetimi (IAM) sayfasında Rol ataması ekle'yi seçin.
    3. Rol sekmesinde Key Vault Sertifika Kullanıcısı'nı seçin.
    4. Üyeler sekmesinde Yönetilen kimlik>+ Üye seç'i seçin.
    5. Yönetilen kimliği seçin sayfasında, API Management örneğiniz ile ilişkilendirilmiş sistem tarafından atanan yönetilen kimliği veya kullanıcı tarafından atanan yönetilen kimliği seçin ve ardından Seç'i seçin.
    6. Gözden geçir + ata'yı seçin.

Key Vault güvenlik duvarı gereksinimleri

Anahtar kasanızda Key Vault güvenlik duvarı etkinleştirildiyse ek gereksinimler şunlardır:

  • Anahtar kasasına erişmek için API Management örneğinin sistem tarafından atanan yönetilen kimliğini kullanmanız gerekir.

  • Key Vault güvenlik duvarında Güvenilen Microsoft Hizmetleri'nin bu güvenlik duvarını atlamasına izin ver seçeneğini etkinleştirin.

  • Azure API Management'a eklemek üzere bir sertifika veya gizli dizi seçerken yerel istemci IP adresinizin anahtar kasasına geçici olarak erişmesine izin verildiğinden emin olun. Daha fazla bilgi için bkz . Azure Key Vault ağ ayarlarını yapılandırma.

    Yapılandırmayı tamamladıktan sonra, anahtar kasası güvenlik duvarında istemci adresinizi engelleyebilirsiniz.

Sanal ağ gereksinimleri

API Management örneği bir sanal ağda dağıtıldıysa, aşağıdaki ağ ayarlarını da yapılandırın:

Ayrıntılar için bkz . Sanal ağda Azure API Management'ı ayarlarken ağ yapılandırması.

Adlandırılmış değer ekleme veya düzenleme

API Management'a anahtar kasası gizli dizisi ekleme

Bkz . Anahtar kasası tümleştirmesi için önkoşullar.

Önemli

API Management örneğinize bir anahtar kasası gizli dizisi eklerken, anahtar kasasından gizli dizileri listeleme izniniz olmalıdır.

Dikkat

API Management'ta anahtar kasası gizli dizisini kullanırken, anahtar kasasına erişmek için kullanılan gizli diziyi, anahtar kasasını veya yönetilen kimliği silmemeye dikkat edin.

  1. Azure portalında API Management örneğine gidin.

  2. API'ler'in altında Adlandırılmış değerler>+Ekle'yi seçin.

  3. Bir Ad tanımlayıcısı girin ve ilkelerde özelliğe başvurmak için kullanılan bir Görünen ad girin.

  4. Değer türü'nde Anahtar kasası'na tıklayın.

  5. Anahtar kasası gizli dizisinin tanımlayıcısını girin (sürüm olmadan) veya anahtar kasasından gizli dizi seçmek için Seç'i seçin.

    Önemli

    Kendiniz bir anahtar kasası gizli dizi tanımlayıcısı girerseniz, sürüm bilgilerinin olmadığından emin olun. Aksi takdirde, anahtar kasasındaki bir güncelleştirmeden sonra gizli dizi API Management'ta otomatik olarak döndürülmeyecektir.

  6. İstemci kimliği'nde sistem tarafından atanan veya mevcut kullanıcı tarafından atanan yönetilen kimliği seçin. API Management hizmetinizde yönetilen kimlikleri eklemeyi veya değiştirmeyi öğrenin.

    Not

    Kimlik, anahtar kasasından gizli dizileri almak ve listelemek için izinlere ihtiyaç duyar. Anahtar kasasına erişimi henüz yapılandırmadıysanız API Management, kimliği gerekli izinlerle otomatik olarak yapılandırabilmesini ister.

  7. Adlandırılmış değerlerinizi düzenlemenize yardımcı olması için isteğe bağlı bir veya daha fazla etiket ekleyin, ardından Kaydet'i seçin.

  8. Oluştur'u belirleyin.

    Anahtar kasası gizli dizi değeri ekleme

API Management'a düz veya gizli dizi değeri ekleme

  1. Azure portalında API Management örneğine gidin.
  2. API'ler'in altında Adlandırılmış değerler>+Ekle'yi seçin.
  3. Bir Ad tanımlayıcısı girin ve ilkelerde özelliğe başvurmak için kullanılan bir Görünen ad girin.
  4. Değer türü'nde Düz veya Gizli Dizi'yi seçin.
  5. Değer alanına bir dize veya ilke ifadesi girin.
  6. Adlandırılmış değerlerinizi düzenlemenize yardımcı olması için isteğe bağlı bir veya daha fazla etiket ekleyin, ardından Kaydet'i seçin.
  7. Oluştur'u belirleyin.

Adlandırılmış değer oluşturulduktan sonra adı seçerek düzenleyebilirsiniz. Görünen adı değiştirirseniz, adlandırılmış değere başvuran tüm ilkeler yeni görünen adı kullanacak şekilde otomatik olarak güncelleştirilir.

Adlandırılmış değer kullanma

Bu bölümdeki örneklerde aşağıdaki tabloda gösterilen adlandırılmış değerler kullanılır.

Veri Akışı Adı Değer Gizli dizi
ContosoHeader TrackingId False
ContosoHeaderValue •••••••••••••••••••••• True
ExpressionProperty @(DateTime.Now.ToString()) False
ContosoHeaderValue2 This is a header value. False

İlkede adlandırılmış bir değer kullanmak için, görünen adını aşağıdaki örnekte gösterildiği gibi gibi gibi {{ContosoHeader}}bir çift küme ayracı içine yerleştirin:

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

Bu örnekte, ContosoHeader bir ilkedeki set-header üst bilginin adı olarak kullanılır ve ContosoHeaderValue bu üst bilginin değeri olarak kullanılır. Bu ilke, API Management ağ geçidine {{ContosoHeader}} yönelik bir istek veya yanıt sırasında değerlendirildiğinde ve {{ContosoHeaderValue}} ilgili değerleriyle değiştirildiğinde.

Adlandırılmış değerler, önceki örnekte gösterildiği gibi tam öznitelik veya öğe değerleri olarak kullanılabilir, ancak aşağıdaki örnekte gösterildiği gibi değişmez metin ifadesinin bir bölümüne de eklenebilir veya birleştirilebilir:

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

Adlandırılmış değerler ilke ifadeleri de içerebilir. Aşağıdaki örnekte ifade ExpressionProperty kullanılmıştır.

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

Bu ilke değerlendirildiğinde değeri {{ExpressionProperty}} ile @(DateTime.Now.ToString())değiştirilir. Değer bir ilke ifadesi olduğundan, ifade değerlendirilir ve ilke yürütülmeye devam eder.

Bunu Azure portalında veya geliştirici portalında, kapsamda adlandırılmış değerler içeren bir ilkeye sahip bir işlemi çağırarak test edebilirsiniz. Aşağıdaki örnekte, adlandırılmış değerlere sahip önceki iki örnek set-header ilkeyle bir işlem çağrılır. Yanıtın adlandırılmış değerlerle ilkeler kullanılarak yapılandırılmış iki özel üst bilgi içerdiğine dikkat edin.

API yanıtlarını test edin

Adlandırılmış değerlere sahip önceki iki örnek ilkeyi içeren bir çağrının giden API izlemesine bakarsanız, adlandırılmış değerlerin eklendiği iki set-header ilkeyi ve ilke ifadesini içeren adlandırılmış değer için ilke ifadesi değerlendirmesini görebilirsiniz.

API Denetçisi izlemesi

Dize ilişkilendirmesi adlandırılmış değerlerle de kullanılabilir.

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

için CustomHeader değeri olacaktır The URL encoded value is This+is+a+header+value..

Dikkat

İlke Azure Key Vault'taki bir gizli diziye başvuruda bulunursa, anahtar kasasından alınan değer API isteği izleme için etkinleştirilmiş aboneliklere erişimi olan kullanıcılar tarafından görülebilir.

Adlandırılmış değerler ilke ifadeleri içerebilir ancak diğer adlandırılmış değerleri içeremez. Adlandırılmış değer başvurusu içeren metin gibi Text: {{MyProperty}}bir değer için kullanılıyorsa, bu başvuru çözümlenmez ve değiştirilmez.

Adlandırılmış değeri silme

Adlandırılmış değeri silmek için adı seçin ve ardından bağlam menüsünden (...) Sil'i seçin.

Önemli

Adlandırılmış değere herhangi bir API Management ilkesi tarafından başvurulursa, adlandırılmış değeri kullanan tüm ilkelerden kaldırana kadar silemezsiniz.

Sonraki adımlar