Aracılığıyla paylaş

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

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ırasıyla yürütülen ifadelerden oluşan bir koleksiyondur. İlke ifadeleri 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. 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

Türü Açıklama
Düz Literal dize veya ilke ifadesi
Gizli API Management tarafından şifrelenen metin dizesi veya ilke ifadesi
Anahtar kasası Azure anahtar kasasında depolanan gizlinin tanımlayıcısı.

Düz değerler veya gizli 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ı sırları

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ı sırlarının kullanılması önerilir.

  • Anahtar kasalarda depolanan gizli bilgiler hizmetler arasında kullanılabilir
  • Sırlara 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üncelleme yapıldıktan sonra, API Yönetimi içindeki belirli bir değer 4 saat içinde güncellenir. Ayrıca Azure portalını veya yönetim REST API'sini kullanarak gizli diziyi el ile yenileyebilirsiniz.

Uyarı

AZURE Key Vault'ta depolanan gizli diziler 1 ile 4096 karakter arasında olmalıdır çünkü API Management bu sınırı aşan değerleri alamaz.

Önkoşullar

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

Uyarı

Şu anda bu özellik çalışma alanlarında kullanılamaz.

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

  1. Portaldaki anahtar kasanıza gidin.
  2. Soldaki menüden Erişim yapılandırması'nı seçin. Yapılandırılan İzin modeline dikkat edin.
  3. İzin modeline bağlı olarak API Management yönetilen kimliği için ya bir anahtar kasası erişim ilkesini ya da Azure RBAC erişimini 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 izinler altında Getir ve Listele'yi ve ardından İleri'yi seçin.
  4. Sorumlu sekmesinde Sorumlu'ya tıklayın, yönetilen kimliğinizin kaynak adını arayın ve ardından İleri'yi seçin. Sistem tarafından atanan bir kimlik kullanıyorsanız, asıl kimlik API Yönetim ö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 Gizli Dizileri Kullanıcısı 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 firewall etkinleştirildiyse şu gereksinimleri karşılamanız gerekir:

  • Anahtar deposuna 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 anahtar seçerken, yerel istemci IP adresinizin anahtar kasasına geçici olarak erişimine 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:

  • API Management alt ağındaki Key Vault'a bir hizmet uç noktasını etkinleştirin.
  • AzureKeyVault ve AzureActiveDirectory hizmet etiketlerine giden trafiğe izin vermek için bir ağ güvenlik grubu (NSG) kuralı yapılandırın.

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

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

API Management'a anahtar kasasına bir gizli anahtar ekleme

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

Önemli

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

Dikkat

API Yönetimi'nde bir anahtar kasası gizli bilgisini kullanırken, anahtar kasasına erişmek için kullanılan gizli bilgiyi, 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 politikalarda özelliğe referans vermek için kullanılan bir Görünen ad girin.

  4. Değer türü'ndeAnahtar kasası'nı seçin.

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

    Önemli

    Anahtar kasası gizli tanımlayıcısını kendiniz girerseniz, sürüm bilgisinin 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.

    Uyarı

    Kimlik, anahtar kasadaki sırları erişmek ve listelemek için izinlere ihtiyaç duyar. Anahtar kasasına erişimi henüz yapılandırmadıysanız, API Management gerekli izinlerle kimliği otomatik olarak yapılandırabilmek için sizi bilgilendirir.

  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'i seçin.

    Anahtar kasası gizli değer ekleme

API Yönetimi'ne açık veya gizli bir değer ekleyin

  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 politikalarda özelliğe referans vermek için kullanılan bir Görünen ad girin.
  4. Değer türü'ndeDüz veya Gizli 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'i seçin.

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.

İsim Değer Gizli
ContosoHeader TrackingId Yanlış
ContosoHeaderValue •••••••••••••••••••••• Doğru
İfadeÖzelliği @(DateTime.Now.ToString()) Yanlış
ContosoHeaderValue2 This is a header value. Yanlış

İlkede adlandırılmış bir değer kullanmak için, görünen adını aşağıdaki örnekte gösterildiği 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 yönelik bir istek veya yanıt sırasında değerlendirildiğinde, {{ContosoHeader}} ve {{ContosoHeaderValue}} ilgili değerleriyle değiştirilir.

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 belirtilmiş değerlerle politikalar 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 İnceleyici İzleme

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.

İlgili içerik