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. Tüm API yapılandırmaları ve ilkeleri genelinde sabit dize değerlerini ve gizli dizileri yönetmek için adlandırılmış değerleri kullanabilirsiniz.

Değer türleri

Türü	Açıklama
Düz	Literal dize veya ilke ifadesi
Gizli	API Management tarafından şifrelenmiş sabit dize 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ı kullanmanızı öneririz.

Uyarı

Şu anda bu senaryo için çalışma alanları anahtar kasası entegrasyonuna sahip değildir.

• Anahtar kasalarında depolanan gizlileri diğer hizmetlerde de kullanabilirsiniz.
• Gizli bilgilere ayrıntılı erişim politikaları uygulayabilirsiniz.
• Anahtar kasasında güncelleştirilen gizli diziler API Management'ta otomatik olarak döndürülür. Anahtar kasasında yapılan güncellemeden sonra, API Management'taki adlandırılmış bir değer dört saat içinde güncellenir. Ayrıca Azure portalını veya yönetim REST API'sini kullanarak gizli diziyi el ile yenileyebilirsiniz.

Uyarı

API Management bu sınırı aşan değerleri alamadığı için Azure Key Vault'ta depolanan gizli diziler 1 ile 4096 karakter arasında olmalıdır.

Önkoşullar

• Henüz bir API Management hizmet örneği oluşturmadıysanız bkz . Hızlı Başlangıç: Azure portalını kullanarak yeni bir Azure API Management örneği oluşturma.

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

Uyarı

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

• Henüz bir anahtar kasanız yoksa oluşturun. Anahtar kasası oluşturma adımları için bkz . Hızlı Başlangıç: Azure portalını kullanarak anahtar kasası oluşturma.

  Anahtar kasasına gizli dizi oluşturmak veya içeri aktarmak için bkz . Hızlı Başlangıç: Azure portalını kullanarak Azure Key Vault'tan gizli dizi ayarlama ve alma.

• API Management örneğinde sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği etkinleştirin.

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

1. Portaldaki anahtar kasanıza gidin.
2. Sol menüde Ayarlar>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, yönetilen kimliğinizin kaynak adını arayın ve İ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 Secrets Kullanıcısı'nı seçin, ardından İleri'ye tıklayın.
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.

• API Management örneğinizin anahtar kasasına yönelik ağ görüş hattına sahip olduğundan emin olun. Senaryolarınıza bağlı olarak, anahtar kasasında aşağıdaki ağ erişim seçeneklerinden birini yapılandırın:

  • Tüm ağlardan genel erişime izin verin.

  • IP adresine veya sanal ağ bağlantısına göre API Management trafiğine izin vermek için bir ağ güvenlik kuralı ayarlayın.

  • Özel Bağlantı bağlantısı ile API Management'tan gelen trafiğin güvenliğini sağlayın.

  • Anahtar kasanızın güvenliğini sağlamak ve API Management'tan gelen trafiğe izin vermek için bir ağ güvenlik çevresi kullanın.

• 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.

Önemli

Mart 2026'dan itibaren, Güvenilen Microsoft hizmetlerinin bu güvenlik duvarını atlamasına izin ver anahtar kasası güvenlik duvarı ayarını etkinleştirerek API Management üzerinden Azure Key Vault'a olan güvenli hizmet bağlantısı artık desteklenmeyecektir. Bu değişiklik sonrasında Key Vault'u API Management ile kullanmaya devam etmek için yukarıda açıklandığı gibi desteklenen bir ağ erişimi seçeneği belirlediğinizden emin olun. Daha fazla bilgi edinin.

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 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. Adlandırılmış değerlerinizi düzenlemenize yardımcı olması için isteğe bağlı bir veya daha fazla Etiket ekleyin.

5. Tür açılan listesinde Anahtar Kasası'nı seçin.

6. 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.

7. İ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.

8. Kaydet'i ve ardından Oluştur'u seçin.

   

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

Portal

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. Tür açılan listesinde Düz veya Gizli'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'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.

Azure CLI

Azure CLI'yi kullanmaya başlamak için:

• Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz. Azure Cloud Shell'i kullanmaya başlama.

  

• CLI referans komutlarını yerel olarak çalıştırmayı tercih ediyorsanız, Azure CLI'yi yükleyin. Windows veya macOS üzerinde çalışıyorsanız, Azure CLI'yi bir Docker konteynerinde çalıştırmayı düşünün. Daha fazla bilgi için Azure CLI'nin bir Docker konteynerında nasıl çalıştırılacağını inceleyin.

  • Yerel bir kurulum kullanıyorsanız, az login komutunu kullanarak Azure CLI'ye giriş yapın. Kimlik doğrulama işlemini tamamlamak için, terminalinizde görüntülenen adımları takip edin. Diğer oturum açma seçenekleri için bkz. Azure CLI kullanarak Azure'da kimlik doğrulaması.

  • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma ve yönetme.

  • Yüklü olan sürümü ve bağımlı kütüphaneleri bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

Adlandırılmış değer eklemek için az apim nv create komutunu kullanın. resource-group ve service-name değerleri için kendi kaynak grubu adınızı ve API Management örneği adınızı kullanın.

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

Adlandırılmış bir değer oluşturduktan sonra az apim nv update komutunu kullanarak değeri güncelleştirebilirsiniz . Tüm adlandırılmış değerlerinizi görmek için az apim nv list komutunu çalıştırın:

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Bu örnekte oluşturduğunuz adlandırılmış değerin ayrıntılarını görmek için az apim nv show komutunu çalıştırın:

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Bu örnek gizli bir değerdir. Önceki komut değeri döndürmez. Değerini görmek için az apim nv show-secret komutunu çalıştırın:

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Adlandırılmış bir değeri silmek için az apim nv delete komutunu kullanın:

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

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ğerleri önceki örnekte gösterildiği gibi tam öznitelik veya öğe değerleri olarak kullanabilirsiniz, ancak aşağıdaki örnekte gösterildiği gibi sabit 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.

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.

Adlandırılmış değerlerle dize ilişkilendirmesini de kullanabilirsiniz.

<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

Politika, Azure Key Vault'taki bir gizli öğeye referans veriyorsa, anahtar kasasından gelen 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ış bir 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

İlkelerle çalışma hakkında daha fazla bilgi edinin:

• API Management'ta ilkeler
• İlke başvurusu
• Politika ifadeleri